TreeGrid v6.0

Tree

TreeGrid documentation index

 

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.

 

 

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.

 

<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