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'/>
<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'/>.
upd 7.0 <C><I><cell> int
CanFocus
[0/1]
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 int
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.
new 15.0 <Cfg> int
FocusedTop
If set, scrolls to Focused row to be exactly given pixels from body top.
If not set, scrolls to Focused row just to be visible in grid.
new 15.0 <Cfg> int
FocusedLeft
If set, scrolls to FocusedCol column to be exactly given pixels from its column section left.
If not set, scrolls to FocusedCol columns just to be visible in grid.
new 13.0 upd 15.0 <Cfg> int
FocusedType
[0]
Flags to control Focused attribute. Bit array.
1. bit, &
1 - If set, does not scroll to focused area on start.
2. bit, &
2 -
(new 15.0) If set, ignores
FocusedTop and
FocusedLeft.
new 15.0 <Cfg> int
ShowFocused
[1]
If the focused cell will be shown and scrolled to after sort / group / filter / search or re-render. Bit array.
It is ignored, if set FocusedType = 3.
1. bit, &
1 - Permits the base feature
2. bit, &
2 - If set, it scrolls to last focused variable row if there is actually focused fixed row (e.g. if changed Filter).
3. bit, &
4 - If set with 2. bit, it focuses the last focused variable row after re-filter and removes focus from the filter row.
<Cfg> bool
IgnoreFocused
Ignores attribute
Focused sent from server. Has sense especially when used TreeGrid server library.
new 15.1 <Cfg> int
FocusLarge
Affects scrolling focused cell into view, if the cell is higher than the view.
If set to
0, scrolls the cell top into view whenever the cell is focused.
If set to
1, does not scroll the cell into view, if it is already in the view fully. Scrolls to the nearest edge of the cell when scrolling to view.
If set to
2, does not scroll the cell into view, it is at least partially visible in view.
new 11.0 upd 15.0 <Cfg> int
SelectingFocus
[0]
If set, automatically selects focused area. Bit array.
1. bit
&1 - selects the focused area.
2. bit
&2 - also selects focused single cell.
3. bit
&4 -
(new 15.0) if focused whole rows and columns, sets
Selected attribute of the row and column, not in cells.
After every focused cell / focused area change clears all selected cells in grid.
Must be set also
Selecting and
SelectingCells.
new 15.0 <Cfg> string[]
ExternalFocus
Can be set to cell as "rowid,col", usually in Space row, that will show row index and column index of of actually focused cell or range in table. Like the formula editing cell in MS Excel.
To the external focus cell can be entered new focus position. Usually like "C3" or "C3:F8" or "C:D" or "3:6".
new 15.0 <Cfg> int
ExternalFocusMaxRows
[200]
Maximum of row pages created with AutoPages if entered not (yet) existing row to focus.
new 15.0 <Cfg> int
ExternalFocusMaxCols
[70]
Maximum of column pages created with AutoColPages if entered not (yet) existing column to focus.
new 15.0 <Cfg> int
TmpFocus
[1]
If grid preserves its focus in some browsers like Firefox that has problems with focusing not editable html tags.
0 - the feature will be disabled. Use in case of problems when grid unwillingly scrolls some its parent tag on click or focus.
1 - default, feature enabled.
2 - another way of enabling the feature. Use in case of problems when grid unwillingly scrolls some its parent tag on click or focus.
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.
new 12.0 API variable TRow
ERow
read only
Actually edited row in grid or null. It is usually the same as
FRow.
new 12.0 API variable string
ECol
read only
Actually edited column in grid or null. It is usually the same as
FCol.
<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!" )' ... />
upd 11.0 API event void
OnFocus
(TGrid grid, TRow row, string col, TRow orow, string ocol, int pagepos, type[ ] rect, type[ ] orect)
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.
new 12.0 API event void
OnBlur
(TGrid grid, TRow orow, string ocol, type[ ] orect)
Called when grid loses focus.
orow,
ocol is previously focused cell.
orect is previously focused rectangle.
chg 11.0 API method bool
Focus
(TRow row, string col, int pagepos = null, type[ ] rect = null, int type = 0)
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.
1. bit | &1 | show | if it is true, expands all parents to show the row. Like if set rect = 1 parameter prior to 11.0 |
2. bit | &2 | no reset | if it is true, does not reset position for key navigation. Prior to 11.0 the key position was never reset, since 11.0 the key position is reset by default! |
3. bit | &4 | no undo | if it is true, does not save the change to undo if set Undo&4 |
4. bit | &8 | no scroll | if it is true, does not scroll the cell into view |
5. bit | &16 | no span | if it is true, does not resize the rect to spanned cells |
6. bit | &32 | no select | if it is true, does not select the focused area if set SelectFocus |
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.
new 15.0 API method void
SetFocused
(bool index)
Saves actual focus and scroll position (
FRow,
FCol,
FPagePos,
FRect)
to
Focused /
FocusedCol /
FocusedPos
/
FocusedRect /
FocusedTop /
FocusedLeft.
The saved position can be restored by
FocusFocused.
If set
index, it saves
FRow index to
Focused instead of id.
new 15.0 API method void
FocusFocused
(bool clear = 1, bool, use = null)
Restores focus position saved by SetFocused or set in input data.
Focuses and scrolls to cell according to
Focused /
FocusedCol /
FocusedPos
/
FocusedRect /
FocusedTop /
FocusedLeft.
If set
clear =
0, it does not clear the Focused... attributes.
If set
use = 1 it does the focus, = 0 does not the focus, = null does the focus if the
IgnoreFocused is 0.
The focus can be asynchronous.
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
new 6.7 <Actions>
FocusEdit
Attached to event OnClickCell
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.
new 12.0 <Actions>
FocusAndEdit
Not attached to any event
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.
<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.
chg 7.0 renamed 11.0 <Actions>
ChangeFocusRow
Attached to event OnClickNoFocus
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.
new 11.0 <Actions>
ChangeFocusCol
Attached to event OnClickNoFocus
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.
<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.
new 12.0 <Actions>
BlurFocused
Not attached to any event
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>
new 12.0 upd 15.0 <Cfg> int
FocusRect
[0]
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. |
5. 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"/>
|
6. bit | &32 | (new 15.0) Permits move / copy focus actions set in 5. bit also on tablet. |
new 11.0 upd 15.0 <Cfg> string[ ]
FocusedRect
Focused area set to
FRect as "
toprowid,
leftcol,
bottomrowid,
bottomcol,
toppagepos,
bottompagepos"
Since 15.0 the
toprowid and
bottomrowid can be empty to focus whole columns or
leftcol and
rightcol can be empty to focus whole rows.
new 11.0 upd 15.0 API variable type[ ]
FRect
read only
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,
bool wholerows,
bool,
wholecolumns]
The FRect area always includes the
FRow,
FCol cell.
To permit focusing more cells by dragging, set e.g.
<Actions OnDragRow="FocusCells"/>
Since 15.0 the
wholerows mean focused whole rows,
wholecolumns means focused whole columns. If set both, whole grid is focused.
new 12.0 API method TRow[ ]
GetFocusedRows
(int type = 0, string attr = null)
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"
new 12.0 API method string[ ]
GetFocusedCols
( )
Returns all actually focused columns.
new 12.0 API method bool
IsFocused
(TRow row, string col)
Returns true if the cell is focused.
new 11.0 chg 12.0 <Actions>
FocusCells
Attached to OnDragRow event, can be attached only to OnDrag... event
Focuses actual cell and starts resizing the focus cursor to rectangle area of cells.
Since 12.0 it fails if
FocusRect is
not set.
new 11.0 chg 12.0 <Actions>
FocusRow
Not attached to any event, can be attached only to OnDrag... event
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.
new 15.0 <Actions>
FocusRows
Not attached to any event, can be attached only to OnDrag... event
Focuses whole actual row and starts resizing the focus cursor vertically to more rows.
It fails if
FocusRect is
not set.
new 11.0 chg 12.0 <Actions>
FocusCol
Not attached to any event, can be attached only to OnDrag... event
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.
new 15.0 <Actions>
FocusCols
Not attached to any event, can be attached only to OnDrag... event
Focuses whole actual column and starts resizing the focus cursor horizontally to more columns.
It fails if
FocusRect is
not set.
new 11.0 chg 12.0 <Actions>
FocusRowCol
Not attached to any event, can be attached only to OnDrag... event
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.
new 12.0 <Actions>
FocusCellRange
Attached to OnShiftClick event
Focuses cell range between actual and focused cell.
new 15.0 <Actions>
FocusRowRange
Not attached to any event
Focuses whole rows range between actual and focused cell.
new 15.0 <Actions>
FocusColRange
Not attached to any event
Focuses whole columns range between actual and focused cell.
new 11.0 chg 15.0 <Actions>
FocusWholeRow ...FAO
Not attached to any event
Focuses all cells in the actual or focused rows.
Since 12.0 it fails if
FocusRect is
not set.
Since 15.0 it focuses all rows in focused rect.
new 12.0 chg 15.0 <Actions>
FocusWholeCol ...FAO
Not attached to any event
Focuses all cells in the actual or focused columns. It fails if
FocusRect is
not set.
Since 15.0 it focuses all columns in focused rect.
new 12.0 <Actions>
FocusWholeGrid
Not attached to any event
Focuses all cells in the grid.
It fails if
FocusRect is
not set.
<Actions>
FocusDown
Attached to event OnShiftDown
Extends the focused range to the first focusable cell below the actually focused cell.
It fails if there is no next focusable cell below.
<Actions>
FocusUp
Attached to event OnShiftUp
Extends the focused range to the first focusable cell above the actually focused cell.
It fails if there is no next focusable cell above.
<Actions>
FocusRight
Attached to event OnShiftRight
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.
<Actions>
FocusLeft
Attached to event OnShiftLeft
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:
<Actions OnDragLeftEdge="MoveFocus" OnDragRightEdge="MoveFocus" OnDragTopEdge="MoveFocus" OnDragBottomEdge="MoveFocus"/>
<Actions OnCtrlDragLeftEdge="CopyFocus" OnCtrlDragRightEdge="CopyFocus" OnCtrlDragTopEdge="CopyFocus" OnCtrlDragBottomEdge="CopyFocus"/>
new 11.0 upd 12.0 <Cfg> int
MoveFocusType
[3]
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. |
new 11.0 <Actions>
MoveFocus
Not attached to any event, can be attached only to OnDrag... events
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 &
16
You can set also
<Cfg FocusCellBorderCursor='1'/> to show move mouse cursor above the focused cell border.
new 11.0 <Actions>
MoveFocusValues
Not attached to any event, can be attached only to OnDrag... events
Moves focused cell or focused area to new location by mouse.
Like
MoveFocus,
but moves only values and EFormula or attributes listed in
EditAttrsValue.
It is attached automatically for dragging with Shift, if set
FocusRect &
16
new 11.0 <Actions>
MoveFocusStyles
Not attached to any event, can be attached only to OnDrag... events
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.
new 12.0 <Actions>
CopyFocus
Not attached to any event, can be attached only to OnDrag... events
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 &
16
new 11.0 <Actions>
CopyFocusValues
Not attached to any event, can be attached only to OnDrag... events
Copies focused cell or focused area to new location by mouse.
Like
CopyFocus,
but copies only values and EFormula or attributes listed in
EditAttrsValue.
It is attached automatically for dragging with Ctrl and Shift, if set
FocusRect &
16
new 11.0 <Actions>
CopyFocusStyles
Not attached to any event, can be attached only to OnDrag... events
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.
new 12.0 API method void
CopyRange
(type[ ] destination, type[ ] source, bool clear = 0)
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]
new 11.0 API event type
OnMoveFocus
(TGrid grid, type[ ] rect, type[ ] orect, type[ ][ ] Values, TRow[ ] Rows, string[ ] Cols, TRow[ ] SourceRows, string[ ] SourceCols)
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.
new 11.0 upd 12.0 API event type
OnMoveFocusValue
(TGrid grid, TRow row, string col, TRow orow, string ocol, type value, type oldvalue, type[ ] attrvalues, string[ ] attrnames, object errors)
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.
new 11.0 API event void
OnMoveFocusFinish
(TGrid grid, type[ ] rect, type[ ] orect, type[ ][ ] Values, TRow[ ] Rows, string[ ] Cols, TRow[ ] SourceRows, string[ ] SourceCols)
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.
new 11.0 upd 12.0 <Cfg> int
AutoFillType
[5]
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. |
new 11.0 <Actions>
FocusFillRowCol
Attached to OnDragCorner event, can be attached only to OnDrag... event
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.
new 11.0 <Actions>
FocusFillCells
Not attached to any event, can be attached only to OnDrag... event
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.
new 11.0 <Actions>
FocusFillRow
Not attached to any event, can be attached only to OnDrag... event
Starts filling cell values by the focused cell or focused cell range. It fills only horizontally.
new 11.0 <Actions>
FocusFillCol
Not attached to any event, can be attached only to OnDrag... event
Starts filling cell values by the focused cell or focused cell range. It fills only vertically.
<Actions>
FillCells
Attached to OnShiftDragRow event, can be attached only to OnDrag... event
Starts filling cell values by the actual cell value. It fills to all cells the actual cell value.
<Actions>
FillCol
Not attached to any event, can be attached only to OnDrag... event
Starts filling cell values by the actual cell value. It fills only vertically.
<Actions>
FillRow
Not attached to any event, can be attached only to OnDrag... event
Starts filling cell values by the actual cell value. It fills only horizontally.
new 12.0 API method void
FillRange
(type[ ] destination, type[ ] source, int type = AutoFillType)
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.
new 11.0 API event bool
OnAutoFillValues
(TGrid grid, type[ ][ ] Values, TRow[ ] Rows, string[ ] Cols, int orcnt, int occnt, int rcnt, int ccnt, bool rdir, bool cdir)
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.
upd 11.0 API event bool
OnAutoFill
(TGrid grid, TRow r1, string c1, TRow r2, string c2, bool rdir, bool cdir, TRow ro, string co)
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:
OnAutoFill(Grid,R2,C5,R8,C12,0,0,[[{R2,C5},{R2,C6},{R2,C7}],[{R3,C5},{R3,C6},{R3,C7}]],R3,C7)
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.
new 8.0 upd 11.0 API event void
OnAutoFillFinish
(TGrid grid, TRow r1, string c1, TRow r2, string c2, bool rdir, bool cdir, TRow ro, string co)
Called after filling is finished. The arguments are the same as in
OnAutoFill.
upd 12.0 API event type
OnAutoFillValue
(TGrid grid, TRow row, string col, TRow orow, string ocol, type val, type prevval, int rowpos, int colpos, TRow orow2, string ocol2, type oldval, type[ ] attrvalues, string[ ] attrnames, object errors)
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.
new 6.0 upd 16.3 <Cfg> int
TabStop
[1]
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.
Since 16.3 if set to
3, tab moves into and out grid without moving cursor inside grid, if set to
4, it also starts editing the cell.
new 6.0 <Cfg> int
TabIndex
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.
If set
FRect, it navigates only inside this area.
<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.
If set
FRect, it navigates only inside this area.
<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.
new 11.0 <Actions>
TabUp
Not attached to any event
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.
new 11.0 <Actions>
TabDown
Not attached to any 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.
new 11.0 <Actions>
TabUpEdit
Not attached to any event
The same as
TabUp but goes to the
editable cell.
new 11.0 <Actions>
TabDownEdit
Not attached to any event
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.
upd 6.0 API event bool
OnKeyDown
(TGrid grid, char key, Event event, string name, string prefix)
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", "F2", "Esc" or "Right".
prefix is shift key prefix - "Shift", "Alt", "Ctrl", "ShiftAlt", "ShiftCtrl", "CtrlAlt", "ShiftCtrlAlt".
Return true to suppress default action.
upd 6.0 API event bool
OnKeyPress
(TGrid grid, char key, Event event, string name, string prefix)
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.
new 6.0 API event bool
OnKeyUp
(TGrid grid, char key, Event event, string name, string prefix)
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 above.
<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.
new 12.0 <Actions>
PageDownFull
Not attached to any event
Like
PageDown, but preserves the focused row relative to the page - it does
not focus last row on last page as the last step.
new 12.0 <Actions>
PageUpFull
Not attached to any event
Like
PageUp, but preserves the focused row relative to the page - it does
not focus first row on first page as the last step.
<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.