Using Tree Widgets

Tree widgets display information in a hierarchical structure or tree. Branches and sub-branches of the tree can be expanded and collapsed (either programmatically or by the user) to display or hide the information they contain. See WIDGET_TREE for a complete description of the function used to create tree widgets.

Types of Tree Widgets

Tree widgets behave slightly differently depending on whether their parent widget is a base widget or another tree widget:

If the tree widget's Parent is a base widget, the tree widget becomes the root of a new tree widget hierarchy. The tree widget itself is not displayed, but it becomes the parent widget for other tree widgets that are displayed. This type of tree widget is referred to as a root node. Note that a tree widget that is a root node cannot be the parent widget for any widget except another tree widget.

If the tree widget's Parent is an existing tree widget, the new tree widget becomes a branch node or leaf node in the existing tree widget. In this case:

If the FOLDER keyword to WIDGET_TREE is present, the node becomes a branch node. Tree widgets that are branch nodes can become the parent widget of other tree widgets (but not of any other type of widget).

If the FOLDER keyword to WIDGET_TREE is not present, the node becomes a leaf node. Leaf nodes cannot serve as the parent widget for any other widget.

Example: A Simple Tree

The following example builds a simple tree widget. Double-clicking on the leaf nodes toggles the value of the displayed text between the values "On" and "Off."

; Event handler routine. 
PRO tree_widget_example_event, ev 
 
  ; We use widget user values to determine what action to take. 
  ; First retrieve the user value (if any) from the widget that 
  ; generated the event. 
 
  WIDGET_CONTROL, ev.ID, GET_UVALUE=uName 
 
  ; If the widget that generated the event has a user value, check 
  ; its value and take the appropriate action. 
  IF (N_ELEMENTS(uName) NE 0) THEN BEGIN 
    IF (uName EQ 'LEAF') THEN BEGIN 
      ; Make sure the value does not change when the leaf node 
      ; is selected with a single click. 
      IF (ev.CLICKS EQ 2) THEN TWE_ToggleValue, ev.ID 
    ENDIF 
    IF (uName EQ 'DONE') THEN WIDGET_CONTROL, ev.TOP, /DESTROY 
  ENDIF 
 
END 
 
; Routine to change the value of a leaf node's text. 
PRO TWE_ToggleValue, widID 
 
  ; Get the current value. 
  WIDGET_CONTROL, widID, GET_VALUE=curVal 
 
  ; Split the string at the colon character. 
  full_string = STRSPLIT(curVal, ':', /EXTRACT) 
 
  ; Check the value of the text after the colon, and toggle 
  ; to the new value. 
  full_string[1] = (full_string[1] EQ ' Off') ? ': On' : ': Off' 
 
  ; Reset the value of the leaf node's text. 
  WIDGET_CONTROL, widID, SET_VALUE=STRJOIN(full_string) 
 
END 
 
; Widget creation routine. 
PRO tree_widget_example 
 
  ; Start with a base widget. 
  wTLB = WIDGET_BASE(/COLUMN, TITLE='Tree Example') 
 
  ; The first tree widget has the top-level base as its parent. 
  ; The visible tree widget branches and leaves will all be 
  ; descendants of this tree widget. 
  wTree = WIDGET_TREE(wTLB) 
 
  ; Place a folder at the root level of the visible tree. 
  wtRoot = WIDGET_TREE(wTree, VALUE='Root', /FOLDER, /EXPANDED) 
 
  ; Create leaves and branches. Note that we set the user value of 
  ; every leaf node (tree widgets that do not have the FOLDER 
  ; keyword set) equal to 'LEAF'. We use this in the event handler 
  ; to determine whether or not to change the text value. 
  wtLeaf11 = WIDGET_TREE(wtRoot, VALUE='Setting 1-1: Off', $ 
    UVALUE='LEAF') 
  wtBranch12 = WIDGET_TREE(wtRoot, VALUE='Branch 1-2', $ 
    /FOLDER, /EXPANDED) 
  wtLeaf121 =WIDGET_TREE(wtBranch12, VALUE='Setting 1-2-1: Off', $ 
    UVALUE='LEAF') 
  wtLeaf122 =WIDGET_TREE(wtBranch12, VALUE='Setting 1-2-2: Off', $ 
    UVALUE='LEAF') 
  wtLeaf13 = WIDGET_TREE(wtRoot, VALUE='Setting 1-3: Off', $ 
    UVALUE='LEAF') 
  wtLeaf14 = WIDGET_TREE(wtRoot, VALUE='Setting 1-4: Off', $ 
    UVALUE='LEAF') 
 
  ; Create a 'Done' button, setting its user value for use in the 
  ; event handler. 
  wDone = WIDGET_BUTTON(wTLB, VALUE="Done", UVALUE='DONE') 
 
  ; Realize the widgets and run XMANAGER to manage them. 
  WIDGET_CONTROL, wTLB, /REALIZE 
  XMANAGER, 'tree_widget_example', wTLB, /NO_BLOCK 
 
END

As with many of the examples in this chapter, this one is designed to merely exhibit the features of the tree widget. Most of the useful things you might do with a tree widget take place in the event handling routines for the leaf nodes; whereas in this example clicking on a leaf simply changes the displayed text value, in a real application more complicated things might take place. Alternately, you might use a tree widget for display purposes only, in which case user interaction would be limited to expanding and collapsing the branches.

Setting the Tree Selection State

You can programmatically select or deselect nodes in a tree widget hierarchy using the SET_TREE_SELECT keyword to WIDGET_CONTROL. Selecting a node or nodes visually highlights the node on the tree display. In the above example, placing the following command just above the call to XMANAGER:

WIDGET_CONTROL, wtLeaf11, /SET_TREE_SELECT

would cause the first leaf node to be highlighted when the widget tree was first displayed.

Making a Tree Entry Visible

If you tree is large or has many branches, you may need to explicitly bring a given node to the user's attention. You can do this using the SET_TREE_VISIBLE keyword to WIDGET_CONTROL:

WIDGET_CONTROL, wTreeNode, /SET_TREE_VISIBLE

were wTreeNode is any node attached to a tree widget - that is, any tree widget that has another tree widget as its parent widget. Setting this keyword has two possible effects:

Replacing the Default Bitmaps

By default, tree widgets use bitmap images of a folder and a single piece of paper as the icons representing branch and leaf nodes in a tree widget hierarchy. You can modify the look of the tree widget by supplying your own bitmap for a given node. Set the BITMAP keyword to WIDGET_TREE equal to a 16 x 16 x 3 array that contains a 24-bit color image.

For example, suppose you have a 16 x 16 pixel TrueColor icon stored in a TIFF file. The following commands make the image the icon used for the root node of a tree widget hierarchy:

myIcon = READ_TIFF('/path_to/myicon.tif', INTERLEAVE=2) 
wtRoot = WIDGET_TREE(wTree, /FOLDER, BITMAP=myIcon)

Note the use of the INTERLEAVE keyword to ensure that the resulting image array has dimensions 16 x 16 x 3. Depending on your image file format, you may need to modify the image array in other ways.

Using Images from the IDL Distribution

The /resources/bitmaps subdirectory of the IDL distribution contains a selection of 16-color (4-bit), 16 x 16 pixel icon images. To use these images as bitmaps in a tree widget, you must convert them to 16 x 16 x 3 (24-bit color) arrays.

The following code snippet loads the camera icon stored in IDLDIR/resources/bitmaps/camera.bmp into a 16 x 16 x 3 array:

; Create a 24-bit image array. 
imageRGB = BYTARR(16,16,3,/NOZERO) 
; Read in the bitmap. 
file=FILEPATH('camera.bmp', SUBDIR=['resource', 'bitmaps']) 
image8 = READ_BMP(file, Red, Green, Blue) 
; Pass the image through the color table 
imageRGB[0,0,0] = Red[image8] 
imageRGB[0,0,1] = Green[image8] 
imageRGB[0,0,2] = Blue[image8]

To use the camera icon in a tree widget, you would specify the imageRGB variable as the value of the BITMAP keyword to WIDGET_TREE.