Jx.Grid

Extends: Object

Implements: Options, Events, Jx.Addable

A tabular control that has fixed scrolling headers on the rows and columns like a spreadsheet.

Jx.Grid is a tabular control with convenient controls for resizing columns, sorting, and inline editing. It is created inside another element, typically a div. If the div is resizable (for instance it fills the page or there is a user control allowing it to be resized), you must call the resize() method of the grid to let it know that its container has been resized.

When creating a new Jx.Grid, you can specify a number of options for the grid that control its appearance and functionality.

Jx.Grid renders data that comes from an external source. This external source, called the model, must implement the following interface.

Example

License

This file is licensed under an MIT style license

Summary

Jx.Grid	Extends: Object
Options
parent	the HTML element to create the grid inside.
alternateRowColors	defaults to false.
rowHeaders	defaults to false.
columnHeaders	defaults to false.
rowSelection	defaults to false.
columnSelection	defaults to false.
cellPrelight	defaults to false.
rowPrelight	defaults to false.
columnPrelight	defaults to false.
rowHeaderPrelight	defaults to false.
columnHeaderPrelight	defaults to false.
cellSelection	defaults to false.
Constructor
Jx.Grid	construct a new instance of Jx.Grid within the domObj
Functions
onScroll	handle the grid scrolling by updating the position of the headers
resize	resize the grid to fit inside its container.
TODO
Jx.Grid.resize	if not showing column or row, should we handle the resize differently
Functions
setModel	set the model for the grid to display.
destroyGrid	destroy the contents of the grid safely
createGrid	create the grid for the current model
setRowHeaderHeight	set the height of a row.
gridChanged	called through the grid listener interface when data has changed in the underlying model
prelightRowHeader	apply the jxGridRowHeaderPrelight style to the header cell of a row.
prelightColumnHeader	apply the jxGridColumnHeaderPrelight style to the header cell of a column.
prelightRow	apply the jxGridRowPrelight style to row.
prelightColumn	apply the jxGridColumnPrelight style to a column.
TODO
Jx.Grid.prelightColumn	Not Yet Implemented.
Jx.Grid.prelightColumn	implement column prelighting (possibly)
Functions
prelightCell	apply the jxGridCellPrelight style to a cell.
selectCell	Select a cell and apply the jxGridCellSelected style to it.
selectRowHeader	Apply the jxGridRowHeaderSelected style to the row header cell of a selected row.
selectRow	Select a row and apply the jxGridRowSelected style to it.
selectColumnHeader	Apply the jxGridColumnHeaderSelected style to the column header cell of a selected column.
selectColumn	Select a column.
TODO
implement column selection
Functions
onMouseMoveGrid	handle the mouse moving over the main grid.
onMouseMoveRowHeader	handle the mouse moving over the row header cells.
onMouseMoveColumnHeader	handle the mouse moving over the column header cells.
onClickGrid	handle the user clicking on the grid.
onClickRowHeader	handle the user clicking on the row header.
onClickColumnHeader	handle the user clicking on the column header.
getRowColumnFromEvent	retrieve the row and column indexes from an event click.

Options

parent

the HTML element to create the grid inside. The grid will resize to fill the domObj.

alternateRowColors

defaults to false. If set to true, then alternating CSS classes are used for rows.

rowHeaders

defaults to false. If set to true, then a column of row header cells are displayed.

columnHeaders

defaults to false. If set to true, then a column of row header cells are displayed.

rowSelection

defaults to false. If set to true, allow the user to select rows.

columnSelection

defaults to false. If set to true, allow the user to select columns.

cellPrelight

defaults to false. If set to true, the cell under the mouse is highlighted as the mouse moves.

rowPrelight

defaults to false. If set to true, the row under the mouse is highlighted as the mouse moves.

columnPrelight

defaults to false. If set to true, the column under the mouse is highlighted as the mouse moves.

rowHeaderPrelight

defaults to false. If set to true, the row header of the row under the mouse is highlighted as the mouse moves.

columnHeaderPrelight

defaults to false. If set to true, the column header of the column under the mouse is highlighted as the mouse moves.

cellSelection

defaults to false. If set to true, allow the user to select cells.

Constructor

Jx.Grid

construct a new instance of Jx.Grid within the domObj

Parameters

options

Jx.Grid.Options

Functions

onScroll

onScroll: function()

handle the grid scrolling by updating the position of the headers

resize

resize: function()

resize the grid to fit inside its container. This involves knowing something about the model it is displaying (the height of the column header and the width of the row header) so nothing happens if no model is set

TODO

Jx.Grid.resize

if not showing column or row, should we handle the resize differently

Functions

setModel

setModel: function( model )

set the model for the grid to display. If a model is attached to the grid it is removed and the new model is displayed.

Parameters

model

{Object} the model to use for this grid

destroyGrid

destroyGrid: function()

destroy the contents of the grid safely

createGrid

createGrid: function()

create the grid for the current model

setRowHeaderHeight

setRowHeaderHeight: function( row,
height )

set the height of a row. This is used internally to adjust the height of the row header when cell contents wrap. A limitation of the table structure is that overflow: hidden on a td will work horizontally but not vertically

Parameters

row	{Integer} the row to set the height for
height	{Integer} the height to set the row (in pixels)

gridChanged

gridChanged: function( model,
row,
col,
value )

called through the grid listener interface when data has changed in the underlying model

Parameters

model	{Object} the model that changed
row	{Integer} the row that changed
col	{Integer} the column that changed
value	{Mixed} the new value

prelightRowHeader

prelightRowHeader: function( row )

apply the jxGridRowHeaderPrelight style to the header cell of a row. This removes the style from the previously pre-lit row header.

Parameters

row	{Integer} the row to pre-light the header cell of

prelightColumnHeader

prelightColumnHeader: function( col )

apply the jxGridColumnHeaderPrelight style to the header cell of a column. This removes the style from the previously pre-lit column header.

Parameters

col	{Integer} the column to pre-light the header cell of

prelightRow

prelightRow: function( row )

apply the jxGridRowPrelight style to row. This removes the style from the previously pre-lit row.

Parameters

row	{Integer} the row to pre-light

prelightColumn

apply the jxGridColumnPrelight style to a column. This removes the style from the previously pre-lit column.

Parameters

col	{Integer} the column to pre-light

TODO

Jx.Grid.prelightColumn

Not Yet Implemented.

Jx.Grid.prelightColumn

implement column prelighting (possibly)

Functions

prelightCell

prelightCell: function( row,
col )

apply the jxGridCellPrelight style to a cell. This removes the style from the previously pre-lit cell.

Parameters

row	{Integer} the row of the cell to pre-light
col	{Integer} the column of the cell to pre-light

selectCell

selectCell: function( row,
col )

Select a cell and apply the jxGridCellSelected style to it. This deselects a previously selected cell.

If the model supports cell selection, it should implement a cellSelected function to receive notification of the selection.

Parameters

row	{Integer} the row of the cell to select
col	{Integer} the column of the cell to select

selectRowHeader

selectRowHeader: function( row,
selected )

Apply the jxGridRowHeaderSelected style to the row header cell of a selected row.

Parameters

row	{Integer} the row header to select
selected	{Boolean} the new state of the row header

selectRow

selectRow: function( row,
selected )

Select a row and apply the jxGridRowSelected style to it.

If the model supports row selection, it should implement a rowSelected function to receive notification of the selection.

Parameters

row	{Integer} the row to select
selected	{Boolean} the new state of the row

selectColumnHeader

selectColumnHeader: function( col,
selected )

Apply the jxGridColumnHeaderSelected style to the column header cell of a selected column.

Parameters

col	{Integer} the column header to select
selected	{Boolean} the new state of the column header

selectColumn

selectColumn: function( col,
selected )

Select a column. This deselects a previously selected column.

Parameters

col	{Integer} the column to select
selected	{Boolean} the new state of the column

TODO

implement column selection

Functions

onMouseMoveGrid

onMouseMoveGrid: function( e )

handle the mouse moving over the main grid. This pre-lights the cell, and subsquently the row and column (and headers).

Parameters

e	{Event} the browser event object

onMouseMoveRowHeader

onMouseMoveRowHeader: function( e )

handle the mouse moving over the row header cells. This pre-lights the row and subsequently the row header.

Parameters

e	{Event} the browser event object

onMouseMoveColumnHeader

onMouseMoveColumnHeader: function( e )

handle the mouse moving over the column header cells. This pre-lights the column and subsequently the column header.

Parameters

e	{Event} the browser event object

onClickGrid

onClickGrid: function( e )

handle the user clicking on the grid. This triggers an event to the model (if a cellSelected function is provided).

The following is an example of a function in the model that selects a row when the cellSelected function is called and deselects any rows that are currently selected.

cellSelected: function(grid, row,col) {
   if (this.selectedRow != null) {
       grid.selectRow(this.selectedRow, false);
   }
   this.selectedRow = row;
   grid.selectRow(row, true);
}

Parameters:
e - {Event} the browser event object

onClickRowHeader

onClickRowHeader: function( e )

handle the user clicking on the row header. This triggers an event to the model (if a rowSelected function is provided) which can then select the row if desired.

The following is an example of a function in the model that selects a row when the rowSelected function is called and deselects any rows that are currently selected. More complex code could be written to allow the user to select multiple rows.

rowSelected: function(grid, row) {
   if (this.selectedRow != null) {
       grid.selectRow(this.selectedRow, false);
   }
   this.selectedRow = row;
   grid.selectRow(row, true);
}

Parameters

e	{Event} the browser event object

onClickColumnHeader

onClickColumnHeader: function( e )

handle the user clicking on the column header. This triggers column selection and column (and header) styling changes and an event to the model (if a columnSelected function is provided)

The following is an example of a function in the model that selects a column when the columnSelected function is called and deselects any columns that are currently selected. More complex code could be written to allow the user to select multiple columns.

colSelected: function(grid, col) {
   if (this.selectedColumn != null) {
       grid.selectColumn(this.selectedColumn, false);
   }
   this.selectedColumn = col;
   grid.selectColumn(col, true);
}

Parameters

e	{Event} the browser event object

getRowColumnFromEvent

getRowColumnFromEvent: function( e )

retrieve the row and column indexes from an event click. This function is used by the grid, row header and column header to safely get these numbers.

If the event isn’t valid (i.e. it wasn’t on a TD or TH) then the returned values will be -1, -1

Parameters

e	{Event} the browser event object

@return Object an object with two properties, row and column, that contain the row and column that was clicked