Grid cursor - focused cell and row

TreeGrid documentation

By default there can be only one focused cell and only the focused cell can be edited. The focused cell is accessible for API by FRow and FCol.

To permit focusing cell range by mouse dragging, attach FocusCells action to some drag event, e.g. <Actions OnDragRow="FocusCells"/>. The range is accessible to API by FRect.

To show bottom right corner in the border cursor, add Corner flag to row FocusCell attribute, e.g. <Def><D Name="R" FocusCell="Border,Color,Class,Corner"/></Def>

To permit editing different cell than the focused one, attach StartEditCell or StartEditCellEmpty action to some event, e.g. <Actions OnCtrlClickCell="StartEditCell"/>. The edited cell is accessible for API by ERow and ECol.

Note, focused cell is not selected cell. For selecting cells or rows see Selecting rows and cells. Focused cells can be automatically selected by setting <Cfg SelectingFocus='2'/>
If set to 1, grid does not delete cursor when it looses focus - after click outside grid.
After click outside the grid, it looses focus and the cursor cannot be changed by keys.

To not let grid loosing its focus after click outside, you can suppress the action by <Actions OnClickOutside='0'/> instead of setting StaticCursor.
In this case the arrow keys will control the grid cursor even if user edits some other input on page - you need to cancel bubbling of onkeydown in such input.
If set, does not show cursor for the cell, only for row.
For this case should be set also <Cfg Editing='0'/>.
If row or cell can be focused - the grid cursor can be placed to this place.
The not focusable cell cannot be edited except Bool and Radio types.
If user clicks to not focusable row, the cursor position is not changed at all.
If user click to not focusable cell in focusable row, it is focused the clicked row and the cell in previously focused column.
When user moves cursor by arrow keys, the not focusable cells are skipped.
Since 7.0 arrow keys skip also cells with CanFocus='2'.

The routine to find out if the cell is focusable checks these points in this order:
1) Checks cell CanFocus, if it set, returns it
2) Checks row CanFocus, if it set, returns it
3) Checks column CanFocus, if it set, returns it
4) Returns 0 for cell types Panel, Button and Select, for other types returns 1.
If cell can be focused. Tests all CanFocus attributes.
An id of focused row to focus it on start on or reload.
When used server paging, it can be id or position of page with focused row and FocusedPos is set to the row position.
This attribute is also sent to server in request for data to change the focused row from server and contains actual FRow.
Name of focused column to focus it on start on or reload.
This attribute is also sent to server in request for data to change the focused row from server and contains actual FCol.
Specifies position (from 0) of focused row at page when used Focused attribute with server paging.
In tree it includes all expanded rows' children.
This attribute is also sent to server in request for data to change the focused row from server and contains actual FPagePos.
Flags to control Focused attribute. Bit array.
1. bit, &1 - If set, does not scroll to focused area on start. Ignores attribute Focused sent from server. Has sense especially when used TreeGrid server library.
If set, automatically selects focused area. If set to 2 it also selects focused single cell.
After every focused cell / focused area change clears all selected cells in grid.
Must be set also Selecting and SelectingCells.
Actually focused row in grid or null. The grid cursor.
It can be a page when there is focused row on not yet loaded page in server paging.
Actually focused column in grid or null. The grid cursor.
If FRow is not yet rendered page in server paging, there is index (from 0) of focused row on this page.
In tree it includes all expanded rows' children.
Actually edited row in grid or null. It is usually the same as FRow.
Actually edited column in grid or null. It is usually the same as FCol.
Called as <Actions> or cell event when the cell is focused.
Attach the action or any JavaScript code to the cell to be run on focus, like <I ... Col1OnFocus='alert("focused!" )' ... />
Called when cell is focused, row, col is actual (new) focused cell.
orow, ocol is previously focused cell. All rows and cols parameters can be nulls.
pagepos is not null if row is not rendered page or row with children, in this case it is position on the page. If server paging is not used, it is always null.
rect (since 11.0) is new focused rectangle, if focused more cells. orect (since 11.0) is previously focused rectangle.
Focusing is moving cursor to row's cell. By mouse click or by arrow keys or by tab key. Don't confuse selecting and focusing row.
Called when grid loses focus.
orow, ocol is previously focused cell. orect is previously focused rectangle.
Focuses the cell or cell range.
If grid was in edit mode, saves changed value in the edited cell.
Returns true, if cell or cell range has been focused. Returns false if the cell or cell range is already focused. Returns null if the cell cannot be focused. For cell range it checks if can be focused only the two corner cells.
If row is page, focuses cell on page on pagepos position after page renders (asynchronously). If server paging is not used, pagepos is ignored.
If row is null, defocuses grid. If col is null, focuses the whole row.
(new 11.0) rect can be an rectangle area as [TRow toprow, string leftcol, TRow bottomrow, string rightcol, int toppagepos, int bottompagepos] to focus it, as FRect. This area must contain the row, col cell.
(new 11.0) type is bit array to control the function behavior.
Remember, if you will call the Focus method from onclick event of some external button, you need to call it in setTimeout or cancel the click event, otherwise grid loses focus due the click to button.
Actually focused grid. This grid catches key events.
If you want to process key events in other controls, set it to null.
Focuses actual cell => moves cursor to cell under mouse cursor.
The grid will receive key events.
It fails if cell cannot be focused.
By default it is attached to events OnClickCell, OnClickEditEnum, OnDblClickCell,
OnClickSideDefaults, OnClickSideDate, OnClickSideFilter, OnClickExpand, OnClickEditBool, OnjClickEditRadio, OnClickLink
Focuses actual cell => moves cursor to cell under mouse cursor. The grid will receive key events.
And starts editing according to InEditMode setting.
It fails if the focus cannot be changed or start edit the cell. It also fails if cell is already focused or cannot be focused.
To only start editing cell without focusing it use StartEditCell.
Focuses actual cell => moves cursor to cell under mouse cursor. The grid will receive key events.
And starts editing the cell regardless on the EditMode settings.
It fails if the focus cannot be changed or start edit the cell. It also fails if cell is already focused or cannot be focused.
Focuses actual cell => moves cursor to cell under mouse cursor.
The grid will receive key events.
It fails if cell is already focused or cannot be focused.
Focuses cell in actual row and focused column. If the cell cannot be focused, focuses only row.
The grid will receive key events.
It fails if the row cannot be focused.
Since 7.0 whole Space rows cannot be focused, only their cells.
Focuses cell in focused row and actual column.
The grid will receive key events.
It fails if the cell cannot be focused or the focused or actual row Space row.
Defocuses grid and hides cursor if it is not set as StaticCursor.
The grid will not receive key events.
Defocuses grid and hides cursor if it is not set as StaticCursor.
The grid will not receive key events.
Fails, if the actual cell is not focused.

Focused cell range

To permit focusing cell range by mouse dragging, attach FocusCells action to some drag event, e.g. <Actions OnDragRow="FocusCells"/>. The range is accessible to API by FRect.
To show bottom right corner in the border cursor, add Corner flag to row FocusCell attribute, e.g. <Def><D Name="R" FocusCell="Border,Color,Class,Corner"/></Def>
If and how it is possible to focus and modify more cells. Bit array.

1. bit	&1	Permits focusing cell range.
2. bit	&2	Shows the right bottom corner in the focus cursor, for auto fill. Adds the "Corner" to all FocusCell attributes.
3. bit	&4	Does not show focus cursor for the whole row. Sets FocusRow = "" for all cells.
4. bit	&8	Shows the focused cell cursor with relative color instead of absolute to not hide the cell background.
8. bit	&16	Assigns MoveFocus, MoveFocusValues , CopyFocus and CopyFocusValues actions for dragging the focus border. Sets: <Actions OnDragLeftEdge="MoveFocus" OnDragRightEdge="MoveFocus" OnDragTopEdge="MoveFocus" OnDragBottomEdge="MoveFocus"/> <Actions OnCtrlDragLeftEdge="CopyFocus" OnCtrlDragRightEdge="CopyFocus" OnCtrlDragTopEdge="CopyFocus" OnCtrlDragBottomEdge="CopyFocus"/> <Actions OnShiftDragLeftEdge="MoveFocusValues" OnShiftDragRightEdge="MoveFocusValues" OnShiftDragTopEdge="MoveFocusValues" OnShiftDragBottomEdge="MoveFocusValues"/> <Actions OnShiftCtrlDragLeftEdge="CopyFocusValues" OnShiftCtrlDragRightEdge="CopyFocusValues" OnShiftCtrlDragTopEdge="CopyFocusValues" OnShiftCtrlDragBottomEdge="CopyFocusValues"/>

Focused area set to FRect as "toprowid,leftcol,bottomrowid,bottomcol,toppagepos,bottompagepos"
Focused rectangle of cells, if there are more cells focused.
It is array as [TRow toprow, string leftcol, TRow bottomrow, string rightcol, int toppagepos, int bottompagepos]
The FRect area always includes the FRow, FCol cell.
To permit focusing more cells by dragging, set e.g. <Actions OnDragRow="FocusCells"/>
Returns all actually focused rows, type is bit array as:
type = &1 with collapsed children, &2 from the same page as the first focused row, &4 from the same tree level as the first focused row.
If set attr, returns only rows with this attribute set, e.g. "CanDelete"
Returns all actually focused columns.
Returns true if the cell is focused.
Focuses actual cell and starts resizing the focus cursor to rectangle area of cells.
Since 12.0 it fails if FocusRect is not set.
Focuses actual cell and starts resizing the focus cursor horizontally to more cells in the focused row.
In versions prior 11.0 was FocusRow action with different meaning, now renamed to ChangeFocusRow. The FocusRow still works in this way if attached in non OnDrag event.
Since 12.0 it fails if FocusRect is not set.
Focuses actual cell and starts resizing the focus cursor vertically to more cells in the focused column.
Since 12.0 it fails if FocusRect is not set.
Focuses actual cell and starts resizing the focus cursor horizontally or vertically to rectangle area of cells. The direction is chosen by the larger destination from the source point.
Since 12.0 it fails if FocusRect is not set.
Focuses cell range between actual and focused cell.
Focuses all cells in the actual or focused row. Since 12.0 added the F suffix.
Since 12.0 it fails if FocusRect is not set.
Focuses all cells in the actual or focused column. It fails if FocusRect is not set.
Focuses all cells in the grid. It fails if FocusRect is not set.
Extends the focused range to the first focusable cell below the actually focused cell.
It fails if there is no next focusable cell below.
Extends the focused range to the first focusable cell above the actually focused cell.
It fails if there is no next focusable cell above.
Extends the focused range to the first focusable cell right to the actually focused cell.
It fails if there is no next focusable cell or no row is focused.
Extends the focused range to the first focusable cell left to the actually focused cell.
It fails if there is no previous focusable cell or no row is focused.

Move and copy focused cells

To move or copy focused cell or cell range by dragging, set such or similar event handlers:
How the MoveFocus will move the cell values. Bit array.

1. bit	&1	Fills the destination focused area by source cells' values.
2. bit	&2	Clears the source cells.
3. bit	&4	Does not move focus of single cell.
4. bit	&8	Fills only empty cells.
5. bit	&16	(new 12.0)Ignore span during move.

Moves focused cell or focused area to new location by mouse. Preserves count of rows and column in the focused area. Moves cell attributes listed in EditAttrs.
Usually attached to OnDragLeftEdge / OnDragRightEdge / OnDragTopEdge / OnDragBottomEdge events to move the focus by dragging its edge like in MS Excel. It is attached automatically, if set FocusRect & 8
You can set also <Cfg FocusCellBorderCursor='1'/> to show move mouse cursor above the focused cell border.
Moves focused cell or focused area to new location by mouse.
Like MoveFocus, but moves only values and EFormula or attributes listed in EditAttrsValue.
Moves focused cell or focused area to new location by mouse.
Like MoveFocus, but moves only cell attributes except value and EFormula or attributes listed in EditAttrsStyle.
Copies focused cell or focused area to new location by mouse. The same as MoveFocus with MoveFocusType without 2.
It is attached automatically for dragging with Ctrl, if set FocusRect & 8
Copies focused cell or focused area to new location by mouse.
Like CopyFocus, but copies only values and EFormula or attributes listed in EditAttrsValue.
Copies focused cell or focused area to new location by mouse.
Like CopyFocus, but copies only cell attributes except value and EFormula or attributes listed in EditAttrsStyle.
Copies given source range to destination range. If set clear, clears the source range.
The range is [TRow row1, string col1, TRow row2, string col2]
Called after moving focus is finished and before MoveFocusType action is applied.
Return true to restore original focus and cancel the action.
Return integer to be used instead of MoveFocusType action and continue.
Return null to continue.
rect is new focused rect, the same as FRect. For single cell it is [FRow,FCol,FRow,FCol]
orect is original focused rect, the original value of FRect. For single cell it is [FRow,FCol,FRow,FCol] from original values.
Values is array of values of source cells to be filled to into destination cells if set MoveFocusType&1. The values can be changed in this event.
Rows, Cols are destination cells, SourceRows, SourceCols are source cells.
Called for every cell in moved area when moving focus, depending on MoveFocusType.
It is called when copying the destination cell from [orow,ocol] to [row,col].
It is called for source cell when clearing it (the orow and ocol are nulls in this case).
If the cell is in both source and destination areas, it is called only for copying. For copying it is called before for clearing.
Return value to fill or value. Or since 12.0 return oldvalue as original value to not set the value to the cell.
Since 12.0, attrvalues are values that will be set to cell attributes their names are in attrnames. It is possible to modify the values in attrvalues, but not in attrnames.
Since 12.0, for errors see OnEditErrors API event.
Called after move focus, after the cells are moved or cleared.
Parameters are the same as in OnMoveFocus, but it is useless to change them here.

Fill cell values by dragging

A user can fill cell values by mouse dragging.
To show bottom right corner in the border cursor, add Corner flag to row FocusCell attribute, e.g. <Def><D Name="R" FocusCell="Border,Color,Class,Corner"/></Def>
Or set <Actions OnDragCell='FillCells'/> or similarly to different drag action, e.g <Actions OnCtrlDragCells='FillCells'/> to fill by the first cell only.
By default the value of the source cells are just copied to the other cells. You can change this behavior by AutoFillType or use OnAutoFileValues or OnAutoFillValue event.
Flags how the auto fill actions will fill the cells, bit array.

1. bit	&1	If set, the source cell values will be copied in the filling direction.
2. bit	&2	If set, the filled numbers can be calculated as in numeric sequence. Only if there is constant increase/decrease.
		Only if filled in one direction. Only if the source area contains at least two cells in the filling direction.
3. bit	&4	If set and the fill area is smaller than source area, the rest of source area will be cleared.
4. bit	&8	(new 12.0) If set, permits calculated filling also from one cell in the filling direction by step 1.
5. bit	&16	(new 12.0) If set, permits calculated filling also string values ending by number, increasing that number.

Starts filling cell values by the focused cell or focused cell range. It fills only horizontally or vertically, the direction is chosen by the larger destination from the source point, like in MS Excel.
The cell focus corner like in MS Excel can be shown by adding Corner flag to the FocusCell.
Starts filling cell values by the focused cell or focused cell range. It fills to all cells the focused cell value or values in focused cell range repeatedly.
The cell focus corner like in MS Excel can be shown by adding Corner flag to the FocusCell.
Starts filling cell values by the focused cell or focused cell range. It fills only horizontally.
Starts filling cell values by the focused cell or focused cell range. It fills only vertically.
Starts filling cell values by the actual cell value. It fills to all cells the actual cell value.
Starts filling cell values by the actual cell value. It fills only vertically.
Starts filling cell values by the actual cell value. It fills only horizontally.
Fills destination range according to the source range according to the type, see AutoFillType.
The destination range must contain the source range or vice versa.
Called after cell range is selected by used in action FillCells/Row/Col and FocusFillCells/Row/Col, before the standard filling is done.
It is called directly before OnAutoFill event. Since 11.0 it is preferred to use instead of OnAutoFill event.
Values is two dimensional array as Values[rowidx][colidx] of values to be set to cells in Rows[rowidx],Cols[colidx].
Values contain already calculated values. They can be changed in this event to fill different values.
The direction of Values/Rows/Cols is in the direction of filling - they can are reversed to position in grid if rdir or cdir is true.
orcnt / ocnt is size of source area. Source area is always in beginning of Values/Rows/Cols.
rnct / ccnt is size of filling area including source area. If set AutoFillType&2, it can be even smaller than source area.
rdir is vertical direction - 0 go down, 1 go up; cdir is horizontal direction - 0 go right, 1 go left.
Return true to cancel the action - no filling will be done.
Called after cell range is selected by used in action FillCells/Row/Col and FocusFillCells/Row/Col, before the standard filling is done.
It is called directly after OnAutoFillValues event. Since 11.0 it is preferred to use OnAutoFillValues event instead.
r1, c1, r2, c2 is the selected cell range. r1,c1 is always the firstly clicked cell.
rdir is vertical direction - 0 when r2 is under r1 and 1 if r2 is above r1.
cdir is horizontal direction - 0 when c2 is right from c1 and 1 when c2 is left from c1.
r1, c1, ro, co (new 11.0) is the originally selected range, often only one cell.

For example if original focused rectangle was [R2,C5 - R3, C7] and it was extended to fill the rectangle [R2,C5 - R8,C12], the OnAutoFill will be called as:


This function can be used to do to any operation in cell range created by dragging.
Return true to suppress default behavior. If returns true, the OnAutoFillValue and OnAutoFillFinish are not called.
Called after filling is finished. The arguments are the same as in OnAutoFill.
Called when automatically filling cell values selected by dragging in action FillCells/Row/Col and FocusFillCells/Row/Col, like in Excel.
It is called for every cell in the range to get its new value.
row, col is cell to fill; orow, ocol is base cell (the first cell dragged); val is predefined value to be filled.
prevval is previously filled (returned) value, for the base cell is null.
rowpos, colpos is distance from the actual cell from the base cell = base cell has 0,0. rowpos is negative when filling up and colpos when filling left.
orow, ocol, orow2, ocol2 (new 11.0) is the base selected cell range, often only one cell.
Return new value or val. Or since 12.0 return oldval as original value to not set the val to the cell.
For example: Grids.OnAutoFillValue=function(G,row,col,orow,ocol,val,old,ri,ci){return val+ri+ci;} - fills with increased values right down and decreased top left.
Since 12.0, attrvalues are values that will be set to cell attributes their names are in attrnames. It is possible to modify the values in attrvalues, but not in attrnames.
Since 12.0, for errors see OnEditErrors API event.

Tabulator navigation

TreeGrid supports tabulator navigation (tab & shift+tab) inside grid and also from another control to grid and from grid to another control.
If and how the grid is included in page tab order.
If set, the grid is accessible by tab key from other inputs on page - the first or the last cell in grid becomes focused.
If set to 1, the cell is just focused, if set to 2, it also starts editing the cell.
If set TabStop, you can also set the exact TabIndex to place the grid into specific position in the page tab order. Similar to HTML tabindex attribute.
Focuses the first focusable cell left to the actual focused cell. If there is none in the row, continues up, from right.
If there is no focused cell in grid, it focuses the first bottom right focusable cell.
Returns false if there is no previous cell to focus.
If returns false and is set TabStop, it focuses the previous control above the grid.
Remember, if you want to focus the previous control, the OnShiftTab event must return 0, otherwise it should return 1.
If set FRect, it navigates only inside this area.
Focuses the first focusable cell right to the actual focused cell. If there is none in the row, continues down, from left.
If there is no focused cell in grid, it focuses the first top left focusable cell.
Returns false if there is no next cell to focus.
If returns false and is set TabStop, it focuses the next control below the grid.
Remember, if you want to focus the previous control, the OnTab event must return 0, otherwise it should return 1.
If set FRect, it navigates only inside this area.
The same as TabRight, but adds new row if no next variable row is available.
The same as TabLeft but goes to the editable cell.
The same as TabRight but goes to the editable cell.
The same as TabRight but goes to the editable cell and adds new row if no next variable row is available.
Focuses the first focusable cell above the actual focused cell. If there is none in the column, continues left, from bottom.
If there is no focused cell in grid, it focuses the first bottom right focusable cell.
Returns false if there is no previous cell to focus.
If set FRect, it navigates only inside this area.
Note, the TabStop is not used in this event.
Focuses the first focusable cell below the actual focused cell. If there is none in the column, continues right, from top.
If there is no focused cell in grid, it focuses the first top left focusable cell.
Behaves like Enter in MS Excel.
Returns false if there is no previous cell to focus.
If set FRect, it navigates only inside this area.
Note, the TabStop is not used in this event.
The same as TabUp but goes to the editable cell.
The same as TabDown but goes to the editable cell.

Key navigation

TreeGrid supports key navigation inside the grid by arrows, PageUp / PageDown, Home / End.
Behavior of any key can be changed by attaching chosen event handler in <Actions/> tag.
Called when a user hold down key in focused grid.
It is called for every key, even for all functional keys like ESC or arrow keys.
key is Unicode code of the character key pressed or key code for functional key.
event is JavaScript key event generated in onkeydown.
name is key name set in <Actions> tag, e.g. "A", "D3", "Esc" or "Right".
prefix is shift key prefix - "Shift", "Alt", "Ctrl", "ShiftAlt", "ShiftCtrl", "CtrlAlt", "ShiftCtrlAlt".
Return true to suppress default action.
Called when a user presses key in focused grid.
It is called after OnKeyDown, see the parameters here.
In some browsers (IE, Safari) it is called only for character keys, in other browsers (Mozilla, Opera) it is called for all keys.
Return true to suppress default action.
Called when a user releases key in focused grid.
See the parameters in OnKeyDown,
Return true to suppress default action.
Focuses the first focusable cell below the actually focused cell. If there is no focused cell, focuses the first left top cell.
It fails if there is no next focusable cell below.
Focuses the first focusable cell below the actually focused cell. If there is no focused cell, focuses the first left top cell.
If there is no next focusable cell below in variable row it adds new row and moves focus here.
Focuses the first focusable cell above the actually focused cell. If there is no focused cell, focuses the first left bottom cell.
It fails if there is no next focusable cell above.
Focuses the first focusable cell right to the actually focused cell.
It fails if there is no next focusable cell or no row is focused.
Focuses the first focusable cell left to the actually focused cell.
It fails if there is no previous focusable cell or no row is focused.
Focuses the first focusable variable row in actually focused column. Focuses the last focusable variable row in actually focused column.
Focuses the same row on the next page or the last row. It does not change focused column except the cell in the new row is not focusable.
When one page is visible (<Cfg AllPages='0'/>) just focuses to the next page on the same position.
When all pages are visible or no paging is set, it scrolls down for the count of visible rows.
Focuses the same row on the previous page or the first row. It does not change focused column except the cell in the new row is not focusable.
When one page is visible (<Cfg AllPages='0'/>) just focuses to the previous page on the same position.
When all pages are visible or no paging is set, it scrolls up for the count of visible rows.
Like PageDown, but preserves the focused row relative to the page - it does not focus last row on last page as the last step.
Like PageUp, but preserves the focused row relative to the page - it does not focus first row on first page as the last step.
Focuses the first editable cell below the actually focused cell. If there is no focused cell, focuses the first left top cell.
It fails if there is no next editable cell below.
Focuses the first editable cell below the actually focused cell. If there is no focused cell, focuses the first left top cell.
If there is no next editable cell below in variable row it adds new row and moves focus here.
Focuses the first editable cell above the actually focused cell. If there is no focused cell, focuses the first left bottom cell.
It fails if there is no next editable cell below.
Focuses the first editable cell right to the actually focused cell.
It fails if there is no next editable cell or no row is focused.
Focuses the first editable cell left to the actually focused cell.
It fails if there is no previous editable cell or no row is focused.