TreeGrid v6.0
Tree
Rows in TreeGrid can be placed into tree.
TreeGrid supports unlimited levels of tree.
In XML can be rows placed in tree of <I> tags like <I A=’1’> <I A=’1-1’> <I A=’1-1-1’/> <I A=’1-1-2’/> </I> <I A=’1-2-1’> <I A=’1-2-2’/> <I/> </I> <I A=’1-2’/> <I A=’1-3’/> </I> <I A=’2’/>
The tree lines and expand/collapse buttons are placed into MainCol.
The row’s children can be expanded, collapsed or not expandable / not collapsible, see Expanded and CanExpand.
The width of icons and indent in tree is defined in styles in Grid.css.
The rows can be also placed into tree automatically by Grouping feature.
<Cfg> string MainCol .
Set this attribute to show TreeGrid instead of plain table. Let it empty to show only plain table.
It is name of main column with tree. The column must exist in the grid, but can be also hidden.
In this column will be displayed the tree with expand / collapse icons.
Only one main column is possible to be in grid. See also Button=’Expand’ to show the tree in more columns.
If set, the column should exist and be visible, otherwise a user cannot see the rows parent / children relationship.
<I> int CanExpand [1] upd 7.0 .
If row shows icon to expand / collapse and the row can be expanded or collapsed.
If set to 0, the row cannot be expanded or collapsed by a user. So its children are always shown or hidden, depending on Expanded.
Since 7.0, if set to 2, the row can be expanded or collapsed, but the expand / collapse icon is not shown. Use to expand / collapse the row by another way.
<I> bool Expanded [1] .
Row is expanded, displays its children.
If ChildPaging is set to 3, only rows with Expanded=’0’ will take effect of the server ChildPaging and can download its children on expand.
<I> string TreeIconX .
Custom tree icons for specified row state (icons for expand/collapse)
X = 0 – not expandable, 1 – last not expandable, 2 – expand (+), 3 – last expand (+), 4 – collapse (-), 5 – last collapse (-)
If set NoTreeLines only values 2 and 4 are used.
The last row is last row inside its parent’s children – its line does not continue.
For example: <I TreeIcon2=’SpecialExpand.gif’ TreeIcon4=’SpecialCollapse.gif’/>
The height of the icon is always set to height of the row, the width is always set to standard Tree icon.
<C> <cell> string Button Button = “Expand” new 7.0 .
To show right side Expand button set Button=”Expand”.
It can be used to show the tree button in different column than in the main column.
To hide expand icon in the main column, you can set row attribute CanExpand=’2’.
<C> <cell> string Icon Icon = “Expand” new 7.0 .
To show left side Expand button set Icon=”Expand”.
It can be used to show the tree button in different column than in the main column.
To hide expand icon in the main column, you can set row attribute CanExpand=’2’.
<Cfg> bool HideRootTree [0] .
Hides the first line in tree (root items are without any line).
Root rows become not expandable, so they should be all Expanded.
<Cfg> bool NoTreeLines [0] .
If set to 1, it does not show connecting lines in tree, shows only expand / collapse buttons
API method void SetNoTreeLines (int Value) new 7.0 .
Sets value of the NoTreeLines and re-renders grid.
API TRow var. int Level read only .
Row’s level in tree. Only for variable rows.
-1 = page, 0 root row, 1 first level children, 2 second level children, ...
API method bool HasChildren (TRow row) .
Returns true if row has some visible children (shows icon expand/collapse)
API method int GetPos (TRow row) .
Returns row’s position in its parent. It counts only visible rows.
<Cfg> int SaveExpanded [0] Saves information to cookies .
If set to 1, saves expanding / collapsing state of all rows to cookies. All rows must have set id attribute.
If set to 2, saves the state of only rows that differs from their default row’s Expanded state.
Remember, cookies are limited to 4096 bytes for the whole page, so use this setting only for very small tables or use PersistentCfg.
Also use the smallest ids as possible (the amount of space is used: id+1 bytes per row).
Cannot be used with server side child paging.
<Cfg> string Expanded new 6.7 .
All rows (comma separated ids) that will be expanded, all other rows will be collapsed if the attribute is present.
It is done on start and also after every page / child page load in server paging.
<Cfg> bool NoScrollAfterExpand [1] chg 7.0 .
If set to 0, TreeGrid scrolls down if the children are not shown all.
If set to 1, when expanding row, does not scroll into view the row’s children – the icon always stays under mouse cursor
Since 7.0 the default value is 1.
The row can be expanded or collapsed by a user by clicking to row’s expand / collapse icon in tree. And also by pressing Ctrl+Enter by default.
Collapsing rows is immediate, but expanding rows can be slows and asynchronous, depending on how many children will be loaded / render, see various paging types.
All rows can be expanded or collapsed by clicking to toolbar buttons ExpandAll or CollapseAll.
The CollapseAll always collapses all rows in grid, but ExpandAll can expand only some rows to avoid dead lock when too many children are present, see ExpandAll... settings.
<Actions> Expand ...F Attached to events OnClickExpand and OnCtrlEnter .
Expands actual or focused row, fails if row is already expanded or cannot be expanded or does not have children.
The expanding can be asynchronous and can finish after the action returned.
<Actions> Collapse ...F Attached to events OnClickExpand and OnCtrlEnter .
Collapses actual or focused row, fails if row is not expanded or cannot be expanded or does not have children.
Use “Expand OR Collapse” to invert expand state
<Actions> ExpandAll Attached to event OnClickButtonExpandAll .
Tries to expand all rows.
The ExpandAll can be asynchronous and can finish after the action returned.
The ExpandAll action can be stopped by a user during process.
<Cfg> bool ExpandAllLoaded [0] renamed 6.0 .
If set to 1 in server child paging (ChildPaging=3) the ExpandAll expands only rows with already downloaded children.
<Cfg> int ExpandAllLevels [3] new 6.0 .
Which levels will be expanded on ExpandAll.
0 – only one level, no sub nodes of actually expanding rows will be expanded.
1 – all already rendered children, the rest only one level
2 – all already downloaded children, the rest only one level
3 – all levels, the expanding can be done in more passing, because it waits for children to download
<Actions> CollapseAll Attached to event OnClickButtonCollapseAll .
Collapses all rows.
The CollapseAll can be asynchronous and can finish after the action returned.
<Actions> Indent ...F Not attached to any event .
Increases level of actual or focused row.
Moves the row as the last child of previous row.
<Actions> Outdent ...F Not attached to any event .
Decreases level of actual or focused row.
Moves the row below its parent row.
API event bool OnExpand (TGrid grid, TRow row) .
Called before the row is expanded or collapsed. Return true to suppress action.
Test the actual state by row.Expanded.
Return true to cancel the action.
API method void Expand (TRow row) .
Expands row, for child paging is asynchronous
API method void ExpandParents (TRow row) .
Expands all parents to show the row. The row must not be hidden (must have Visible=1). For child paging is asynchronous.
API method bool ExpandAll (TRow parent, int loaded = 0, int levels = 3) .
Expands all rows in parent and shows their children.
If parent is null, expands all rows in grid.
loaded is ExpandAllLoaded, levels is ExpandAllLevels.
Remember, in grid with ChildPaging is not often possible to expand all rows, because rendering of thousands of rows is very slow.
API method void Collapse (TRow row) .
Collapses row
API method void CollapseAll ( ) .
Collapses all rows