## Tree

### Description

The Tree class implements a control for displaying and manipulating hierarchical lists. It comprises a tree of 'nodes', which can be expanded or collapsed by the user. Examples are the left-hand pane of the APLX 'Workspace Explorer' window, or Microsoft's 'Windows Explorer'. Under Windows and Linux, you can optionally associate an ImageList with the Tree, to display images next to the nodes.

#### Tree properties

The main Tree properties are:

`style`: The sum of the following flags:

          1 = Hide the buttons at the nodes.
          2 = Hide the lines connecting the children.
          4 = Show the top-level (root) node
          8 = Highlight the selection even if control does not have focus
          16 = Allow the user to edit the labels (Windows only)
         128 = Disable rather than hide unneeded scroll bars (MacOS only)

`list`: A nested matrix (or vector) of either 3, 4 or 5 columns, and one row for each node. The columns are:

          [;1] An integer node identifier. If you specify 0, APLX assigns
               a unique value for each node.
          [;2] An integer representing node depth, typically 1 = the top level.
          [;3] A character vector giving the label to display for this node
          [;4] A vector of four indices into the list of images associated with the
               control. These are the Unselected, Selected, Overlay, and State images,
               in index origin 1. 0 means no image.  Ignored under MacOS.
          [;5] A nested vector of keywords giving the state of the node.

The state keywords are: `'highlightbold'`, `'highlightcut'`, `'highlightdrop'`, `'highlightselect'`, `'expanded'`, `'expandedonce'`, `'haschildren'` and `'forceparent'`. Precede the keyword by a minus sign to switch off the state. The `'highlightcut'`, `'highlightdrop'` and `'forceparent'` keywords apply to Windows only, and are ignored under MacOS.

`imagelist` (Windows and Linux only): A character vector containing the name of the main ImageList associated with the Tree. The first two elements of the fourth column of the `list` property are indexes into this list of images, and the third element is an index into the `overlays` property of this list.

`imagelistuser` (Windows and Linux only): A character vector containing the name of the secondary (user) ImageList associated with the Tree. The fourth element of the fourth column of the `list` property is an index into this list of images.

`indent`: The tree indentation in the current `scale` units

`value`: The ID of the currently-selected node

`highlightbold`: An integer vector specifying which nodes are bold highlighted

`highlightcut`: An integer vector specifying which nodes are highlighted for cutting

`highlightdrop`: An integer vector specifying which nodes are highlighted for dropping

`highlightselect`: An integer vector specifying which nodes are highlighted for selection

#### Tree methods

The main Tree methods are:

`Expand`: Control how a node displays. The method takes a length-2 nested vector. The first element is a keyword indicating the action. The second element is an integer, the node ID. The action keywords are:

            expand          Open node to display children
            collapse        Close node to hide children
            toggle          Expand closed node or collapse open node
            expandbranch    Open node to display children (recursively)
            collapsebranch  Close node to hide children (recursively)
            collapsereset   Removes all descendants

`EnsureVisible`: Ensure that a given node is visible, expanding any parents if they are currently collapsed, and scrolling the node into view. Takes a single integer argument, the node ID.

`ShowNode`: Select a node, or make it visible as the first item visible in the window. The method takes a length-2 nested vector. The first element is a keyword indicating the action. The second element is an integer, the node ID, or is 0 or `'none'` to indicate the currently-selected node. The action keywords are:

            select          Select the node
            drop            make the node the drag-and-drop target (Windows only)
            firstvisible    Make node visible at top of window

`Ensurevisible`: Ensure that a given node is visible, expanding and/or scrolling the tree if necessary. The argument is the node ID to be shown.

`SortChildren`: (Windows Only) Sort the children of a node, and optionally recurses through all descendants. First argument is node identifier, or character vector `'root'`. The optional second argument is the character vector `'recurse'`.

`DeleteNodes`: Delete one or more nodes. Argument is a vector of node IDs to delete.

`InsertNodes`: Insert one or more nodes. The first argument is node id of parent (or `'root'`). The second argument is node id of preceding sibling (or `'first'`, `'last'`, or `'sort'`). The third argument is a matrix (or vector for single node), as per the `list` property.

`Setinfo`: Sets various attributes of one or more nodes.

`Getinfo`: Retrieves various attributes of one or more nodes (Windows only).

`Beginlabeledit`: Allows the user to start editing a node's label (Windows only).

`Cancellabeledit`: Ends label editing.

`Hittest`: Determines which node a point on the control corresponds to.

`Findnode`: Finds a node given various criteria.

### Example

         ’DEMO_Tree;TREE;ŒIO;NAMES;DEMO
    [1]   © Sample function demonstrating use of the Tree object
    [2]   ŒIO„1
    [3]   DEMO„'Œ' ŒNEW 'Window' ª DEMO.title„'Tree Example'
    [4]   DEMO.myTree.New 'Tree' ª DEMO.myTree.align„¯1 ª DEMO.myTree.style„12
    [5]   TREE„11 5½0
    [6]   TREE[;2]„1 2 2 3 3 3 4 4 2 2 1
    [7]   NAMES„'Work' 'APL Workspaces' 'Documents' 'Reports' 'Letters'
    [8]   NAMES„NAMES,'Planning' 'Product plan' 'Strategic plan'
    [9]   NAMES„NAMES,'Spreadsheets' 'Graphics' 'Personal'
    [10]  TREE[;3]„NAMES
    [11]  TREE[;4]„11½›1 1 0 0
    [12]  TREE[;5]„11½›0½'' ''
    [13]  TREE[1 3 6 11;5]„4½›'HIGHLIGHTBOLD' 'EXPANDED'
    [14]  DEMO.myTree.list„TREE
    [15]  ©
    [16]  © Wait for the user to close the window
    [17]  0 0½ŒWE DEMO
         ’

### Properties

align anchors aquaadjust autodraw border caption children class color count data doublebuffered dragsource droptarget enabled events extent font handle highlightbold highlightcut highlightdrop highlightselect imagelist imagelistuser indent labeledithwnd list maxsize methods minsize name opened order pointer properties scale searchstring self size sourceformats style tabstop targetformats tie tooltip units value visible where winptr

### Methods

Beginlabeledit Cancellabeledit Click Clienttoscreen Close Create Delete Deletenodes Draw Ensurevisible Expand Findnode Getinfo Focus Hide Hittest Insertnodes New Open Paint Resize Screentoclient Send Set Setinfo Show Shownode Sortchildren Trigger

### Callbacks

onClick onClose onDblClick onDestroy onDragDrop onDragEnd onDragEnter onDragLeave onDragOver onDragStart onFocus onHide onKeyDown onKeyPress onKeyUp onMouseDown onMouseMove onMouseUp onOpen onSelChange onSend onShow onUnFocus

Topic: APLX Help : System Classes : List of Classes : Tree

[ Previous | Contents | Index ]