TreeGrid v6.0
Grid cursor – focused cell and row
<Cfg> bool StaticCursor [0] .
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.
<Cfg> int FocusWholeRow [0] .
If set, does not show cursor for the cell, only for row.
For this case should be set also <Cfg Editing=’0’/>
<C> <I> <cell> int CanFocus [0/1] upd 7.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.
API method bool CanFocus (TRow row, string col) .
If cell can be focused. Tests all CanFocus attributes.
<Cfg> string Focused .
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.
<Cfg> string FocusedCol .
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.
<Cfg> int FocusedPos .
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.
<Cfg> bool IgnoreFocused .
Ignores attribute Focused sent from server. Has sense especially when used TreeGrid server library.
API variable TRow FRow read only .
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.
API variable string FCol read only .
Actually focused column in grid or null. The grid cursor.
API variable int FPagePos read only .
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.
<XML event> void OnFocus (TGrid Grid, TRow Row, string Col, TEvent Event) .
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!”)’ ... />
API event void OnFocus (TGrid grid, TRow row, string col, TRow orow, string ocol, int pagepos) .
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.
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.
API method bool Focus (TRow row, string col, int pagepos = null, bool show = false) .
Focuses the cell.
If grid was in edit mode, saves changed value in the edited cell.
Returns true, if cell was focused.
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 show is true, expands all parents to show the row.
Remember, when you will call the Focus method from onclick event of some external button, you need to call it in setTimeout, otherwise grid looses focus due the click to button - setTimeout(function(){grid.Focus(row,col);},10);
global prop. TGrid Grids.Focused .
Actually focused grid. This grid catches key events.
If you want to process key events in other controls, set it to null.
<Actions> Focus Attached to many events .
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
<Actions> FocusEdit Attached to event OnClickCell new 6.7 .
Focuses actual cell => moves cursor to cell under mouse cursor.
And starts editing according to InEditMode setting.
It fails if the focus cannot be changed or start edit the cell
The grid will receive key events.
It fails if cell is already focused or cannot be focused.
<Actions> ChangeFocus Not attached to any event .
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.
<Actions> FocusRow Attached to event OnClickNoFocus chg 7.0 .
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.
<Actions> Blur Attached to event OnClickOutside .
Defocuses grid and hides cursor if it is not set as StaticCursor.
The grid will not receive key events.
TreeGrid supports tabulator navigation (tab & shift+tab) inside grid and also from another control to grid and from grid to another control.
<Cfg> int TabStop [1] new 6.0 .
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.
<Cfg> int TabIndex new 6.0 .
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.
<Actions> TabLeft Attached to event OnShiftTab .
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.
<Actions> TabRight Attached to event OnTab .
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.
<Actions> TabRightAdd Not attached to any event .
The same as TabRight, but adds new row if no next variable row is available.
<Actions> TabLeftEdit Attached to events OnShiftTabEdit and OnShiftTabEnum .
The same as TabLeft but goes to the editable cell.
<Actions> TabRightEdit Attached to events OnTabEdit and OnTabEnum .
The same as TabRight but goes to the editable cell.
<Actions> TabRightEditAdd Not attached to any event .
The same as TabRight but goes to the editable cell and adds new row if no next variable row is available.
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.
API event bool OnKeyDown (TGrid grid, char key, Event event, string name, string prefix) upd 6.0 .
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.
API event bool OnKeyPress (TGrid grid, char key, Event event, string name, string prefix) upd 6.0 .
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.
API event bool OnKeyUp (TGrid grid, char key, Event event, string name, string prefix) new 6.0 .
Called when a user releases key in focused grid.
See the parameters in OnKeyDown,
Return true to suppress default action.
<Actions> GoDown Attached to event OnDown .
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.
<Actions> GoDownAdd Not attached to any event .
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.
<Actions> GoUp Attached to event OnUp .
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 below.
<Actions> GoRight Attached to event OnRight .
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.
<Actions> GoLeft Attached to event OnLeft .
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.
<Actions> GoFirst Attached to event OnHome .
Focuses the first focusable variable row in actually focused column.
<Actions> GoLast Attached to event OnEnd .
Focuses the last focusable variable row in actually focused column.
<Actions> PageDown Attached to event OnPageDown .
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.
<Actions> PageUp Attached to event OnPageUp .
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.
<Actions> GoDownEdit Attached to event OnDownEdit .
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.
<Actions> GoDownEditAdd Not attached to any event .
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.
<Actions> GoUpEdit Attached to event OnUpEdit .
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.
<Actions> GoRightEdit Not attached to any event .
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.
<Actions> GoLeftEdit Not attached to any event .
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.