Events and actions

TreeGrid documentation

TreeGrid contains fully customizable Key and Mouse schema, all key and mouse actions (JavaScript callbacks, event handlers) are set in Defaults.xml in <Actions> tag and can be changed by a user.

JavaScript callbacks / event handlers in TreeGrid

a) TreeGrid mouse events

Every part (row, cell, button, etc.) in grid has its own name and you can attach an action for it:
To the action name is attached key prefix when some control key is held down: "Shift", "Ctrl", "Alt", "Meta" (on Mac) and their combinations.
The actions can be defined in global <Actions> tag, attached in global Grids array by JavaScript, defined for specific <C>, <I> or cell.
The JavaScript action has always this definition: function (TGrid Grid, TRow Row, TCol Col, TEvent Event), where Row, Col is cell under mouse.

b) TreeGrid key events

There are three different key actions called when a user presses key in Focused grid: regular, edit, edit multiline.
The action name is the key name defined in <Actions> tag.
To the action name is attached key prefix when some control key is held down: "Shift", "Ctrl", "Alt", "Meta" (on Mac) and their combinations.
The actions can be defined in global <Actions> tag, attached in global Grids array by JavaScript, defined for specific <C>, <I> or cell.
The JavaScript action has always this definition: function (TGrid Grid, TRow Row, TCol Col, TEvent Event), where Row, Col is focused cell.

c) TreeGrid API events

TreeGrid provides many JavaScript callbacks for many actions done in grid, like OnSelect, OnRenderFinish, OnClick and so on.
The actions are attached to global Grids array by JavaScript.
The JavaScript actions have various definitions.

d) TreeGrid calculations and formulas

Every row or cell attribute can be calculated, so it can have attached JavaScript formula to calculate the value. Basically the formulas are used to calculate cell values, but also other attributes can be calculated.

e) Standard JavaScript events

You can attach any JavaScript event handler like onclick to any tag on HTML page and provide some action with TreeGrid using its API. The grid is accessible by global Grids array.
You can attach JavaScript events also to HTML code inside grid cells, but if there are many such cells, it can remarkably slow down the grid, so you should reconsider it and use another event option.

TreeGrid mouse events

The event name consists from: On + key_prefix + event_name + target.
For example OnMouseOverTree, OnShiftClickRow, OnCtrlShiftRightClickCell

Mouse event names

Key and mouse button prefixes

Touch event names (for tablets and mobiles) (new 7.0)

There are available events for one or more fingers touching down the pad.
If defined more handlers for the same event with different fingers, it is called only one (even if it returns false) for the specified count of fingers.
For example if defined Click, Click1 and Click3 events, for 1 finger is called Click1, for 2 fingers also Click1, for 3 or more fingers is called Click3. The Click is never called if defined Click1.
All the affected fingers must be on the grid, not outside on the pad!
No key or button prefixes for the touch events available!


Touch events do not work in MS IE in any version.
Touch events work in all other browsers on tablets and mobiles and in Chrome and Safari on desktop by default.
Touch events in MS Edge on desktop you have to permit in about:flags, option Touch - Touch events - Enable touch events.
Touch events in Firefox on desktop you have to permit in about:config, option dom.w3c_touch_events.enabled = 1.

Event targets

Every point in grid belongs to one or more targets. For one point in grid can be run more events, for different targets.
The targets are classified into 12 groups, every point in grid can have only one target per group.
To see what targets are assigned to grid points, set <treegrid>/<bdo> Debug attribute to "event" and hover the grid.
The assigned action are called in the order 0 - 11, if any of the actions succeeds, the next actions are not called.

0) Edge - the edge of the cell, now implemented only for header cells and focused cell.
Inside (default value for no edge)
Resize (bottom right edge in grid, for resize grid) / HeaderLeft / HeaderRight (resizing columns, set for cell with Resizing=2)
PagerHeaderLeft / PagerHeaderRight (resizing pager)
HeaderTop / HeaderBottom (since 11.0, resizing rows, set for cell with Resizing=1)
HScrollLeft (edge between left and middle scrollbar) / HScrollRight (edge between middle and right scrollbar)
LeftEdge / RightEdge / TopEdge / BottomEdge (since 11.0, border edge of the focused cell, shown when defined FocusCell="Border,...")
Corner (since 11.0, right bottom corner of focused cell, shown when defined FocusCell="Corner,...")
Note, mouse cursor for the LeftEdge, RightEdge, TopEdge, BottomEdge and Corner cannot be set by action in OnMouseOver, it must be set in TreeGrid CSS style.

1) Special
Sort / SortUp / SortDown (sorting icon or the whole header cell depending on <Cfg SortIcons/> setting)
Radio1 / Radio2 / Radio... (individual Radio type buttons)
DropCol1 / DropCol2 / DropCol... (individual columns in DropCols type, the empty space is the last DropCol)
PagerPage1 / PagerPage2 / PagerPager... (individual pages in right side pager, without empty space)
Left / Mid / Right (horizontal scrollbar)
Levels1 / Levels2 / Levels... (individual tree Level buttons in header, since 10.0)
Popup (popup icon of Button type with List attribute)
Close (close icon of Button type with CanDelete = 2, since 13.0)

2) PartType
Edit + cell Type (e.g EditText, EditInt, ..., only editable cells, for Bool and Radio is returned for the icon only, otherwise returns Nothing)
/ DropCol / DropEmpty (cell Type="DropCols", DropEmpty is the empty space without columns)
/ Link (cell Type="Img","Link", only the link or image, otherwise Nothing)
/ Gantt (cell Type="Gantt") / GanttHeader (header of Gantt type column)
/ Expand (expand or collapse button in tree)
/ Levels (tree level buttons in header, since 10.0)
/ ButtonSave / ButtonAdd / ... / ButtonXXX (all standard and custom toolbar buttons - cell Type="Button", XXX is column name)
/ PanelFiltered / PanelGrouped / PanelSorted / SpaceOff / Space... (all custom panel buttons in Space row, Type="Panel")
/ PanelDelete / PanelSelect / PanelMove / PanelCopy / PanelOff / Panel... (all custom panel buttons in standard row, Type="Panel")
/ HeaderDelete / HeaderSelect / HeaderMove / HeaderCopy / HeaderOff / Header... (all custom panel buttons in Header row, Type="Panel")
/ SideSort / SideDate / SideDefaults / SideFilter
/ SideButton (custom right side Button)
/ SideIcon (custom left / right side Icon)
/ Nothing (other types when CanEdit='0'; Bool and Radio also outside the icon, Bool,Radio,Enum also in ReadOnly mode)

3) Part
Content (standard cell content) / Caption (header cell content) / Side (right/left cell button) / Tree (tree button or lines) / Panel (cell Type="Panel") / Button (cell Type="Button", since 10.0 also for side Icon)

4) CellState
Edited (focused cell in edit mode) / Viewed (focused cell in read only edit mode) / Focused (focused cell) / Regular (not focused cell)

5) CellEdit
Editable / ReadOnly (CanEdit='0') / NoFocus (CanFocus='0')

6) CellKind
Kind + row Kind attribute (KindData, KindHeader, KindSpace, KindFilter, KindGroup, KindSearch, KindToolbar, KindPager, ...)
/ KindUser (standard row without cells, specified by xxxHtml attribute)

7) CellSection
Header (Kind="Header") / Body (body row) / Fixed (head and foot row except header) / Space (space row )
/ PagerHeader (right side pager header) / PagerBody (right side pager except header, including empty space)

8) Cell
Cell (any cell) / PagerPage (right side page, no empty space) / Empty (any other place without cells)

9) Section
Left / Mid / Right / All (space row)

10) RowKind
HeaderRow / BodyRow / FixedRow / SpaceRow / NoRow

11) RowSection
Row (any row) / Pager (right side pager) / VScroll (vertical scrollbar) / HScroll (horizontal scrollbar) / Other

12) Grid
Grid (anything inside grid) / Outside (anything outside the grid, including other grids)

Assigning event actions/callbacks

The event actions can be assigned in TreeGrid XML/JSON or by JavaScript in global Grids array.
In XML/JSON the event can be assigned to cell, whole row, whole column or whole grid in <Actions> tag.
For example: <I Col1OnClickCell='Focus'/> (cell), <I OnClickCell ='Focus'/> (row), <C OnClickCell ='Focus'/> (column), <Actions OnClickCell ='Focus'/> (grid).
If more events are assigned for one cell, they are called in this order: 1) Grids array, 2) one from cell or row or column, 3) <Actions>. If any action returns true, the next are not called.

Dynamical assignment by JavaScript
Every action can be replaced dynamically by JavaScript, by simple assignment, for example:
Grids.OnClickCell = function(Grid,Row,Col,Event) { ... }
row[col+"OnClickCell"] = "alert('click')";
row.OnClickCell = "..."
grid.Cols[col].OnClickCell = "..."
grid.Actions.OnClickCell = "..."

The action code assigned to XML/JSON can be exact JavaScript code or simplified notation. The action in global Grids array must be JavaScript function.

Simplified notation for assigning actions in XML/JSON

- One action is assigned just by name
	[A]	<Actions OnClickCell='Focus'/> - do Focus
- Constant action. 1 or 0, useful with other operators to return 0 or 1 independently on result of actions
	[1] or [0]	<Actions OnUp='GoUp,1'/> - do GoUp and always return success to suppress default behavior for OnUp key event
- Two action are always executed. Separate by plus. The return value is true if at least one action succeeded.
	[A + B]	<Actions OnClickCell='Focus+ShowDetail'/> - do Focus and next ShowDetail
- The second action is executed only if the first action succeeds. The return value is true if both actions succeeded. Separate by AND or &&. Attention, when you use only "&" instead of "&&", both action are always called!
	[A && B] or [A AND B]	<Action OnClickCell='Focus AND StartEdit'/> - do Focus and if succeeds, do StartEdit
- The second action is executed only if the first action fails. The return value is true if at least one action succeeded. Separate by OR or ||. Attention, when you use only "|" instead of "||", both action are always called!
	[A || B] or [A OR B]	<Action OnClickSort='SortAsc OR SortDesc'/> - do SortAsc or, if not possible, do SortDesc
- Action B is executed only when Action A succeeded, Action C is executed only when Action A failed. The colon must not be missing.
	[A ? B : C]	<Actions OnClickCell='Focus ? StartEdit : ShowDetail'/> - do Focus and if succeeds do StartEdit otherwise do ShowDetail
- Both actions are always executed. The return value is the result of the second action and the first action result is ignored
	[A , B]	<Action OnMouseOverBody='ColorHover,HoverRowCell'/> - do ColorHover and next HoverRowCell, return value of HoverRowCell.
The operators can be combined together, the operator priority is according to they are listed here, the plus has the highest priority. You can use parenthesis ( ) to change the priority.
		<Actions OnClickCell="Focus AND StartEdit+ShowDetail"/> - do Focus and, if it succeeds, do both StartEdit and ShowDetail

Exact JavaScript notation for assigning actions in XML/JSON
You can use any JavaScript code here, for long code is better to define custom JavaScript function and call it here.
Example: <Actions OnClickCell="alert('clicked ['+Grid.ARow.id+','+Event.Col+']');"/>

Assigning function to global Grids array
You can assign the JavaScript function in script in HTML page or in external script. The assignment must be placed after including TreeGrid script GridE.js.
Example: Grids.OnClickCell = function(Grid,Row,Col,Event){ alert('clicked ['+Row.id+','+Col+']'); }

Event action (function callback) parameters

The event handler is called with parameters TGrid Grid, TRow Row, string Col, TEvent Event.
These parameters can be accessible from the event handler code, for example: OnClickRow = "Grid.SelectRow(Row)".
The Row and Col parameters can be null if there is click outside cells.
The event assigned to global Grids array is called as global function with these parameters - function (Grid, Row, Col, Event).
The event code should return 1 or true for success, 0, false or null for failure.

TEvent properties (the cell properties are related always to mouse position!)

string Name	Name of event without On, for example MouseMove or Click.
TRow Row, string Col	Cell under mouse cursor
string Type	Type of the cell, like Int or Text
bool CanEdit, CanFocus	Permissions of the cell
int X, Y	Position of mouse click relative to the cell
int Width, Height	Size of the cell
int ClientX, ClientY	Absolute position of mouse click, the event.clientX, event.clientY
int AbsX, AbsY	Absolute position of mouse click. It is not the same as event.clientX, event.clientY. It is position where will be placed tag with position:absolute.
string Level	Target group (0-11), for example PartType or CellSection
string Target	Target name from the group, for example ButtonSave or PagerBody
string Prefix	Key prefix, for example Shift or CtrlAlt
int Button	Button pressed in OnMouseDown, 1 left, 2 middle, 3 right

...and many other internal properties that must not be changed ...

Action name suffix

Action suffix is used to define target cell(s)/row(s)/column(s) the action will affect.
Available suffixes for actions:
F - focused cell(s) or focused whole row(s) or focused whole column(s).
S - selected cells(s) and whole selected row(s) and whole selected column(s).
A - actual cell / row / column under mouse cursor.
R - whole row(s). For actions manipulating cell ranges it uses whole rows from all chosen ranges and cells. For actions manipulating whole rows it takes only whole selected / focused rows. With A can return actual row.
C - whole column(s). For actions manipulating cell ranges it uses whole columns from all chosen ranges and cells. For actions manipulating whole columns it takes only whole selected / focused columns. With A can return actual column.
W - whole grid. Takes all cells / rows / columns in grid regardless on current selection / focus / mouse position. Ignores F, S, A, O suffixes.
O - the only cell / row / column. If there are more cells / rows / columns to use (selected or focused), the action fails.
The suffixes can be freely combined, except W with F,S,A,O.
For example OnCtrlClick="ClearCellAR" will clear actual row.
The menu item text for action in cell menu is defined in <Lang><MenuCell ... /></Lang>, there can be defined also different text for action with suffix, e.g. <Lang><MenuCell ClearCellRC="Clear whole row"/></Lang>. Use always order "FSARCWO" in the attribute name suffix.

If called action without any suffix, the target is chosen by:
a) In mouse action, if actual cell is selected or it is Space Button, it takes all selected cells / rows / columns. If actual cell is focused or it is Space button, it takes the focused cells / rows / columns. If actual cells is neither focused nor selected and it is not Space button, it takes the actual cell itself.
b) In key action it takes all focused and selected cells / rows / columns.
Prior 15.0 there was only suffix F and the action without suffix affected only actual cell. The action affecting focused or selected ranges were named differently.

Calling predefined actions from JavaScript

Every action can be also called from JavaScript by grid["Action"+name], for example grid.ActionSave();

The target is used for action suffix, it is bit array of the suffix values. If it is null, it calls action without suffix.
The suffix bit values: F - 1, S - 2, A - 4, R - 8, S - 16, W - 32, O - 64.
For example grid.ActionClear(12) will call action ClearAR.
The target can be temporary changed by CellRanges attribute.
Prior to 15.0 the target could be only 1 as F.

(New 12.0) All actions except dragging and mouse cursor actions can be called just to test if the action will succeed for actual state. Call it with the second parameter as 1, like grid.ActionSave(null,1);

Calling actions from JavaScript is intended just to extend the global mouse or key schema. To provide specific actions for individual cells, use standard API methods like SelectRow or AddRow.

Creating custom actions

Since 12.0 it is possible to create custom actions.
The custom action is created as function assigned to some Grids property.
The function takes three arguments as (TGrid grid, int target, bool test).
grid is the grid object calling the action.
target is set according to the action suffix, the suffix bit values: F - 1, S - 2, A - 4, R - 8, C - 16, W - 32, O - 64.
test is set, if the function is called to test, if the action will succeed. In this case it must not do any action, just return true or false.
The function must return true for success or false for failure.
If set test, the action can also return integer for success as count of affected items, that will replaced the %1 in menu item text.

The action text for cell Menu can be defined in <Lang><MenuCell name="text"/></Lang>.
The custom action can be assigned like any standard TreeGrid action to any TreeGrid event or cell Menu.
The custom action cannot be assigned to dragging events.

For example the next code hides or shows cell content on double click or from right click popup menu:
<script>
Grids.HideCell = function(grid,focus,test,show) {
var row = focus ? grid.FRow : grid.ARow, col = focus ? grid.FCol : grid.ACol;
if(!row||!col||(show?row[col+"Visible"]!=-1:row[col+"Visible"]==-1)) return false;
if(test) return true;
row[col+"Visible"] = (show?1:-1); grid.RefreshCell(row,col);
return true;
}
Grids.ShowCell = function(grid,focus,test) { return Grids.HideCell(grid,focus,test,1); }
</script>
<Cfg Menu="|HideCell|ShowCell"/>
<Actions OnDblClickCell="HideCell OR ShowCell"/>
<Lang><MenuCell HideCell="Hide the cell content" ShowCell="Show the cell content"/></Lang>
Returns actual TreeGrid mouse event object. See TEvent.

Focused vs. actual cell

Predefined actions are done usually for focused or actual cell, row or column. It is not the same.
Actual cell, row or column is under mouse cursor and focused cell or cell range is TreeGrid cursor (blue by default).
Also focused cell or cell range is not the same as selected cells, rows or columns. There can be more selected cell areas, rows and columns and is possible to delete, move or copy them, whereas focused cell or cell area is only one and it is a grid cursor.
When action says that works with actual or focused row / column / cell, it exists in more versions, version without suffix works with actual or focused version depending on event, version with suffix A works with actual and the version with suffix F works with focused and S with selected.
For example DeleteRow ...FSARO has DeleteRowA for actual row and DeleteRowF for focused row and DeleteRowS for selected row.

TreeGrid key events

The event name consists from: On + key_prefix + key_name [+ target].
For example OnUp, OnShiftTab, OnUpEdit

The key actions are called in JavaScript onkeydown event and are called only for focused grid. There can be only one focused grid at a time. The focused grid is set by Grids.Focused property automatically when some cell in grid is focused.
The build-in TreeGrid action should be used with ...F suffix when assigned to key events, to handle focused cell and not active (under mouse) cell.

Key event names

Key names for all possible keys on keyboard.
Key names are defined by KeyNames... attributes for key scan codes. The KeyNames should not be changed, if there is not real reason to do it.

Base keys

Control keys

Other std. keys

Numeric keys

Lock keys

Character keys

Key event targets

By default has key event no target that is used for standard controlling when EditMode is off - no cell is being edited.
If the EditMode is on, there are called events for target Edit. If the edited cell is multiline, there is called two actions for targets EditMultiline and Edit - if the EditMultiline action returns true, the Edit action is not called.

Assigning actions for events and function parameters are the same as for mouse events.

TreeGrid API events

The API event handlers can be assigned by two ways: 1) by direct assignment or 2) by TGSetEvent or TGAddEvent function.
These ways cannot be mixed for the same event!
Note, the event handler is your function that is called from TreeGrid code. If you want to call the event handler from your code, just call your function directly with appropriate parameters.
Since 11.0 if any event handler returns null (or undefined), it is ignored like it would not be defined at all. Except OnCorrectDependencies event, here the null (but not undefined) has its own meaning.

Direct assignment

Grids.EventName = function(grid, param1, param2, ...) { ... }
or
function MyFunc(grid, param1, param2, ...) { ... }
Grids.EventName = MyFunc;

For example:
Grids.OnClick = function(grid,row,col,x,y) { alert("clicked cell "+(row?row.id:null)+ ","+col+" at "+x+","+y); }
This global event is called for all grids on page, with different first parameter grid.

Assignment by TGSetEvent or TGAddEvent

You can set one event handler per grid by TGSetEvent.
Or you can set more event handlers per event and grid by TGAddEvent.
And remove assigned handlers them by TGDelEvent.
Sets TreeGrid event name handler for grid with given id.
Clears all other handlers set for this event name and grid id by TGAddEvent or TGSetEvent.
Use it, if you have more grids and want to call different function for every grid.

name	event name like "OnClick". If the name is null, the TGSetEvent call is ignored.
id	id of the grid to attach the event handler to. This grid need not exist yet in time of call the TGSetEvent / TGAddEvent.
	(new 11.0) If id is empty string, the function will be called for all other grids than for those having attached some this event handler by TGSetEvent / TGAddEvent.
	(chg 11.0) If id is null, the function will be called for all grids. Always after the handlers attached to exact grid or other grids.
func	any JavaScript function to be called for event raised. It should have the same parameters as the event handler expects.
	If the func is null, it only deletes all the event name handlers.
ident	(new 11.0) identifier for the func, by it the func can be deleted by TGDelEvent or read by TGGetEvent.

Since 11.0 it returns 0 for error, 1 for event set.
Since 14.1 if used GridED.js on demand script instead of GridE.js static script, the function downloads the GridE.js asynchronously and next sets the event handler.

Example: (both the ways do the same thing)

Standard way:	Grids.OnClick = function(G){ if(G.id=="G1") alert("G1 clicked"); if(G.id=="G2") alert("G2 clicked"); }
TGSetEvent way:	TGSetEvent("OnClick","G1",function(){ alert("G1 clicked");} );
	TGSetEvent("OnClick","G2",function(){ alert("G2 clicked");} );

Do not use both ways together; if you set Grids.OnClick, you cannot set it also by TGSetEvent / TGAddEvent and vice versa.
TGSetEvent is useful also when using automatic merging web pages like by Java portal - JSR-000168 Portlet.
Since 11.0 it can be used for all events. Since 11.0 it can be used with TGAddEvent / TGDelEvent. This function slightly slows event execution.
Note, calling TDSetEvent marks the event defined always for all grids, it can cause slightly different behavior for OnRowFilter, OnButtonClick, OnIconClick, OnContextMenu, OnGanttMenuClick, OnGanttRunBoxChanged
Adds TreeGrid event name handler for grid with given id.
It preserves all other attached events. All attached handlers will be called when the event happens.
With this function you can have more handlers for one event and one grid and you can add and delete them dynamically.
Must not be used with standard event assignment by Grids[name].
Since 11.0 the calling order of attached events is in the order they were attached. First are called handlers for exact grid id (id was set) or the other events (id was "") and finally the events attached to all grids (id was null).
The return value for event is the first non null return value from some handler.

name	event name like "OnClick". If the name is null, the TGAddEvent call is ignored.
id	id of the grid to attach the event handler to. This grid need not exist in time of call the TGSetEvent / TGAddEvent.
	(chg 11.0) If id is empty string, the function will be called for all other grids than for those having attached some this event handler by TGSetEvent / TGAddEvent.
	(new 11.0) If id is null, the function will be called for all grids. Always after the handlers attached to exact grid or other grids.
func	any JavaScript function to be called for event raised. It should have the same parameters as the event handler expects.
	If the func is null, the TGAddEvent is ignored.
ident	(new 11.0) identifier for the func, by it the func can be deleted by TGDelEvent or read by TGGetEvent.
	It must be unique for given name and id. If it already exists, the func is replaced instead of adding new handler.

Since 11.0 it returns 0 for error, 1 for event added, 2 for event replaced.
Since 14.1 if used GridED.js on demand script instead of GridE.js static script, the function downloads the GridE.js asynchronously and next adds the event handler.
Since 11.0 it can be used for all events. Since 11.0 it can be used with TGSetEvent / TGDelEvent. This function slightly slows event execution.
Note, calling AddEvent marks the event defined always for all grids, it can cause slightly different behavior for OnRowFilter, OnButtonClick, OnIconClick, OnContextMenu, OnGanttMenuClick, OnGanttRunBoxChanged
Removes TreeGrid event handler added by TGAddEvent or (since 11.0) TGSetEvent functions.

name	event name like "OnClick".
	If the name is null, it deletes all event handlers attached to given grid id. In this case the func is ignored.
id	id of the grid to delete the event handler(s) from. This grid need not exist in time of call the TGDelEvent.
	(new 11.0) If id is empty string, it deletes all other grids handler(s) added by TGSetEvent / TGAddEvent with id as empty string.
	(new 11.0) If id is null, it deletes all grids handler(s) added by TGSetEvent / TGAddEvent with id as null.
ident	It can be the JavaScript function attached to the event. It must be the same function object you passed to TGAddEvent / TGSetEvent, not newly defined function with the same code!
	Or since 11.0 it can be the identifier under it the handler was added (the ident parameter in TGSetEvent / TGAddEvent).
	If the ident is null, it deletes all handlers attached to event name and grid id.

Since 11.0 returns true if the handler is deleted otherwise it returns false.
Returns TreeGrid event handler added by TGAddEvent or TGSetEvent functions.

name	event name like "OnClick".
id	id of the grid to get the event handler(s) from. This grid need not exist in time of call the TGGetEvent.
	It can be also empty string or null. To get appropriate attached handler.
ident	the identifier under it the handler was added (the ident parameter in TGSetEvent / TGAddEvent).

returns the attached function object or null for error.