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