Tree

TreeGrid documentation

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.
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.
Changes MainCol to given column.
If set noshow, does not call RenderBody to display changes.
0 - it shows standard tree from top, children are below their parent
1 - it shows MS Excel summary outline tree, from bottom, children are above their parent
Sets value of ReversedTree and renders body.
For noshow = 1 does not render body and requires rerender.
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.
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.
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 (-).
(Since 12.0) X = 6 line through, used only with custom icons 0 - 5, 7 no line through, used only if defined also 6, 8 - wait expand (+), 9 - last wait expand (+).
(Since 12.0) X = 10 - drag above, 11 - last drag above, 12 - drag into, 13 - last drag into, 14 - drag below, 15 - last drag below, 16 - no drag, 17 - last no drag.
If set NoTreeLines, only values 0, 2, 4, 8, 10, 12 and 14 are used.
The last is the 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 set to standard Tree icon or to TreeWidthX.
Custom widths of tree icons and indent. Are used only if set SpannedTree='1'.
X = 0 - tree level indent. 1 - width of leaf or not expandable button, 2 - width of expand / collapse button.
Since 12.0 it can be used with any value of NoTreeLines, but for tree lines only with custom TreeIconX.
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'.
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'.
It can be set only in Header row in MainCol column.
If set, it displays buttons for tree levels, like in MS Excel outline. After click to the button, it expands / collapses the rows to show up to the selected level.
If set to 1, the button count is equal to the maximal tree level in grid (= max Level + 1).
If set to >1, it displays maximally given button count.
The count of level buttons is updated after grouping changes. It is also increased, but not decreased, after moving or adding rows.
If set, shows minimally this count of Levels buttons. Useful in server paging, when the tree depth is unknown.
Hides the first line in tree (root items are without any line).
Root rows become not expandable, so they should be all Expanded.
Set it to 1 if some MainCol cell is spanned between columns (has set Span attribute).
Set it to 1 along with NoTreeLines to control widths of the tree icons and indent by TreeWidthX.
If set to 1, it shows tree icons in included <table> tag and slows down rendering.
Cannot be used when the main column cells have set RowSpan.
If set to 1, it does not show connecting lines in tree, shows only expand / collapse buttons.
Use especially for custom icons or tree indent widths.
If set to 1, it does not show connecting lines in tree when printing, shows only expand / collapse buttons.
If empty, uses value of NoTreeLines.
Sets value of the NoTreeLines and re-renders grid.
Row's level in tree. Only for variable rows.
-1 = page, 0 root row, 1 first level children, 2 second level children, ...
Returns true if row has some visible children (shows icon expand/collapse).
Returns row's position in its parent. It counts only visible rows.
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. Cannot be used for automatically created group rows.
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.
If defined both Expanded and Collapsed attributes, even empty, the row expanded state is changed only if the row is present in one of the lists.
It overrides the states saved by SaveExpanded.
All rows (comma separated ids) that will be collapsed, all other rows will be expanded if the attribute is present.
It is done on start and also after every page / child page load in server paging.
If defined both Expanded and Collapsed attributes, even empty, the row expanded state is changed only if the row is present in one of the lists.
It overrides the states saved by SaveExpanded.
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.

Actions and API for expand / collapse

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.
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.
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.
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 the process.
If set to 1 in server child paging (ChildPaging=3) the ExpandAll expands only rows with already downloaded children.
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.
Collapses all rows.
The CollapseAll can be asynchronous and can finish after the action returned.
Collapses all rows in the first expanded collapsible level. All rows in grid will look collapsed, but they could contain expanded children.
The CollapseAll can be asynchronous and can finish after the action returned.
Increases level of actual or focused row.
Moves the row as the last child of previous row.
Increases level of all selected rows.
Moves every selected row as the last child of previous row. It never moves selected row as child of another selected row.
Since 12.0 version without ...F fails if the actual row is not selected.
Increases level of focused rows on the same level as the first focused row.
Moves every focused row as the last child of previous row.
Version without ...F fails if the actual cell is not focused.
Decreases level of actual or focused row.
Moves the row below its parent row.
Decreases level of all selected rows.
Moves every selected row below its parent row. It never move the row if its parent is also selected.
Since 12.0 version without ...F fails if the actual row is not selected.
Decreases level of focused rows on the same level as the first focused row.
Moves every focused row below its parent row.
Version without ...F fails if the actual cell is not focused.
Expands / collapses grid after click to Levels button.
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.
Expands row, for child paging is asynchronous.
Expands all parents to show the row. The row must not be hidden (must have Visible=1). For child paging is asynchronous.
Expands all rows in parent and shows their children.
If parent is null, expands all rows in grid.
loaded is ExpandAllLoaded, levels is ExpandAllLevels.
max (since 12.0) is maximal level to expand, 0 expands only root rows, 1 expands root rows and their immediate children, etc.
(since 12.0) if set test = 1, it does not do anything, just returns count of affected rows.
Remember, in grid with ChildPaging is not often possible to expand all rows, because rendering of thousands of rows is very slow.
Called after expanding all rows finished (cancelled = 0) or was interrupted (cancelled = 1).
cancelled is -1 if there were no rows to expand.
Note, in child parts it is called before the child parts are rendered.
Collapses row.
Collapses all rows.
Since 12.0 for root = 1 collapses only first expanded level.
Since 12.0 for text = 1 does not do any change, just returns count of the collapsible rows.
Since 12.0 returns count of collapsed rows.
Collapses / expands rows to show exactly given tree level. level is 1 for root level (collapses all), 2 for second level (expands the root rows), etc.