WIDGET_INFO

WIDGET_INFO

The WIDGET_INFO function is used to obtain information about the widget subsystem and individual widgets. The specific area for which information is desired is selected by setting the appropriate keyword.

Syntax

Result = WIDGET_INFO( [Widget_ID] )

Keywords that apply to all widgets: [, /ACTIVE] [, /CHILD] [, /EVENT_FUNC] [, /EVENT_PRO] [, FIND_BY_UNAME=string] [, /FONTNAME] [, /GEOMETRY] [, /KBRD_FOCUS_EVENTS] [, /MANAGED] [, /MAP] [, /NAME] [, /PARENT] [, /REALIZED] [, /SENSITIVE] [, /SIBLING] [, /SYSTEM_COLORS] [, /TAB_MODE] [, /TRACKING_EVENTS] [, /TYPE] [, UNITS={0 | 1 | 2}] [, /UNAME] [, /UPDATE] [, /VALID_ID] [, /VERSION] [, /VISIBLE]

Keywords that apply to widgets created with WIDGET_BASE: [, /CONTEXT_EVENTS] [, /MODAL] [, /TLB_ICONIFY_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] [, /TLB_MOVE_EVENTS] [, /TLB_SIZE_EVENTS]

Keywords that apply to widgets created with WIDGET_BUTTON: [, /BUTTON_SET] [, /DYNAMIC_RESIZE] [, /PUSHBUTTON_EVENTS] [, /TOOLTIP]

Keywords that apply to widgets created with WIDGET_COMBOBOX: [, /COMBOBOX_GETTEXT] [, /COMBOBOX_NUMBER] [, /DYNAMIC_RESIZE]

Keywords that apply to widgets created with WIDGET_DRAW: [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, DRAW_KEYBOARD_EVENTS={0 | 1 | 2}] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] [, /TOOLTIP]

Keywords that apply to widgets created with WIDGET_DROPLIST: [, /DROPLIST_NUMBER] [, /DROPLIST_SELECT] [, /DYNAMIC_RESIZE]

Keywords that apply to widgets created with WIDGET_LABEL: [, /DYNAMIC_RESIZE]

Keywords that apply to widgets created with WIDGET_LIST: [, /CONTEXT_EVENTS] [, /LIST_MULTIPLE] [, /LIST_NUMBER] [, /LIST_NUM_VISIBLE] [, /LIST_SELECT] [, /LIST_TOP]

Keywords that apply to widgets created with WIDGET_PROPERTYSHEET: [, /CONTEXT_EVENTS] [, COMPONENT=objref] [, /MULTIPLE_PROPERTIES] [, PROPERTY_VALID=string] [, PROPERTY_VALUE=string] [, /PROPERTYSHEET_NSELECTED] [, /PROPERTYSHEET_SELECTED]

Keywords that apply to widgets created with WIDGET_SLIDER: [, /SLIDER_MIN_MAX]

Keywords that apply to widgets created with WIDGET_TAB: [, /TAB_CURRENT] [, /TAB_MULTILINE] [, /TAB_NUMBER]

Keywords that apply to widgets created with WIDGET_TABLE: [, /COLUMN_WIDTHS] [, /CONTEXT_EVENTS] [, /ROW_HEIGHTS{not supported in Windows}] [, /TABLE_ALL_EVENTS] [, /TABLE_DISJOINT_SELECTION] [, /TABLE_EDITABLE] [, /TABLE_EDIT_CELL] [, /TABLE_SELECT] [, /TABLE_VIEW] [, /USE_TABLE_SELECT]

Keywords that apply to widgets created with WIDGET_TEXT: [, /CONTEXT_EVENTS] [, /TEXT_ALL_EVENTS] [, /TEXT_EDITABLE] [, /TEXT_NUMBER] [, TEXT_OFFSET_TO_XY=integer] [, /TEXT_SELECT] [, /TEXT_TOP_LINE] [, TEXT_XY_TO_OFFSET=[column, line]]

Keywords that apply to widgets created with WIDGET_TREE: [, /CONTEXT_EVENTS] [, /TREE_EXPANDED] [, /TREE_ROOT] [, /TREE_SELECT]

Return Value

Returns the specified information for the given widget ID. If the SYSTEM_COLORS keyword is specified, a structure is returned. See The WIDGET_SYSTEM_COLORS Structure for details.

Arguments

Widget_ID

Usually this argument should be the widget ID of the widget for which information is desired. If the ACTIVE or VERSION keywords are specified, this argument is not required.

Widget_ID can also be an array of widget identifiers, in which case the result is an array with the same structure in which information on all the specified widgets is returned.

Keywords

Not all keywords to WIDGET_INFO apply to all combinations of widgets. In the following list, descriptions of keywords that affect only certain types of widgets include a list of the widgets for which the keyword is useful.

ACTIVE

This keyword applies to all widgets.

Set this keyword to return 1 if there is at least one realized, managed, top-level widget on the screen. Otherwise, 0 is returned.

BUTTON_SET

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to return the "set" state of a widget button. If the button is currently set, 1 (one) is returned. If the button is currently not set, 0 (zero) is returned. This keyword is intended for use with exclusive, non-exclusive and checked menu buttons.

CHILD

This keyword applies to all widgets.

Set this keyword to return the widget ID of the first child of the widget specified by Widget_ID. If the widget has no children, 0 is returned.

COLUMN_WIDTHS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return an array of long integers giving the width of each column in the table. If USE_TABLE_SELECT is set equal to one, only the column widths for columns that contain currently-selected cells are returned. If USE_TABLE_SELECT is set equal to an array, only the column widths for columns that contain specified cells are returned.

COMBOBOX_GETTEXT

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to return the current text from the text box of the specified combobox widget. Note that when using an editable combobox, the text displayed in the text box may not be an item from the list of values in the combobox list. To obtain the index of the selected item, inspect the INDEX field of the event structure returned by the combobox widget.

COMBOBOX_NUMBER

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to return the number of elements currently contained in the list of the specified combobox widget.

COMPONENT

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to an object reference to indicate which object to query. This is most useful when the property sheet references multiple objects. If this keyword is not specified, the first (possibly only) object is queried.

CONTEXT_EVENTS

This keyword applies to widgets created with the WIDGET_BASE, WIDGET_LIST, WIDGET_PROPERTYSHEET, WIDGET_TABLE, WIDGET_TEXT or WIDGET_TREE functions.

Set this keyword to return 1 (one) if the widget specified by Widget_ID is configured to generate context events (that is, the widget was created with the CONTEXT_EVENTS keyword). Otherwise, 0 (zero) is returned.

DRAW_BUTTON_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the BUTTON_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_EXPOSE_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the EXPOSE_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_KEYBOARD_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return an integer specifying the type of keyboard events currently generated by the draw widget specified by Widget_ID. Possible values are:

0: No keyboard events are generated

1: Keyboard events are generated for "normal" keys (all keys except function keys and modifier keys: Shift, Control, Caps Lock, and Alt).

2: Keyboard events are generated for "normal" keys and modifier keys.

Note

Keyboard events are never generated for function keys.

DRAW_MOTION_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the MOTION_EVENTS attribute set. Otherwise, 0 is returned.

DRAW_VIEWPORT_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to return 1 if Widget_ID is a draw widget with the VIEWPORT_EVENTS attribute set. Otherwise, 0 is returned.

DROPLIST_NUMBER

This keyword applies to widgets created with the WIDGET_DROPLIST function.

Set this keyword to return the number of elements currently contained in the specified droplist widget.

DROPLIST_SELECT

This keyword applies to widgets created with the WIDGET_DROPLIST function.

Set this keyword to return the zero-based number of the currently-selected element (i.e., the currently-displayed element) in the specified droplist widget.

DYNAMIC_RESIZE

This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_COMBOBOX, WIDGET_DROPLIST, and WIDGET_LABEL functions.

Set this keyword to return a True value (1) if the widget specified by Widget_ID is a button, droplist, or label widget that has had its DYNAMIC_RESIZE attribute set. Otherwise, False (0) is returned.

EVENT_FUNC

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the event handler function associated with Widget_ID. A null string is returned if no event handler function exists.

EVENT_PRO

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the event handler procedure associated with Widget_ID. A null string is returned if no event handler procedure exists.

FIND_BY_UNAME

This keyword applies to all widgets.

Set this keyword to a UNAME value that will be searched for in the widget hierarchy, and if a widget with the given UNAME is in the hierarchy, its ID is returned. The search starts in the hierarchy with the given widget ID and travels down, and this keyword returns the widget ID of the first widget that has the specified UNAME value.

If a widget is not found, 0 is returned.

FONTNAME

This keyword applies to all widgets.

Set this keyword to return a string containing the name of the font being used by the specified widget. The returned name can then be used when creating other widgets or with the SET_FONT keyword to the DEVICE procedure. If fonts are not supported by the specified widget, an empty string is returned.

Note that you can use this keyword to retrieve the name of the default font used by one type of widget and use the same font in other contexts. For example, the following code retrieves the default font used for buttons and writes into the drawable area of a draw widget using the same font:

wBase = WIDGET_BASE(/ROW) 
wButton = WIDGET_BUTTON(wBase, VALUE="Button") 
wDraw = WIDGET_DRAW(wBase, XSIZE=200, YSIZE=100) 
WIDGET_CONTROL, wBase, /REALIZE 
strFont = WIDGET_INFO(wButton, /FONTNAME) 
DEVICE, SET_FONT=strFont 
WIDGET_CONTROL, wDraw, GET_VALUE=iWindow 
WSET, iWindow 
XYOUTS, 100, 50, 'Same Font as Button', FONT=0, /DEVICE, $ 
   ALIGNMENT=.5

This method allows you to synchronize the fonts in several widgets without knowing in advance which font is in use.

The format of the returned font name is platform dependent. See About Device Fonts for additional details.

GEOMETRY

This keyword applies to all widgets.

Note

Some widgets have no geometry values of their own. For example, only the root node of a tree widget hierarchy has associated geometry values. Similarly, buttons created on a pop-up menu have no geometry. Widgets with no intrinsic geometry values will return a WIDGET_GEOMETRY structure containing all zeroes.

Set this keyword to return a WIDGET_GEOMETRY structure that describes the offset and size information for the widget specified by Widget_ID. This structure has the following definition:

{ WIDGET_GEOMETRY,  
   XOFFSET:0.0, 
   YOFFSET:0.0, 
   XSIZE:0.0, 
   YSIZE:0.0, 
   SCR_XSIZE:0.0, 
   SCR_YSIZE:0.0, 
   DRAW_XSIZE:0.0, 
   DRAW_YSIZE:0.0, 
   MARGIN:0.0, 
   XPAD:0.0, 
   YPAD:0.0, 
   SPACE:0.0 }

With the exception of MARGIN, all of the structure's fields correspond to the keywords of the same name to the various widget routines. MARGIN is the width of any frame added to the widget, in units specified by the UNITS keyword (pixels are the default). Therefore, the actual width of any widget is:

SCR_XSIZE + (2* MARGIN)

The actual height of any widget is:

SCR_YSIZE + (2 * MARGIN)

Note

Different window managers may use different window dressing (borders, margins, scrollbars, etc.). As a result, running a given segment of widget code on different platforms may yield different geometry.

Note

In most cases, setting SCR_XSIZE (or SCR_YSIZE) for a base widget should override the value set via the XSIZE (or YSIZE) keyword. For unrealized base widgets on Microsoft Windows platforms, however, the returned WIDGET_GEOMETRY structure will report the specified value of XSIZE (or YSIZE) rather than the value supplied via the SCR_XSIZE (or SCR_YSIZE) keyword.

Note

For table widgets, the YSIZE and XSIZE values return the total number of rows and columns, which may differ from the visible number of rows and columns.

KBRD_FOCUS_EVENTS

This keyword applies to all widgets.

Set this keyword to return the keyboard focus events status of the widget specified by Widget ID. WIDGET_INFO returns 1 (one) if keyboard focus events are currently enabled for the widget, or 0 (zero) if they are not. Only base, table, and text widgets can generate keyboard focus events.

LIST_MULTIPLE

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword equal to a named variable that will contain a non-zero value if the list widget supports multiple item selections. See the MULTIPLE keyword to WIDGET_LIST for more on multiple item selections.

LIST_NUMBER

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the number of elements currently contained in the specified list widget.

LIST_NUM_VISIBLE

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the number of elements that can be visible in the scrolling viewport of the specified list widget. Note that this value can be larger than the total number of elements actually in the list.

LIST_SELECT

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the index or indices of the currently selected (highlighted) element or elements in the specified list widget. Note that this offset is zero-based. If no element is currently selected, -1 is returned.

LIST_TOP

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to return the zero-based offset of the topmost element currently visible in the specified list widget.

MANAGED

This keyword applies to all widgets.

Set this keyword to return 1 if the specified widget is managed, or 0 otherwise. If no widget ID is specified in the call to WIDGET_INFO, the return value will be an array containing the widget IDs of all currently-managed widgets.

MAP

This keyword applies to all widgets.

Set this keyword to return True (1) if the widget specified by Widget_ID is mapped (visible), or False (0) otherwise. Note that when a base widget is unmapped, all of its children are unmapped. If WIDGET_INFO reports that a particular widget is unmapped, it may be because a parent in the widget hierarchy has been unmapped.

MODAL

This keyword applies to widgets created with the WIDGET_BASE function and the MODAL keyword.

If this keyword is set, WIDGET_INFO will return True (1) if the base widget specified by Widget_ID is a modal base widget, or False (0) otherwise.

MULTIPLE_PROPERTIES

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the property sheet's current selection mode. A value of 1 indicates support for multiple property selection. A value of 0 indicates that only single property selection is permitted.

NAME

This keyword applies to all widgets.

Set this keyword to return the widget type name of the widget specified by Widget_ID. The returned value will be one of the following strings: "BASE", "BUTTON", "COMBOBOX", "DRAW", "DROPLIST", "LABEL", "LIST", "PROPERTYSHEET", "SLIDER", "TAB", "TABLE", "TEXT", or "TREE". Set the TYPE keyword to return the widget's type code.

PARENT

This keyword applies to all widgets.

Set this keyword to return the widget ID of the parent of the widget specified by Widget_ID. If the widget is a top-level base (i.e., it has no parent), 0 is returned.

PROPERTY_VALID

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to a scalar string or one-element string array that contains a property identifier. If the specified property is included in the property sheet, WIDGET_INFO will return 1; if the property is not included in the property sheet, WIDGET_INFO will return 0. Comparisons are case-insensitive.

Note

Property identifiers returned in the IDENTIFIER field of an event structure generated by a property sheet widget can be assumed to be valid.

PROPERTY_VALUE

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to a string that contains a property identifier. If the specified property is included in the property sheet, WIDGET_INFO will return the value of the property. If the specified property is not included in the property sheet, WIDGET_INFO will generate an error; use the PROPERTY_VALID keyword to WIDGET_INFO to check for validity before retrieving the property value. Comparisons are case-insensitive.

If the property sheet contains multiple components, use the COMPONENT keyword to indicate which component the property value should be retrieved from.

Note on use of this keyword

When a user changes a value in the property sheet widget, the actual value of the underlying property does not change automatically. Use this keyword to retrieve the value specified by the user, then apply the new value to the underlying component. The following code snippet illustrates this process:

PRO prop_event, e 
 
; Get the value of the changed property, using the component and 
; property identifier information contained in the widget event. 
value = widget_info( e.id, component = e.component, $ 
   property_value = e.identifier ) 
 
; Set the component's property's value 
e.component->SetPropertyByIdentifier, e.identifier, value 
 
END

PROPERTYSHEET_NSELECTED

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the number of currently selected properties. The COMPONENT keyword is not required.

PROPERTYSHEET_SELECTED

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to return the identifiers of the currently selected properties. The return value depends on the number of rows selected as follows:


Selection	Return Value
No Properties Selected	Returns an empty string (' ').
Single Property Selected	Returns a string containing the property identifier.
Multiple Properties Selected	Returns an array of strings containing each selected property's identifier.

The COMPONENT keyword is not required.

PUSHBUTTON_EVENTS

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to return the pushbutton events status for the widget specified by Widget_ID. WIDGET_INFO returns 1 if pushbutton events are currently enabled for the widget, or 0 otherwise.

REALIZED

This keyword applies to all widgets.

Set this keyword to return 1 if the widget specified by Widget_ID has been realized. If the widget has not been realized, 0 is returned.

ROW_HEIGHTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Note

This keyword is not supported under Microsoft Windows.

Set this keyword to return an array of long integers giving the height of each row in the table. If USE_TABLE_SELECT is set equal to one, only the row heights for rows that contain currently-selected cells are returned. If USE_TABLE_SELECT is set equal to an array, only the row heights for rows that contain specified cells are returned.

SENSITIVE

This keyword applies to all widgets.

Set this keyword to return True (1) if the widget specified by Widget_ID is sensitive (enabled), or False (0) otherwise. Note that when a base is made insensitive, all its children are made insensitive. If WIDGET_INFO reports that a particular widget is insensitive, it may be because a parent in the widget hierarchy has been made insensitive.

SIBLING

This keyword applies to all widgets.

Set this keyword to return the widget ID of the first sibling of the widget specified by Widget_ID. If the widget is the last sibling in the chain, 0 is returned.

SLIDER_MIN_MAX

This keyword applies to widgets created with the WIDGET_SLIDER function.

Set this keyword to return the current minimum and maximum values of the specified slider as a two-element integer array. Element 0 is the minimum value and element 1 is the maximum value.

SYSTEM_COLORS

This keyword applies to all widgets.

Set this keyword and supply the widget ID of any widget to cause WIDGET_INFO to return an IDL structure that contains RGB values used for 25 IDL display elements.

For more detailed information on the WIDGET_SYSTEM_COLORS structure fields and their meaning see the The WIDGET_SYSTEM_COLORS Structure.

TAB_CURRENT

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the zero-based index of the current tab in the tab widget.

TAB_MODE

This keyword applies to all widgets.

Set this keyword to return what support the specified widget has for navigating among widgets using the Tab key. Possible return values are:


Value	Description
0	Navigation is not supported onto or off of the widget.
1	Navigation is supported onto and off of the widget.
2	Navigation is supported only onto the widget.
3	Navigation is supported only off of the widget.

Note

In widget applications on the UNIX platform, the Motif library controls what widgets are brought into and released from focus using tabbing. The TAB_MODE keyword value is always zero and any attempt to change it is ignored when running a widget application on the UNIX platform.

TAB_MULTILINE

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the current setting of the multi-line mode for the tab widget.

TAB_NUMBER

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword to return the number of tabs contained in the tab widget.

TABLE_ALL_EVENTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return 1 (one) if Widget_ID is a table widget with the ALL_EVENTS attribute set. Otherwise, 0 (zero) is returned.

TABLE_DISJOINT_SELECTION

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return 1 (one) if the widget specified by Widget_ID has disjoint selection enabled. Otherwise, 0 (zero) is returned.

TABLE_EDITABLE

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return 1 (one) if Widget_ID is a table widget that allows user editing of its contents. Otherwise, 0 (zero) is returned.

TABLE_EDIT_CELL

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return a two-element integer array containing the row and column coordinates of the currently editable cell. If none of the cells in the table widget is currently editable, the array [-1, -1] is returned.

TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return the currently-selected (highlighted) cells in the specified table widget.

In standard selection mode, this keyword returns an array of the form [ left, top, right, bottom ] containing the zero-based indices of the columns and rows that define the selection.

In disjoint selection mode (enabled by setting the DISJOINT_SELECTION keyword to WIDGET_TABLE), this keyword returns a 2 x n array of column/row pairs containing the zero-based indices the selected cells.

TABLE_VIEW

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to return a two-element array of the form [left, top] containing the zero-based offsets of the top-left cell currently visible in the specified table widget.

TEXT_ALL_EVENTS

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return 1 if Widget_ID is a text widget with the ALL_EVENTS attribute set. Otherwise, 0 is returned.

TEXT_EDITABLE

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return 1 if Widget_ID is a text widget that allows user editing of its contents. Otherwise, 0 is returned.

TEXT_NUMBER

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return the number of characters currently contained in the specified text widget, including end-of-line characters.

Note

On Windows platforms, Carriage Return/Line Feed pairs count as a single character.

TEXT_OFFSET_TO_XY

This keyword applies to widgets created with the WIDGET_TEXT function.

Use this keyword to translate a text widget character offset into column and line form. The value of this keyword should be set to the character offset (an integer) to be translated. WIDGET_INFO returns a two-element integer array giving the column (element 0) and line (element 1) corresponding to the offset. If the offset specified is out of range, the array [-1,-1] is returned.

TEXT_SELECT

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return the starting character offset and length (in characters) of the selected (highlighted) text in the specified text widget. WIDGET_INFO returns a two-element integer array containing the starting position of the highlighted text as an offset from character zero of the text in the widget (element 0), and length of the current selection (element 1).

TEXT_TOP_LINE

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to return the zero-based line number of the line currently at the top of a text widget's display viewport. Note that this value is different from the zero-based character offset of the characters in the line. The character offset can be calculated from the line offset via the TEXT_XY_TO_OFFSET keyword.

TEXT_XY_TO_OFFSET

This keyword applies to widgets created with the WIDGET_TEXT function.

Use this keyword to translate a text widget position given in line and column form into a character offset. The value of this keyword should be set to a two-element integer array specifying the column (element 0) and line (element 1) position. WIDGET_INFO returns the character offset (as a longword integer) corresponding to the position. If the position specified is out of range, -1 is returned.

TLB_ICONIFY_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return iconify events. Otherwise, 0 is returned.

TLB_KILL_REQUEST_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return kill request events. Otherwise, 0 is returned.

TLB_MOVE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return move events. Otherwise, 0 is returned.

TLB_SIZE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to return 1 if the top-level base widget specified by Widget_ID is set to return resize events. Otherwise, 0 is returned.

TOOLTIP

This keyword applies to widgets created with the WIDGET_BUTTON and WIDGET_DRAW functions.

Set this keyword to have the WIDGET_INFO function return the text of the tooltip of the widget. If the widget does not have a tooltip, a null string will be returned.

TRACKING_EVENTS

This keyword applies to all widgets.

Set this keyword to return the tracking events status for the widget specified by Widget_ID. WIDGET_INFO returns 1 if tracking events are currently enabled for the widget. Otherwise, 0 is returned.

TREE_EXPANDED

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return 1 (one) if the specified tree widget node is a folder that is expanded, or 0 (zero) if the specified node is a folder that is collapsed.

Note

Only tree widget nodes created with the FOLDER keyword can be expanded or collapsed. This keyword will always return 0 (zero) if the specified tree widget node is not a folder.

TREE_ROOT

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return the widget ID of the root node of the tree widget hierarchy of which Widget ID is a part. The root node is the tree widget whose parent is a base widget.

TREE_SELECT

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword to return information about the nodes selected in the specified tree widget. This keyword has two modes of operation, depending on the widget ID passed to WIDGET_INFO:

If the specified widget ID is for the root node of the tree widget (the tree widget whose Parent is a base widget), this keyword returns either the widget ID of the selected node or (if multiple nodes are selected) an array of widget IDs of the selected nodes. If no nodes are selected, -1 is returned.

If the specified widget ID is a tree widget that is a node in a tree, this keyword returns 1 (one) if the node is selected or 0 (zero) if it is not selected.

TYPE

This keyword applies to all widgets.

Set this keyword to return the type code of the specified Widget_ID. Possible values are given the following table. Note that you can set the NAME keyword to return string names instead.


Value	Type
0	Base
1	Button
2	Slider
3	Text
4	Draw
5	Label
6	List
8	Droplist
9	Table
10	Tab
11	Tree
12	Combobox

UNAME

This keyword applies to all widgets.

Set this keyword to have the WIDGET_INFO function return the user name of the widget.

UNITS

This keyword applies to all widgets.

Use this keyword to specify the unit of measurement used when returning dimensions for most widget types. Set UNITS equal to 0 (zero) to specify that all measurements are in pixels (this 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.

Note

This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when retrieving the XSIZE or YSIZE of a WIDGET_LIST, WIDGET_TABLE, or WIDGET_TEXT functions.

UPDATE

This keyword applies to all widgets.

Set this keyword to return 1 if the widget hierarchy that contains Widget_ID is set to display updates. Otherwise, 0 is returned. See UPDATE.

USE_TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to modify the behavior of the COLUMN_WIDTHS and ROW_HEIGHTS keywords. If USE_TABLE_SELECT is set, the COLUMN_WIDTHS and ROW_HEIGHTS keywords only apply to the currently-selected cells. Normally, these keywords apply to the entire contents of a table widget.

The USE_TABLE_SELECT keyword can also be specified as a four-element array, of the form [left, top, right, bottom], giving the group of cells to act on. In this usage, the value -1 is used to refer to the row or column titles.

VALID_ID

This keyword applies to all widgets.

Set this keyword to return 1 if Widget_ID represents a currently-valid widget. Otherwise, 0 is returned.

VERSION

This keyword applies to all widgets.

Set this keyword to return a structure that gives information about the widget implementation. This structure has the following definition:

{ WIDGET_VERSION, STYLE:'', TOOLKIT:'', RELEASE:'' }

STYLE is the style of widget toolkit used. TOOLKIT is the implementation of the toolkit. RELEASE is the version level of the toolkit. This field can be used to distinguish between different releases of a given toolkit, such as Motif 1.0 and Motif 1.1.

VISIBLE

This keyword applies to all widgets.

Set this keyword to return True (1) if the widget specified by Widget_ID is visible, or False (0) otherwise. A widget is visible if:

it has been realized,

it and all of its ancestors are mapped.

Note

The value returned by WIDGET_INFO when this keyword is set is not affected if the widget is minimized or obscured by another window. Widgets that are visible in the sense of this keyword may not be immediately apparent to a person viewing a particular display device.

The WIDGET_SYSTEM_COLORS Structure

When the SYSTEM_COLORS keyword is specified in a call to WIDGET_INFO, IDL returns a WIDGET_SYSTEM_COLORS structure. This allows application developers to determine what colors are used in IDL application widgets, so they can design widgets for their application with the same look and feel as the supplied IDL widgets.

The WIDGET_SYSTEM_COLORS structure consists of 25 fields, each containing a three-element vector corresponding to the Red, Green, and Blue color values used for various widget elements. The vector elements are integers ranging between 0 and 255 if a color value is available (vector elements contain -1 if the color value is unavailable). The field names and meaning on the Windows and UNIX operating systems are shown in the following table.


Field Names	Windows Platform	UNIX Platform
DARK_SHADOW_3D	Dark shadow color for 3D display elements.	N/A
FACE_3D	Face color for 3D display elements and dialog boxes.	Base background color for all widgets.
LIGHT_EDGE_3D	Highlight color for 3D edges that face the light source.	Color of top and left edges of 3D widgets.
LIGHT_3D	Light color for 3D display elements.	Color of highlight rectangle around widgets with the keyboard focus.
SHADOW_3D	Color for 3D edges that face away from the light source.	Color of bottom and right edges of 3D widgets.
ACTIVE_BORDER	Active window's border color.	Push button background color when button is armed.
ACTIVE_CAPTION	Active window's caption color.	N/A
APP_WORKSPACE	Background color of MDI applications.	N/A
DESKTOP	Desktop color.	N/A
BUTTON_TEXT	Text color on push buttons.	Widget text color.
CAPTION_TEXT	Color of text in caption, size box, and scroll bar arrow box.	Widget text color.
GRAY_TEXT	Color of disabled text.	N/A
HIGHLIGHT	Color of item(s) selected in a widget.	Toggle button fill color.
HIGHLIGHT_TEXT	Color of text of item(s) selected in a widget.	N/A
INACTIVE_BORDER	Inactive window's border color.	N/A
INACTIVE_CAPTION	Inactive window's caption color.	N/A
INACTIVE_CAPTION_TEXT	Inactive window's caption text color.	N/A
TOOLTIP_BK	Background color for tooltip controls.	N/A
TOOLTIP_TEXT	Text color for tooltip controls.	N/A
MENU	Menu background color.	N/A
MENU_TEXT	Menu text color.	N/A
SCROLLBAR	Color of scroll bar "gray" area.	Color of scroll bar "gray" area.
WINDOW_BK	Window background color.	Base background color for all widgets.
WINDOW_FRAME	Window frame color.	Widget border color.
WINDOW_TEXT	Text color in windows.	Widget text color.

Version History

Introduced: Pre 4.0

BUTTON_SET, COMBOBOX_GETTEXT, COMBOBOX_NUMBER, FONTNAME, MAP, SENSITIVE, TAB_CURRENT, TAB_MULTILINE, TAB_NUMBER, TABLE_DISJOINT_SELECTION, TLB_ICONIFY_EVENTS, TLB_MOVE_EVENTS, TLB_SIZE_EVENTS, TOOLTIP, TREE_EXPANDED, TREE_ROOT, TREE_SELECT, and VISIBLE keywords added: 5.6

COMPONENT, PROPERTY_VALID, PROPERTY_VALUE, and PUSHBUTTON_EVENTS keywords added: 6.0

MULTIPLE_PROPERTIES, PROPERTYSHEET_NSELECTED, PROPERTYSHEET_SELECTED, TAB_MODE keywords added: 6.1