The WIDGET_TREE function is used to create and populate a tree widget. The tree widget presents a hierarchical view that can be used to organize a wide variety of data structures and information.
The WIDGET_TREE function performs two separate tasks: creating the tree widget and populating the tree widget with nodes (branches and leaves).
For a more detailed discussion of the tree widget, along with examples, see Using Tree Widgets.
Result = WIDGET_TREE( Parent [, /ALIGN_BOTTOM | , /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT | , /ALIGN_TOP] [, BITMAP=array] [, /CONTEXT_EVENTS] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, /EXPANDED] [, /FOLDER] [, FUNC_GET_VALUE=string] [, GROUP_LEADER=widget_id] [, KILL_NOTIFY=string] [, /MULTIPLE] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, /SENSITIVE] [, TAB_MODE=value] [, /TRACKING_EVENTS] [, /TOP] [, UNAME=string] [, UNITS={0 | 1 | 2}] [, UVALUE=value] [, VALUE=string] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value] )
The returned value of this function is the widget ID of the newly-created tree widget.
The widget ID of the parent for the new tree widget. Parent can be either a base widget or a tree widget.
| Note |
Set this keyword to align the new widget with the bottom of its parent base. To take effect, the parent must be a ROW base.
Set this keyword to align the new widget with the center of its parent base. To take effect, the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be vertically centered. In COLUMN bases, the new widget will be horizontally centered.
Set this keyword to align the new widget with the left side of its parent base. To take effect, the parent must be a COLUMN base.
Set this keyword to align the new widget with the right side of its parent base. To take effect, the parent must be a COLUMN base.
Set this keyword to align the new widget with the top of its parent base. To take effect, the parent must be a ROW base.
Set this keyword equal to a 16x16x3 array representing an RGB image that will be displayed next to the node in the tree widget.
Set this keyword to cause context menu events (or simply context events) to be issued when the user clicks the right mouse button over the widget. Set the keyword to 0 (zero) to disable such events. Context events are intended for use with context-sensitive menus (also known as pop-up or shortcut menus); pass the context event ID to the WIDGET_DISPLAYCONTEXTMENU within your widget program's event handler to display the context menu.
For more on detecting and handling context menu events, see Context-Sensitive Menus.
This keyword is only valid if the Parent of the tree widget is a base widget.
A string containing the name of a function to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget.
A string containing the name of a procedure to be called by the WIDGET_EVENT function when an event arrives from a widget in the widget hierarchy rooted at the newly-created widget.
If the tree node being created is a folder (specified by the FOLDER keyword), set this keyword to cause the folder to be initially displayed expanded, showing all of its immediate child entries. By default, folders are initially displayed collapsed.
This keyword is only valid if the Parent of the tree widget is another tree widget.
Set this keyword to cause the tree node being created to act as a folder (that is, as a branch of the tree rather than a leaf).
| Note |
This keyword is only valid if the Parent of the tree widget is another tree widget.
A string containing the name of a function to be called when the GET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to change the value that should be returned for a widget. Compound widgets use this ability to define their values transparently to the user.
The widget ID of an existing widget that serves as group leader for the newly-created widget. When a group leader is killed, for any reason, all widgets in the group are also destroyed.
A given widget can be in more than one group. The WIDGET_CONTROL procedure can be used to add additional group associations to a widget. You cannot remove a widget from an existing group.
Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such callback procedure. This callback procedure can be removed by setting the routine name to the null string (''). Note that the procedure specified is used only if you are not using the XMANAGER procedure to manage your widgets.
The callback routine is called with the widget identifier as its only argument. At that point, the widget identifier can only be used with the WIDGET_CONTROL procedure to get or set the user value. All other requests that require a widget ID are disallowed for the target widget. The callback is not issued until the WIDGET_EVENT function is called.
If you use the XMANAGER procedure to manage your widgets, the value of this keyword is overwritten. Use the CLEANUP keyword to XMANAGER to specify a procedure to be called when a managed widget dies.
Set this keyword to enable multiple selection operations in the tree widget. If enabled, multiple elements in the tree widget can be selected at one time by holding down the Control or Shift key while clicking the left mouse button.
This keyword is only valid if the Parent of the tree widget is a base widget.
Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique works well for small data, it can have a significant memory cost when the data being copied is large.
If the NO_COPY keyword is set, IDL handles these operations differently. Rather than copying the source data, it takes the data away from the source and attaches it directly to the destination. This feature can be used by compound widgets to obtain state information from a UVALUE without all the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. Upon a set operation (using the UVALUE keyword to WIDGET_TAB or the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. Upon a get operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined.
Set this keyword to a string containing the name of a procedure to be called automatically when the specified widget is realized. This callback occurs just once (because widgets are realized only once). Each widget is allowed a single such callback procedure. This callback procedure can be removed by setting the routine name to the null string (''). The callback routine is called with the widget ID as its only argument.
A string containing the name of a procedure to be called when the SET_VALUE keyword to the WIDGET_CONTROL procedure is called for this widget. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user.
Set this keyword to the desired screen width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword.
Set this keyword to the desired screen height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword.
Set this keyword to control the initial sensitivity state of the widget.
If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input.
Sensitivity can be used to control when a user is allowed to manipulate the widget.
| Note |
After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL.
Set this keyword to one of the values shown in the table below to determine how the widget hierarchy can be navigated using the Tab key. The TAB_MODE setting is inherited by lower-level bases and child widgets from the parent WIDGET_BASE unless it is explicitly set on an individual widget. If the TAB_MODE value of the widget differs from that of the base, the setting on the widget will be respected when the widget has focus. For example, if a base does not support tabbing, but an individual child widget does support tabbing, this functionality will be enabled when the child widget has focus.
| Note |
Valid settings are:
|
Value
|
Description
|
|---|---|
| 0 |
Disable navigation onto or off of the widget. This is the default unless the TAB_MODE has been set on a parent base. Child widgets automatically inherit the tab mode of the parent base as described in Inheriting the TAB_MODE Value.
|
| 1 |
Enable navigation onto and off of the widget.
|
| 2 |
Navigate only onto the widget.
|
| 3 |
Navigate only off of the widget.
|
| Note |
Once a WIDGET_TREE widget receives focus through tabbing, additional navigation capabilities are platform dependent:
Use the arrow keys to select higher or lower level nodes once a tree widget has focus. The TAB_MODE specified for the root tree widget defines the tabbing support for all of its nodes.
After creating the widget hierarchy, you can change tabbing support using the WIDGET_CONTROL procedure's TAB_MODE keyword, or query a widget's support for tabbing using the WIDGET_INFO procedure's TAB_MODE keyword.
See Tabbing in Widget Applications for usage details and examples.
Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. For the structure of tracking events, see TRACKING_EVENTS in the documentation for WIDGET_BASE.
Set this keyword to cause the tree node being created to be inserted as the parent node's top entry. By default, new nodes are inserted as the parent node's bottom entry.
This keyword is only valid if the Parent of the tree widget is another tree widget.
Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.
To query the widget hierarchy, use the WIDGET_INFO with the FIND_BY_UNAME keyword. The UNAME should be unique to the widget hierarchy because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (which is the default), to 1 (one) to specify that all measurements are in inches, or to 2 (two) to specify that all measurements are in centimeters.
The user value to be assigned to the widget.
Each widget can contain a user-specified value of any data type and organization. This value is not used by the widget in any way, but exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value when the widget is first created.
If UVALUE is not present, the widget's initial user value is undefined.
Set this keyword equal to a string containing the text that will be displayed next to the tree node. If this keyword is not set, the default value Tree is used.
| Note |
This keyword is only valid if the Parent of the tree widget is another tree widget.
The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. You should avoid using this style of widget programming.
The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a hint to the toolkit and may be ignored in some situations.
The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.
Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. You should avoid using this style of widget programming.
The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a hint to the toolkit and may be ignored in some situations.
A number of keywords to the WIDGET_CONTROL affect the behavior of tree widgets. In addition to those keywords that affect all widgets, the following keywords are particularly useful: SET_TREE_BITMAP, SET_TREE_EXPANDED, SET_TREE_SELECT, SET_TREE_VISIBLE.
Some keywords to the WIDGET_INFO return information that applies specifically to tree widgets. In addition to those keywords that apply to all widgets, the following keywords are particularly useful: TREE_EXPANDED, TREE_SELECT, and TREE_ROOT.
Several variations of the tree widget event structure depend upon the specific event being reported. All of these structures contain the standard three fields (ID, TOP, and HANDLER) as well as an integer TYPE field that indicates which type of structure has been returned. Programs should always check the type field before referencing fields that are not present in all tree event structures. The different tree widget event structures are described below.
This structure is returned when the currently selected node in the tree widget changes:
{WIDGET_TREE_SEL, ID:0L, TOP:0L, HANDLER:0L, TYPE:0, CLICKS:0L}
The CLICKS field indicates the number of mouse-button clicks that occurred when the event took place. This field contains 1 (one) when the item is selected, or 2 when the user double-clicks on the item.
This structure is returned when a folder in the tree widget expands or collapses:
{WIDGET_TREE_EXPAND, ID:0L, TOP:0L, HANDLER:0L, TYPE:1, EXPAND:0L}
The EXPAND field contains 1 (one) if the folder expanded or 0 (zero) if the folder collapsed.
A tree widget created with the CONTEXT_EVENTS keyword set returns the following event structure in response to a right mouse button click:
{WIDGET_CONTEXT, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L,
ROW:0L, COL:0L}
The first three fields are the standard fields found in every widget event. The X and Y fields give the device coordinates at which the event occurred, measured from the upper left corner of the tree widget. The ROW and COL fields return meaningful information for table widgets and values of zero (0) for other widgets.
Introduced: 5.6
TAB_MODE keyword added: 6.1
ROW and COL fields of WIDGET_CONTEXT event structure added: 6.1