The ability to create multi-level lists is the reason why this routine and control is called XTREE (and not XTABLE or XLIST). But they do present several additional considerations and complications discussed below.

Determining which items are displayed: Absent any special instructions, the default it to start with just the top level items displayed. The program can override this when the tree is first displayed via the XTR.EXPANDLEVEL parameter. For even more control, a special control column using the cformat code (=) allows the program to ascertain and also set the Expand/Collapse State for every item.

User controls for expanding/collapsing: See the multi-level tree section under Mouse and Keyboard techniques. Note that under application control you could augment the user controls. For example, to auto-expand a level whenever the parent is selected, you could use the SelChgExit and/or ClickExit Advanced Coldef Options in conjunction with the expand/collapse state column type to force the tree to return to the application whenever the selection changes, and then programmatically set the expand/collapse flag. Similarly you could respond to the selection (via double-click or ENTER) of a parent item to force expansion. Also see ExpandExit to intercept the user's request to expand/collapse an item.

Options for the expand/collapse indicators: By default, each item with dependent children will be preceded by a +/- button that can be clicked to expand or collapse the dependents. See XTR.SHOWBUTTONS for options concerning the visibility of the expand/collapse buttons. You can also associate an icon with each of the three item states (expandable, expanded, leaf) similar to the way Explorer shows folder and file icons; see XTF2_ITEMICONS for details.

Sorting: When sorting a column in a multi-level tree, only the top level (level 0) items are sorted. The dependents move along with their respective parents but are not themselves sorted within each group of siblings. See the Sorting section under Mouse and Keyboard techniques for more details.

Column Definitions by Level: Since you can only have one set of column definitions, when using multiple levels, typically the higher levels may have blank columns, and you may need to interpret the contents of the columns differently depending on the level. In file mode, the level flag (as defined by the @ code in coldef ) is returned with the selection, allowing you to interpret the result appropriately. In array mode, you get back the selected array index(es) and can refer to the original array data to determine the level of the selected item(s). Note that the array index returned will be relative to the array you pass, and is not affected by sorting.