The WIDGET_CONTROL procedure is used to realize, manage, and destroy widget hierarchies. It is often used to change the default behavior or appearance of previously-realized widgets.

Syntax

---

WIDGET_CONTROL [, Widget_ID]

Keywords that apply to all widgets: [, BAD_ID=variable] [, /CLEAR_EVENTS] [, DEFAULT_FONT=string{do not specify Widget_ID}] [, /DELAY_DESTROY{do not specify Widget_ID}] [, /DESTROY] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, FUNC_GET_VALUE=string] [, GET_UVALUE=variable] [, GROUP_LEADER=widget_id] [, /HOURGLASS{do not specify Widget_ID}] [, KILL_NOTIFY=string] [, /MAP] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, /REALIZE] [, /REDRAW] [, /RESET{do not specify Widget_ID}] [, SCR_XSIZE=width] [, SCR_YSIZE=height] [, SEND_EVENT=structure] [, /SENSITIVE] [, SET_UNAME=string] [, SET_UVALUE=value] [, /SHOW] [, TIMER=value] [, TLB_GET_OFFSET=variable] [, TLB_GET_SIZE=variable] [, /TLB_KILL_REQUEST_EVENTS] [, TLB_SET_TITLE=string] [, TLB_SET_XOFFSET=value] [, TLB_SET_YOFFSET=value] [, /TRACKING_EVENTS] [, UNITS={0 | 1 | 2}] [, /UPDATE] [, XOFFSET=value] [, XSIZE=value] [, YOFFSET=value] [, YSIZE=value]

Keywords that apply to WIDGET_BASE: [, BASE_SET_TITLE=string] [, /CONTEXT_EVENTS] [, /ICONIFY] [, /KBRD_FOCUS_EVENTS] [, TAB_MODE=value] [, /TLB_ICONIFY_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] [, /TLB_MOVE_EVENTS] [, /TLB_SIZE_EVENTS]

Keywords that apply to WIDGET_BROWSER: [, /BROWSER_CANCEL_ALL_DOWNLOADS] [, /BROWSER_CANCEL_DOWNLOAD] [, /BROWSER_CANCEL_PAGE] [, /BROWSER_GO_BACK] [, /BROWSER_GO_FORWARD] [, BROWSER_NOTIFY=value] [, /BROWSER_RELOAD]

Keywords that apply to WIDGET_BUTTON: [, /BITMAP] [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, IMAGE=byte array] [, /INPUT_FOCUS] [, /PUSHBUTTON_EVENTS] [, /SET_BUTTON] [, /SET_MASK] [, SET_VALUE=value] [, TAB_MODE=value] [, TOOLTIP=string] [, X_BITMAP_EXTRA=bits]

Keywords that apply to WIDGET_COMBOBOX: [, COMBOBOX_ADDITEM=string] [, COMBOBOX_DELETEITEM=integer] [, COMBOBOX_INDEX=integer] [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, IGNORE_ACCELERATORS={string array | {0 | 1}}] [, SET_COMBOBOX_SELECT=integer] [/SET_LIST_EVENTS][, SET_VALUE=value] [, TAB_MODE=value]

Keywords that apply to WIDGET_DRAW and WIDGET_WINDOW: [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, DRAW_KEYBOARD_EVENTS={0 | 1 | 2}] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] [, /DRAW_WHEEL_EVENTS] [, DRAW_XSIZE=integer] [, DRAW_YSIZE=integer] [, GET_DRAW_VIEW=variable] [, GET_UVALUE=variable] [, GET_VALUE=variable] [, IGNORE_ACCELERATORS={string array | {0 | 1}}] [, /INPUT_FOCUS] [, SET_DRAG_NOTIFY=string] [, SET_DRAW_VIEW=[x, y]] [, /SET_DROP_EVENTS] [, TOOLTIP=string]

Keywords that apply to WIDGET_DROPLIST: [, /DYNAMIC_RESIZE] [, GET_VALUE=variable] [, SET_DROPLIST_SELECT=integer] [, SET_VALUE=value] [, TAB_MODE=value]

Keywords that apply to WIDGET_LABEL: [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, SET_VALUE=value]

Keywords that apply to WIDGET_LIST: [, /CONTEXT_EVENTS] [, SET_LIST_SELECT=value] [, SET_LIST_TOP=integer] [, SET_VALUE=value] [, TAB_MODE=value]

Keywords that apply to WIDGET_PROPERTYSHEET: [, /CONTEXT_EVENTS] [, /EDITABLE] [, GET_VALUE=variable] [, /HIDE_ADVANCED_ONLY] [, IGNORE_ACCELERATORS={string array | {0 | 1}}] [, /MULTIPLE_PROPERTIES] [, PROPERTYSHEET_SETSELECTED=empty string, string, or array of strings] [, REFRESH_PROPERTY=string, array of strings, or integer] [, SET_VALUE=value]

Keywords that apply to WIDGET_SLIDER: [, GET_VALUE=value] [, SET_SLIDER_MAX=value] [, SET_SLIDER_MIN=value] [, SET_VALUE=value][, TAB_MODE=value]

Keywords that apply to WIDGET_TAB: [, SET_TAB_CURRENT=index] [, SET_TAB_MULTILINE=value] [, TAB_MODE=value]

Keywords that apply to WIDGET_TABLE: [, ALIGNMENT={0 | 1 | 2}] [, /ALL_TABLE_EVENTS] [, AM_PM=[string, string]] [, BACKGROUND_COLOR=array] [, COLUMN_LABELS=string array] [, COLUMN_WIDTHS=array] [, /CONTEXT_EVENTS] [, DAYS_OF_WEEK=string_array{7 names}] [, /DELETE_COLUMNS{not for row_major mode}] [, /DELETE_ROWS{not for column_major mode}] [, /EDITABLE] [, EDIT_CELL=[integer, integer]] [, FONT=string array] [, FOREGROUND_COLOR=array] [, FORMAT=value] [, GET_VALUE=variable] [, IGNORE_ACCELERATORS={string array | {0 | 1}}] [, INSERT_COLUMNS=value] [, INSERT_ROWS=value] [, /KBRD_FOCUS_EVENTS] [, MONTHS=string_array{12 names}] [, ROW_LABELS=string array] [, ROW_HEIGHTS=array] [, SET_TABLE_SELECT=[left, top, right, bottom]] [, SET_TABLE_VIEW=[integer, integer]] [, SET_TEXT_SELECT=[integer, integer]] [, SET_VALUE=value] [, TAB_MODE=value] [, TABLE_BLANK=cells] [, /TABLE_DISJOINT_SELECTION] [, TABLE_XSIZE=columns] [, TABLE_YSIZE=rows] [, /USE_TABLE_SELECT | , USE_TABLE_SELECT=[left, top, right, bottom]] [, /USE_TEXT_SELECT]

Keywords that apply to WIDGET_TEXT: [, /ALL_TEXT_EVENTS] [, /APPEND] [, /CONTEXT_EVENTS] [, /EDITABLE] [, GET_VALUE=variable] [, IGNORE_ACCELERATORS={string array | {0 | 1}}] [, /INPUT_FOCUS] [, /KBRD_FOCUS_EVENTS] [, /NO_NEWLINE] [, SET_TEXT_SELECT=[integer, integer]] [, SET_TEXT_TOP_LINE=line_number] [, SET_VALUE=value] [, TAB_MODE=value] [, /USE_TEXT_SELECT]

Keywords that apply to WIDGET_TREE: [, /CONTEXT_EVENTS] [, GET_VALUE=variable] [, SET_DRAG_NOTIFY=string] [, /SET_DRAGGABLE] [, /SET_DROP_EVENTS] [, /SET_MASK] [, SET_TREE_BITMAP=array] [, SET_TREE_CHECKED=value] [, /SET_TREE_EXPANDED] [, SET_TREE_INDEX=value] [, SET_TREE_SELECT={0 | 1 | widget ID | array of widget IDs}] [, /SET_TREE_VISIBLE] [, SET_VALUE=value] [, TAB_MODE=value] [, TOOLTIP =string]

Arguments

---

Widget_ID

The widget ID of the widget to be manipulated. This argument is required by all operations, unless the description of the specific keyword states otherwise. Note that if Widget_ID is not provided for a keyword that needs it, that keyword is quietly ignored.

Keywords

---

Not all keywords to WIDGET_CONTROL 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.

ALIGNMENT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a scalar, 2-D array, or 1-D array specifying the alignment of the contents of each cell. An alignment of 0 (the default) aligns the left edge of the text with the left edge of the cell. An alignment of 2 right-justifies the text, while 1 results in text centered within the cell.

If the USE_TABLE_SELECT keyword is not set:

• If ALIGNMENT is set equal to a scalar, all table cells are aligned as specified. If ALIGNMENT is set equal to a 2-D array, the alignment of each table cell is governed by the corresponding element of the array.

If the USE_TABLE_SELECT keyword is set:

• In standard selection mode, if ALIGNMENT is set equal to a scalar, all cells in the selection are aligned as specified. If ALIGNMENT is set equal to a 2-D array, the alignment of each selected cell is governed by the corresponding element of the array.
• In disjoint selection mode, if ALIGNMENT is set equal to a scalar, all cells in the selection are aligned as specified. If ALIGNMENT is set equal to a 1-D array, the alignment of each selected cell is governed by the corresponding element of the array.

ALL_TABLE_EVENTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to cause the table widget to generate events whenever the user changes the contents of a table cell.

Note: If the EDITABLE keyword is set, an insert character event (TYPE=0) is generated when the user presses the Return or Enter key in the table widget, even if the ALL_TABLE_EVENTS keyword is not set. End-of-line events such as these could be used by the programmer as an indication to check the cell value or to set the currently selected cell to the next cell. See the table below for details on the interaction between ALL_TABLE_EVENTS and EDITABLE.

Keywords		Effects
ALL_TABLE_EVENTS	EDITABLE	Input changes widget contents?	Type of events generated
Not set	Not set	No	None
Not set	Set	Yes	End-of-line insertion
Set	Not set	No	All events
Set	Set	Yes	All events

ALL_TEXT_EVENTS

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to cause the text widget to generate events whenever the user changes the contents of the text area.

Note: If the EDITABLE keyword is set, an insert character event (TYPE=0) is generated when the user presses the Return or Enter key in the text widget, even if the ALL_EVENTS keyword is not set. See the table below for details on the interaction between ALL_TEXT_EVENTS and EDITABLE.

Keywords		Effects
ALL_TEXT_EVENTS	EDITABLE	Input changes widget contents?	Type of events generated
Not set	Not set	No	None
Not set	Set	Yes	End-of-line insertion
Set	Not set	No	All events
Set	Set	Yes	All events

AM_PM

This keyword applies to widgets created with the WIDGET_TABLE function.

Supplies a string array of two names to be used for the names of the AM and PM string when processing explicitly formatted dates (CAPA, CApA, and CapA format codes) with the FORMAT keyword.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

APPEND

This keyword applies to widgets created with the WIDGET_TEXT function.

When using the SET_VALUE keyword to set the contents of a text widget (as created with the WIDGET_TEXT procedure), setting this keyword indicates that the supplied text should be appended to the existing contents of the text widget rather than replace it.

BACKGROUND_COLOR

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to one or more RGB triplets to specify cell background colors. For an RGB triplet, each red, green, and blue byte must be in the range [0,255].

Note: A computer’s graphics system might not express an arbitrary RGB triplet accurately or be capable of displaying a large number of distinct colors. The actually applied may be different from the color you specify.

When you use this keyword in conjunction with USE_TABLE_SELECT, you can specify the set of affected cells. Otherwise, IDL operates on all of the table’s cells. If a single color is provided, it is applied to all cells and is used as the default whenever new cells are created. If more than one color is provided, IDL applies the colors row by row, left to right, working from the top row to the bottom row. When there are fewer colors than cells, IDL cycles through the colors repeatedly.

For more information, see Table Widget Cell Attributes.

BAD_ID

This keyword applies to all widgets.

If Widget_ID is not a valid widget identifier, this WIDGET_CONTROL normally issues an error and causes program execution to stop. However, if BAD_ID is present and specifies a named variable, the invalid ID is stored into the variable, and this routine quietly returns. If no error occurs, a zero is stored.

BASE_SET_TITLE

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to a scalar string to change the title of the specified base widget. If the parent of the base widget is a tab widget, the title of the corresponding tab in the tab widget is changed to the provided string. If the parent is not a tab control, this keyword behaves like the keyword TLB_SET_TITLE.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

BITMAP

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to specify that the SET_VALUE keyword specifies the name of a .bmp file.

The value of a widget button can be a bitmap as described in Bitmap Buttons and Labels. If you specify the name of a bitmap file with the VALUE keyword, you must also set the BITMAP keyword.

BROWSER_CANCEL_ALL_DOWNLOADS

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to cancel the downloading of all current downloads

BROWSER_CANCEL_DOWNLOAD

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to a download ID to cancel the downloading of that specific download.

BROWSER_CANCEL_PAGE

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to cancel any active loading of frames by the browser.

BROWSER_GO_BACK

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to navigate the browser to the prior page. If there is no prior page then nothing happens. You can use the BROWSER_CAN_GO_BACK keyword to WIDGET_INFO to determine if there is a prior page.

BROWSER_GO_FORWARD

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to navigate the browser to the "next" page. If there is no next page then nothing happens. You can use the BROWSER_CAN_GO_FORWARD keyword to WIDGET_INFO to determine if there is a "next" page.

BROWSER_NOTIFY

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to a scalar string to send to the browser's JavaScript IDLNotify handler.

BROWSER_RELOAD

This keyword applies to widgets created with the WIDGET_BROWSER function.

Set this keyword to force the browser to reload the current page.

CLEAR_EVENTS

This keyword applies to all widgets.

If set, any events generated by the widget hierarchy rooted at Widget_ID which have arrived but have not been processed (via the WIDGET_EVENT procedure) are discarded.

COLUMN_LABELS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to an array of strings to be used as labels for the columns of the table. If no label is specified for a column, it receives the default label “n” where n is the column number. If this keyword is set to the empty string (''), all column labels are set to be empty.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

COLUMN_WIDTHS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a one-dimensional array of widths for the columns of the table widget. The widths are given in the units specified with the UNITS keyword. If no width is specified for a column, that column is set to the default size, which varies by platform. If COLUMN_WIDTHS is set to a scalar value, all of the column widths are set to that value.

Note: Column widths are limited to 0.

If the USE_TABLE_SELECT keyword is set (in either standard or disjoint selection mode), the indices of the elements of an array specified as the value of the COLUMN_WIDTHS keyword are interpreted as indices into the list of selected columns. For example, if the table is in disjoint selection mode, the current selection includes cells from columns 0, 1, 2, 5, 6, and 7, USE_TABLE_SELECT is set equal to one, and the COLUMN_WIDTHS keyword is set equal to a four-element array [20, 35, 30, 35], the widths of columns 0, 1, 2, and 5 would be modified. Similarly, if the table is in standard selection mode and the USE_TABLE_SELECT keyword is set equal to the array [0, 1, 0, 0], and the COLUMN_WIDTHS keyword is set equal to a four-element array [20, 35, 30, 35], only the width of the first column would be altered.

COMBOBOX_ADDITEM

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to a non-empty string that specifies a new item to add to the list of the combobox. By default, the item will be added to the end of the list. The item can be added to a specified position in the list by setting the COMBOBOX_INDEX keyword in the same call to WIDGET_CONTROL.

COMBOBOX_DELETEITEM

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to an integer that specifies the zero-based index of the combobox element to be deleted from the list. If the specified element is outside the range of existing elements, no element is deleted.

COMBOBOX_INDEX

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to an integer that specifies the zero-based index of the position at which a new item will be added to the list when using the COMBOBOX_ADDITEM keyword. The value -1 is a special case that indicates the item should be added to the end of the list. Note that this special case is provided for convenience, and that an item can also be added to the end of the list by omitting the COMBOBOX_INDEX keyword entirely. If the supplied index is not -1, and is outside the range of zero to the length of the existing list, the item is not added to the list.

Note: You can retrieve the length of the existing list using the COMBOBOX_NUMBER keyword to WIDGET_INFO function.

CONTEXT_EVENTS

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

Set this keyword to cause context menu events (or 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 procedure within your widget program’s event handler to display the context menu.

Note: You can also capture right mouse button events generated within draw widgets. See the BUTTON_EVENTS keyword to the WIDGET_DRAW and WIDGET_WINDOW functions for details.

For more on detecting and handling context menu events, see Context-Sensitive Menus.

DAYS_OF_WEEK

This keyword applies to widgets created with the WIDGET_TABLE function.

Supplies a string array of 7 names to be used for the names of the days of the week when processing explicitly formatted dates (CDWA, CDwA, and CdwA format codes) with the FORMAT keyword.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

DEFAULT_FONT

This keyword applies to all widgets that support fonts. Attempting to set a font on a widget that does not support fonts is not an error, but the attempt is ignored.

Note: The WIDGET_BASE, WIDGET_DRAW, WIDGET_TAB, WIDGET_TREE and WIDGET_WINDOW widgets do not support fonts.

Do not specify a Widget ID when using this keyword.

A string containing the name of the default font to be used.

If the font to be used for a given widget is not explicitly specified (via the FONT keyword to the widget creation function), a default supplied by the window system or server is used. Use this keyword to change the default. See Using Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.

Note: On Microsoft Windows platforms, IDL uses the system default font. Different versions of Windows use different system default fonts; in general, the system default font is the font appropriate for the version of Windows in question.

DELAY_DESTROY

This keyword applies to all widgets. Do not specify a Widget ID when using this keyword.

Normally, when the user destroys a widget hierarchy using the window manager, it is immediately removed. This can cause problems for applications that use the background task facility provided by the XMANAGER procedure if the hierarchy is destroyed while a background task is using it.

If DELAY_DESTROY is set, attempts to destroy the hierarchy are delayed until the next attempt to obtain an event for it. Setting DELAY_DESTROY to zero restores the default behavior.

XMANAGER uses this keyword automatically when managing background tasks. It is not expected that applications will need to use it directly.

DELETE_COLUMNS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to delete columns that contain selected cells. If a selection is specified via the USE_TABLE_SELECT keyword (in either standard or disjoint mode), the columns that contain cells specified in the selection array are deleted. If the USE_TABLE_SELECT keyword is either absent or set equal to 1, the columns that contain selected cells are deleted.

Note: You cannot delete columns from a table which displays structure data in /ROW_MAJOR mode (the default).

DELETE_ROWS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to delete rows that contain selected cells. If a selection is specified via the USE_TABLE_SELECT keyword (in either standard or disjoint mode), the rows that contain cells specified in the selection array are deleted. If the USE_TABLE_SELECT keyword is either absent or set equal to 1, the rows that contain selected cells are deleted.

Note: You cannot delete rows from a table which displays structure data in /COLUMN_MAJOR mode.

DESTROY

This keyword applies to all widgets.

Set this keyword to destroy the widget and any child widgets in its hierarchy. Any further attempts to use the IDs for these widgets will cause an error.

DRAW_BUTTON_EVENTS

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

Set this keyword to enable button press events for draw widgets. Setting a zero value disables such events.

Note: You can use button events generated by draw widgets to simulate the functionality of the CONTEXT_EVENTS keyword to WIDGET_BASE, WIDGET_LIST, and WIDGET_TEXT. See the BUTTON_EVENTS keyword to WIDGET_DRAW and WIDGET_WINDOW for details.

DRAW_EXPOSE_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to enable viewport expose events for draw widgets. Setting a zero value disables such events.

Note: You must explicitly disable backing store (by setting the RETAIN keyword to WIDGET_DRAW equal to zero) in order to generate expose events.

DRAW_KEYBOARD_EVENTS

This keyword applies to widgets created with WIDGET_DRAW.

Set this keyword equal to 1 (one) or 2 to make the draw widget generate an event when it has the keyboard focus and a key is pressed or released. (The method by which a widget receives the keyboard focus is dependent on the window manager in use.) The value of the key pressed is reported in either the CH or the KEY field of the event structure, depending on the type of key pressed. See Widget Events Returned by Draw Widgets for details.

• If this keyword is set equal to 1, the draw widget will generate an event when a “normal” key is pressed. “Normal” keys include all keys except function keys and the modifier keys: Shift, Control, Caps Lock, and Alt. If a modifier key is pressed at the same time as a normal key, the value of the modifier key is reported in the MODIFIERS field of the event structure.
• If this keyword is set equal to 2, the draw widget will generate an event when either a normal key or a modifier key is pressed. Values for modifier keys are reported in the KEY field of the event structure, and the MODIFIERS field contains zero.

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 enable motion events for draw widgets. Setting a zero value disables such events.

DRAW_VIEWPORT_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to enable viewport motion events for draw widgets. Setting a zero value disables such events.

DRAW_WHEEL_EVENTS

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to enable wheel events for draw widgets. Setting a zero value disables such events.

DRAW_XSIZE

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to an integer that specifies the new horizontal size for the graphics region (the virtual size) of a draw widget in units specified by the UNITS keyword (pixels are the default). For non-scrollable draw widgets, setting this keyword is the same as setting SCR_XSIZE or XSIZE. However, for scrolling draw widgets DRAW_XSIZE is the only way to change the width of the drawable area (XSIZE sets the viewport size).

DRAW_YSIZE

This keyword applies to widgets created with the WIDGET_DRAW function.

Set this keyword to an integer that specifies the new vertical size for the graphics region (the virtual size) of a draw widget in units specified by the UNITS keyword (pixels are the default). For non-scrollable draw widgets, setting this keyword is the same as setting SCR_YSIZE or YSIZE. However, for scrolling draw widgets DRAW_YSIZE is the only way to change the height of the drawable area (YSIZE sets the viewport size).

DYNAMIC_RESIZE

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

Set this keyword to activate (if set to 1) or deactivate (if set to 0) dynamic resizing of the specified WIDGET_BUTTON, WIDGET_LABEL, or WIDGET_DROPLIST widget (see the documentation for the DYNAMIC_RESIZE keyword to those procedures for more information about dynamic widget resizing).

EDITABLE

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET, WIDGET_TABLE, and WIDGET_TEXT functions.

Set this keyword to directly edit the contents of a property sheet, text, or table widget. For table widgets, you can control individual cell editability by restricting the targeted cells with USE_TABLE_SELECT. Additionally, when you supply an array of editability values, the values are distributed across the set of target cells. A scalar value is applied to all targeted cells.

For more information, see Table Widget Cell Attributes.

The default value depends on the type of widget as follows:

• Text and table widgets are read-only by default (the default value is 0). The text cannot be modified. See the descriptions of the ALL_TABLE_EVENTS and ALL_TEXT_EVENTS keywords for additional details.
• Property sheet widgets are editable by default (EDITABLE=1). In this default mode, property values can be modified. When a property sheet is marked as read-only (EDITABLE=0), you can select properties and use any scrollbars, but cannot change any values. Setting this keyword to 0 is roughly equivalent to desensitizing all properties by setting the SENSITIVE attribute of every property on the property sheet equal to 0.

Note: To set the SENSITIVE attribute of individual properties within a property sheet, use IDLitComponent::RegisterProperty or IDLitComponent::SetPropertyAttribute.

EDIT_CELL

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a two-element integer array containing the y (row) and x (column) coordinates of a table cell to put that cell into edit mode. For example, to put the top cell in the third column (x index=2) into edit mode, use the following commands:

row=0

col=2

WIDGET_CONTROL, table, EDIT_CELL=[row, col]

where table is the Widget ID of the table widget.

EVENT_FUNC

This keyword applies to all widget primitives (non-compound widgets).

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 given by Widget_ID.

This keyword overwrites any event routine supplied by previous uses of the EVENT_FUNC or EVENT_PRO keywords. To specify no event routine, set this keyword to an empty string ('').

EVENT_PRO

This keyword applies to all widget primitives (non-compound widgets).

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 given by Widget_ID.

This keyword overwrites any event routine supplied by previous uses of the EVENT_FUNC or EVENT_PRO keywords. To specify no event routine, set this keyword to an empty string ('').

FONT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to the names of the fonts used by the widget. Specified fonts are “device fonts” (an X Windows font on Motif systems, a TrueType or PostScript font on Windows systems). See Using Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.

You can restrict the set of targeted cells with USE_TABLE_SELECT. Another way to control individual cell fonts is to specify an array of font names. IDL distributes the supplied font names over the set of targeted cells, repeatedly if necessary (if there are fewer fonts than cells). If you provide a scalar string, IDL changes all targeted cells to the same font.

For more information, see Table Widget Cell Attributes.

FOREGROUND_COLOR

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to one or more RGB triplets to specify cell text colors. For an RGB triplet, each red, green, and blue byte must be in the range [0,255].

Note: A computer’s graphics system might not express an arbitrary RGB triplet accurately or be capable of displaying a large number of distinct colors. The actually applied may be different from the color you specify.

When you use this keyword in conjunction with USE_TABLE_SELECT, you can specify the set of affected cells. Otherwise, IDL operates on all of the table’s cells. If a single color is provided, it is applied to all cells and is used as the default whenever new cells are created. If more than one color is provided, IDL applies the colors row by row, left to right, working from the top row to the bottom row. When there are fewer colors than cells, IDL cycles through the colors repeatedly.

For more information, see Table Widget Cell Attributes.

FORMAT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a single string or a one- or two-dimensional array of strings that specify the format of data displayed within table cells. The string(s) are of the same form as used by the FORMAT keyword to the PRINT procedure, and the default format is the same as that used by the PRINT/PRINTF procedures.

If the USE_TABLE_SELECT keyword is set equal to one, the format is changed only for the currently selected cells. If USE_TABLE_SELECT is set equal to an array, the format is changed for the specified cells.

• In standard selection mode, FORMAT can be set either to a single string or to a two-dimensional array of strings of the same size as the selected area.
• In disjoint selection mode, FORMAT can be set either to a single string or to a one-dimensional array of strings with the same number of elements as the selected area.

FUNC_GET_VALUE

This keyword applies to all widgets.

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. The function specified by FUNC_GET_VALUE is called with the widget ID as an argument. The function specified by FUNC_GET_VALUE should return a value for a 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.

GET_DRAW_VIEW

This keyword applies to widgets created with the WIDGET_DRAW function.

Specifies a named variable which will be assigned the current position of a draw widget viewport. The position is returned as a 2-element integer array giving the X and Y position relative to the lower left corner of the graphics area.

GET_UVALUE

This keyword applies to all widgets.

Set this keyword to a named variable to contain the current user value of the widget.

Each widget can contain a user set value of any data type and organization. This value is not used by the widget in any way, and exists entirely for the convenience of the IDL programmer. This keyword allows you to obtain the current user value.

The user value of a widget can be set with the SET_UVALUE keyword to this routine, or with the UVALUE keyword to the routine that created it.

To improve the efficiency of the data transfer, consider using the NO_COPY keyword (described below) with GET_UVALUE.

GET_VALUE

This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_COMBOBOX, WIDGET_DRAW, WIDGET_DROPLIST, WIDGET_LABEL, WIDGET_PROPERTYSHEET, WIDGET_SLIDER, WIDGET_TABLE, WIDGET_TEXT, WIDGET_TREE and WIDGET_WINDOW functions.

Note: If you would like information about the values returned for a specific compound widget—beginning with the prefix “CW_”—please refer to the description of the compound widget, which may also include a section titled, “Keywords to WIDGET_CONTROL and WIDGET_INFO”.

Set this keyword to a named variable to contain the current value of the widget. The type of value returned depends on the widget type:

• Button: If the button label is text, it is returned as a string. Attempts to obtain the value of a button with a bitmap label is an error.
• Combobox: The contents of the list of the combobox widget are returned as a string or string array.
• Draw: The value of a draw widget depends on whether the draw widget uses IDL Direct Graphics or IDL Object Graphics. (The type of graphics used is specified by the GRAPHICS_LEVEL keyword to WIDGET_DRAW.) The two possibilities are:
1. By default, draw widgets use IDL Direct Graphics. In this case, the value of a draw widget is the IDL window ID for the drawing area. This ID is used with procedures such as WSET, WSHOW, etc., to direct graphics to the widget. The window ID is assigned to drawing area widgets at the time they are realized. If the widget has not yet been realized, a value of -1 is returned.

2. If the draw widget uses IDL Object Graphics (that is, if the GRAPHICS_LEVEL keyword to WIDGET_DRAW is set equal to 2), the value of the draw widget is the object reference of the window object used in the draw widget.

   To obtain the window number for a newly created draw widget, use GET_VALUE after the draw widget has been realized. Draw widgets do not have a window number assigned to them until they are realized. For example, to return the window number of a draw widget in the variable win_num, use the command:

   WIDGET_CONTROL, my_drawwidget, GET_VALUE=win_num

   where my_drawwidget is the widget ID of the desired draw widget.

   When using Object Graphics for the widget draw, the following command returns an object reference to the draw window:

   WIDGET_CONTROL, my_drawwidget, GET_VALUE=oWindow

   where oWindow is a window object.

• Droplist: The contents of the droplist widget’s list are returned as a string or string array.
• Label: The label text is returned as a string.
• Property Sheet: Retrieves the component object(s) that the property sheet is associated with. Use the GET_VALUE keyword to WIDGET_CONTROL.
• Slider: The current value of the slider is returned as an integer.
• Table: Normally, the data for the whole table are returned as a two dimensional array or a vector of structures.

If the USE_TABLE_SELECT keyword is set, the value returned is a subset of the whole data.

• If the table is in standard selection mode and the table data is of a single type, the value returned is a two dimensional array. If the table contains structure data, the value returned is a vector of (possibly anonymous) structures.
• If the table is in disjoint selection mode and the table data is a single type, the value returned is a one-dimensional array of values. If the table contains structure data, the value returned is a single structure in which each field corresponds to a selected cell. In either case, use the TABLE_SELECT keyword to WIDGET_INFO to get the row and column indices of the disjoint values.

If the USE_TEXT_SELECT keyword is set, the value returned is a string corresponding to the currently-selected text in the currently-selected cell.

• Text: The current contents of the text widget are returned as a string array. If the USE_TEXT_SELECT keyword is also specified, only the contents of the current selection are returned.
• Tree: The label text associated with the node is returned as a string. If the specified widget is the root of the tree then an empty string (““) is returned.
• Window: The value of WIDGET_WINDOW is the object reference of the WIDGET_WINDOW object. See the WIDGET_ WINDOW example.
• Widget types not listed above do not return a value. Attempting to retrieve the value of such a widget causes an error.

The value of a widget can be set with the SET_VALUE keyword to this routine, or with the VALUE keyword to the routine that created it.

GROUP_LEADER

This keyword applies to all widgets.

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. It is not possible to remove a widget from an existing group.

HIDE_ADVANCED_ONLY

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this keyword to 1 to only display simple properties (properties that do not have the ADVANCED_ONLY attribute set). The default behavior is to display all properties.

HOURGLASS

This keyword applies to all widgets. Do not specify a Widget ID when using this keyword.

Set this keyword to turn on an “hourglass-shaped” cursor for all IDL widgets and graphics windows. The hourglass remains in place until the WIDGET_EVENT function attempts to process the next event. Then the previous cursor is reinstated. If an application starts a time-intensive calculation inside an event-handling routine, the hourglass cursor should be used to indicate that the system is not currently responding to events.

ICONIFY

This keyword applies to all widgets.

Set this keyword to a non-zero value to cause the specified widget to become iconified. Set this keyword to zero to open an iconified widget.

IGNORE_ACCELERATORS

This keyword applies to widgets created with the WIDGET_COMBOBOX, WIDGET_DRAW, WIDGET_PROPERTYSHEET, WIDGET_TABLE, WIDGET_TEXT, and WIDGET_WINDOW functions.

Set this keyword to a list of accelerators that should be ignored while the target widget has the keyboard focus. Using this mechanism, keystrokes that IDL would otherwise deliver only to an accelerated button are allowed to fall through to the target widget. If the keyword is set while the widget already has the focus, the effects are immediate. Acceleration is restored when the target widget loses the focus.

Note: See WIDGET_BUTTON’s description of the ACCELERATOR keyword for the syntax used to specify accelerators.

If you do not set this keyword to a list, you can set it to one of the following values:

1	All existing accelerators are ignored
0	No accelerators are ignored

IMAGE

Note: This keyword is for menu buttons and works only on Windows platforms, version 7 and newer. IMAGE is ignored if it is used with the VALUE keyword when VALUE specifies an image.

Use this keyword to specify a three- or four-dimensional array representing the image to be displayed as a menu button. Images can be any size, and display to the left of the button text.

• RGB - set the IMAGE keyword equal to an n x m x 3 byte array that represents a 24-bit color image, interleaved by plane, with the planes in the order red, green, blue. The value of the lower-left pixel is automatically rendered as transparent. Any matching pixel value in the image renders as transparent, so design with this in mind.
• RGBA (Alpha channel) - set the IMAGE keyword equal to an n x m x 4 byte array that represents a 32-bit color image, interleaved by plane, with the planes in the order red, green, blue, alpha. This method creates a color bitmap button that allows various levels of the background to show through, depending on the opacity of each pixel.

INPUT_FOCUS

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

If Widget_ID is a text widget or a draw widget, set this keyword to cause the widget to receive the keyboard focus. If Widget_ID is a button widget, set this keyword to position the mouse pointer over the button (on Motif), or set the focus to the button so that it can be “pushed” with the spacebar (on Windows). While this keyword will set the focus to widgets of other types, the exact location of the focus is not well defined.

Note: You cannot assign the input focus to an unrealized widget.

INSERT_COLUMNS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to the number of columns to be added to the right of the rightmost column of the table. If the USE_TABLE_SELECT keyword is set equal to one, the columns are inserted to the left of the current selection. If USE_TABLE_SELECT is set equal to an array, the columns are inserted to the left of the specified selection.

Note: You cannot insert columns into a table which displays structure data in /ROW_MAJOR (default) mode because it would change the structure.

INSERT_ROWS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to the number of rows to be added below the bottommost row of the table. If the USE_TABLE_SELECT keyword is set equal to one, the rows are inserted above the current selection. If USE_TABLE_SELECT is set equal to an array, the rows are inserted above the specified selection.

Note: You cannot insert rows into a table which displays structure data in /COLUMN_MAJOR mode because it would change the structure.

KBRD_FOCUS_EVENTS

This keyword applies to widgets created with the WIDGET_BASE, WIDGET_TABLE, and WIDGET_TEXT functions.

Set this keyword to cause widget keyboard focus events to be issued for the widget whenever the keyboard focus of that widget changes. See the KBRD_FOCUS_EVENTS keywords to WIDGET_BASE, WIDGET_TABLE, and WIDGET_TEXT for details.

See Keyboard Focus Events for more information.

KILL_NOTIFY

This keyword applies to all widgets.

Use this keyword to change or remove a previously-specified callback procedure for Widget_ID. A previously-defined callback can be removed by setting this keyword to an empty string ('').

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.

• For a top-level base widget in a widget application, the CLEANUP keyword to XMANAGER can also be used to specify a procedure that will be called when the base widget dies. Note that the last call to any of:
• WIDGET_BASE, KILL_NOTIFY
• XMANAGER, CLEANUP
• WIDGET_CONTROL, KILL_NOTIFY

determines the procedure that is executed when the specified top-level base widget dies.

MANAGED

This keyword applies to all widgets.

This keyword is used by the XMANAGER procedure to mark those widgets that it is currently managing. User applications should not use this keyword directly.

MAP

This keyword applies to all widgets.

Set this keyword to zero to unmap the widget hierarchy rooted at the widget specified by Widget_ID. The hierarchy disappears from the screen, but still exists.

The mapping operation applies only to base widgets. If the specified widget is not a base, IDL searches upward in the widget hierarchy until it finds the closest base widget. The map operation is applied to that base.

Set MAP to a nonzero value to re-map the widget hierarchy and make it visible. Normally, the widget is automatically mapped when it is realized, so use of the MAP keyword is not required.

MONTHS

This keyword applies to widgets created with the WIDGET_TABLE function.

Supplies a string array of 12 names to be used for the names of the months when processing explicitly formatted dates (CMOA, CMoA, and CmoA format codes) with the FORMAT keyword.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

MULTIPLE_PROPERTIES

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

Set this property to 1 to allow multiple properties to be selected at the same time. When this keyword is set, you can hold down the Ctrl key while left-clicking with the mouse to make nonadjacent selections, or hold down the Shift key to select an adjacent range of properties.

When changing the selection support of a property sheet from multiple selection to single selection (MULTIPLE_PROPERTIES equals 0), the current set of selected properties is cleared unless there is only a single selection.

NO_COPY

This keyword applies to all widgets.

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 copy of the data being transferred. Although this technique is fine 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 the SET_UVALUE and GET_UVALUE operations differently. Rather than copy 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 the memory copying that would otherwise occur. However, it has the side effect of causing the source variable to become undefined. On a “set” operation (using the SET_UVALUE keyword to WIDGET_CONTROL), the variable passed as value becomes undefined. On a “get” operation (GET_UVALUE keyword to WIDGET_CONTROL), the user value of the widget in question becomes undefined.

Note: The NO_COPY keyword increases efficiency when sending event structures using the SEND_EVENT keyword to WIDGET_CONTROL.

NO_NEWLINE

This keyword applies to widgets created with the WIDGET_TEXT function.

When setting the value of a multi-line text widget, newline characters are automatically appended to the end of each line of text. The NO_NEWLINE keyword suppresses this action.

NOTIFY_REALIZE

This keyword applies to all widgets.

Set this keyword to a string that contains 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. A previously-set callback routine can be removed by setting this keyword to an empty string (''). The callback routine is called with the widget ID as its only argument.

PRO_SET_VALUE

This keyword applies to all widgets.

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.

The procedure specified by PRO_SET_VALUE is called with two arguments: a Widget ID and a Value. Using this technique allows you to designate a routine that sets the value for the widget specified by Widget ID.

This keyword is intended for use in compound widgets, which use it to define the compound widget’s value transparently to the user.

Using this keyword with widget primitives is somewhat problematic, because calling WIDGET_CONTROL, SET_VALUE within the procedure will also call the procedure specified by PRO_SET_VALUE. In order to use PRO_SET_VALUE with a widget primitive, the specified procedure must do the following:

1. Process the Value supplied to the procedure in the necessary way
2. Unset the PRO_SET_VALUE keyword for the affected widget by setting its value to an empty string
3. Set the affected widget’s value using the SET_VALUE keyword to WIDGET_CONTROL
4. Reset the PRO_SET_VALUE keyword to the original procedure

PROPERTYSHEET_SETSELECTED

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function.

This keyword allows programmatic property selection. Set it to a string or an array of strings to identify the properties to appear selected. The strings should match valid property identifiers. When this keyword is set to an empty string, or an array that contains only empty strings, it clears all property selections.

PUSHBUTTON_EVENTS

This keyword applies to widgets created with the WIDGET_BUTTON function.

Set this keyword to a non-zero value to enable pushbutton events for the widget specified by Widget_ID. Set the keyword to 0 to disable pushbutton events for the specified widget. For a description of pushbutton events, see PUSHBUTTON_EVENTS in the documentation for WIDGET_BUTTON.

REALIZE

This keyword applies to all widgets.

If set, the widget hierarchy is realized. Until the realization step, the widget hierarchy exists only within IDL. Realization is the step of actually creating the widgets on the screen (and mapping them if necessary).

When a previously realized widget gets a new child widget, the new child is automatically realized.

Tip: Under Microsoft Windows, when a hidden base is realized, then mapped, a Windows resize message is sent by the windowing system. This “extra” resize event is generated before any manipulation of the base widget by the user.

REDRAW

This keyword applies to all widgets.

Use this keyword to enable and disable redraws on a particular widget. A value of 0 (zero) disables drawing while a value of 1 enables drawing. On Windows, this keyword differs from the UPDATE keyword, because REDRAW affects only the widget and its children. In addition, whenever REDRAW is set to 1, the specified widget and its children are immediately redrawn. On Unix, using this keyword is equivalent to using the UPDATE keyword.

REFRESH_PROPERTY

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function. Set this keyword to:

• A non-zero numeric value to refresh all properties. Refreshing all properties in this manner is more efficient to use /REFRESH_PROPERTY than WIDGET_CONTROL’s SET_VALUE keyword to reload the property sheet.
• A string or string array containing one or more property identifiers identifying individual properties to be refreshed.

The REFRESH_PROPERTY keyword also updates a property's sensitivity and visibility according to the value of the property held by the related component. Although the property sheet knows about its component, the property sheet and underlying component have a clear boundary and can only affect each other through IDL statements. The following example illustrates this. The first selected property in the property sheet is hidden after a 4 second wait as long at the REFRESH_PROPERTY keyword is used. When commented out, there is no notification that the first selected property should be hidden.

PRO ExPropSheetRefresh

; Create and initialize the component.

oComp = OBJ_NEW('IDLitVisAxis')

; Create a base and property sheet.

base = WIDGET_BASE(/TLB_SIZE_EVENT, $

   TITLE = 'Single Property Sheet Example')

wPropAxis = WIDGET_PROPERTYSHEET(base, VALUE = oComp, $

UNAME = 'PropSheet', xsize = 45)

; Pre-select the color and transparency properties of

; axis component.

WIDGET_CONTROL, wPropAxis,  $

   PROPERTYSHEET_SETSELECTED=['Color', 'Transparency']

; Activate the widgets.

WIDGET_CONTROL, base, SET_UVALUE = oComp, /REALIZE

XMANAGER, 'ExSinglePropSheet', base, /NO_BLOCK

; Wait 4 seconds and then hide the first selected property 

; and refresh the property sheet. 

WAIT, 4

a = WIDGET_INFO(wPropAxis, /propertysheet_selected)

oComp->SetPropertyAttribute, a[0], /HIDE

WIDGET_CONTROL, wPropAxis, /REFRESH_PROPERTY

END

RESET

This keyword applies to all widgets. Do not specify a Widget ID when using this keyword. Set the RESET keyword to destroy every currently active widget. This keyword should be used with caution.

ROW_LABELS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to an array of strings to be used as labels for the rows of the table. If no label is specified for a row, it receives the default label “n” where n is the row number. If this keyword is set to the empty string (''), all row labels are set to be empty.

ROW_HEIGHTS

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a one-dimensional array of heights for the rows of the table widget. The heights are given in the units specified with the UNITS keyword. If no height is specified for a row, that row is set to the default size, which varies by platform. If ROW_HEIGHTS is set to a scalar value, all of the row heights are set to that value.

Note: On Microsoft Windows platforms, rows cannot have different heights. You should supply a scalar value, but if you supply an array of values, IDL applies the last value to all rows.

Note: Row heights are limited to 0 on Motif and 1 on Windows.

If the USE_TABLE_SELECT keyword is set (in either standard or disjoint selection mode), the indices of the elements of the specified array are interpreted as indices into the list of selected rows. For example, if the table is in disjoint selection mode, the current selection includes cells from rows 0, 1, 2, 5, 6, and 7, USE_TABLE_SELECT is set equal to one, and the ROW_HEIGHTS keyword is set equal to a four-element array [20, 35, 30, 35], the height of rows 0, 1, 2, and 5 would be modified. Similarly, if the table is in standard selection mode and the USE_TABLE_SELECT keyword is set equal to the array [0, 1, 0, 0], and the ROW_HEIGHTS keyword is set equal to a four-element array [20, 35, 30, 35], only the height of the first row would be altered.

Note: You can make column header cells taller by first selecting them with USE_TABLE_SELECT (using -1 for the row values of the selection indexes the header cells of the selection’s columns) and then setting their height with ROW_HEIGHTS.

SCR_XSIZE

This keyword applies to all widgets.

Set this keyword to an integer value that represents the widget’s new horizontal size, in units specified by the UNITS keyword (pixels are the default). Attempting to change the size of a widget that is part of a menubar or pulldown menu causes an error. This keyword is useful for resizing table, text, list, and scrolling widgets. Note that [XY]SIZE sets client area and SCR_[XY]SIZE sets total area (title bar, borders, menu, client area).

SCR_YSIZE

This keyword applies to all widgets.

Set this keyword to an integer value that represents the widget’s new vertical size, in units specified by the UNITS keyword (pixels are the default). Attempting to change the size of a widget that is part of a menubar or pulldown menu causes an error. This keyword is useful for resizing table, text, list, and scrolling widgets. Note that [XY]SIZE sets client area and SCR_[XY]SIZE sets total area (title bar, borders, menu, client area).

SEND_EVENT

This keyword applies to all widgets.

Set this keyword to a structure containing a valid widget event to be sent to the specified widget. The value of SEND_EVENT must be a structure and the first three fields must be ID, TOP, and HANDLER (all of LONG type). Additional fields can be of any type.

As a convenience, you can set the values of the ID, TOP, and HANDLER fields to the long integer zero. Setting these fields to zero will result in their being populated with the following values:

ID	the widget ID of the widget specified in the call to WIDGET_CONTROL.
TOP	the widget ID of the top-level base containing ID.
HANDLER	the widget ID of the widget associated with the event handling routine for ID.

To improve the efficiency of the data transfer, consider using the NO_COPY keyword with SEND_EVENT.

SENSITIVE

This keyword applies to all widgets.

Sensitivity can be used to control when a user is allowed to manipulate a widget. Set this keyword to control the sensitivity state of a widget after creation. Use the SENSITIVE keyword with the widget creation function to control the initial sensitivity state.

When a widget is sensitive, it has normal appearance and can receive user input. For instance, 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, and ignores any input directed at it. If SENSITIVE is zero, the widget hierarchy becomes insensitive. If nonzero, it becomes sensitive.

Note: Some widgets do not change their appearance when they are made insensitive, and cease generating events.

SET_BUTTON

This keyword applies to widgets created with the WIDGET_BUTTON function.

This keyword changes the current state of toggle buttons. If set equal to zero, every toggle button in the hierarchy specified by Widget_ID is set to the unselected state. If set to a nonzero value, the action depends on the type of base holding the buttons:

• For a non-exclusive base:
• If a single button is specified by Widget_ID, that button is set to the selected state, leaving the state of other buttons in the base unchanged.
• If the base itself is specified by Widget_ID, all buttons are set to the selected state.
• For an exclusive base:
• If a single button is specified by Widget_ID, that button is set to the selected state, and all other buttons in the base are set to the unselected state.
• If the base itself is specified by Widget_ID, IDL generates an error, since an exclusive base can contain at most one selected button.

If the specified Widget_ID is a button widget that was created using the CHECKED_MENU keyword, the checked state of the menu item is modified. If the keyword value is nonzero, the menu button is placed in a checked state. If the keyword value is zero, the button is placed in a un-checked state.

SET_COMBOBOX_SELECT

This keyword applies to widgets created with the WIDGET_COMBOBOX function.

Set this keyword to an integer that specifies the zero-based index of the combobox list element to be displayed. If the specified element is outside the range of existing elements, the selection remains unchanged.

SET_DRAG_NOTIFY

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

Set this keyword equal to a string containing the name of a function that will be automatically called as the end-user drags over the widget. Alternatively, set this keyword equal to the string:

• <inherit> (including the < and > characters) to have the widget inherit an ancestor’s callback
• <default> (including the < and > characters) to use the system default callback.

For more details, see the DRAG_NOTIFY keyword to WIDGET_DRAW or WIDGET_TREE.

SET_DRAGGABLE

This keyword applies to widgets created with the WIDGET_TREE function.

Use this keyword to specify whether or not the widget can be dragged. A value of 1 (one) makes the widget a valid drag item and a value of 0 (zero) makes the widget not draggable. If this keyword is not specified or is set to -1 then the widget inherits its draggability from the nearest ancestor that sets the a draggability value.

Note: Although the root node of a tree widget cannot be dragged nor inherit a value, the value can be set so that child nodes can inherit the value. The default value is 0.

SET_DRAW_VIEW

This keyword applies to widgets created with the WIDGET_DRAW function.

A scrollable draw widget provides a large graphics area which is viewed through a smaller viewport. This keyword allows changing the current position of the viewport. The desired position is specified as a 2-element integer array giving the X and Y position in units specified by the UNITS keyword (pixels are the default) relative to the lower left corner of the graphics area. For example, to position the viewport to the lower left corner of the image:

WIDGET_CONTROL, widget, SET_DRAW_VIEW=[0, 0]

SET_DROP_EVENTS

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

Use this keyword to specify whether or not the widget will generate drop events. See Widget Events Returned by Draw Widgets or Widget Events Returned by Tree Widgets for an explanation of the event structure.

A value of 1 (one) causes the widget to generate drop events and a value of 0 (zero) causes the widget to not generate drop events. If this keyword is not specified or is set to -1, the widget inherits this setting from the nearest ancestor that sets a value of zero or one.

Tree root nodes and draw widgets can generate drop events, but cannot inherit. Their default value is 0.

SET_DROPLIST_SELECT

This keyword applies to widgets created with the WIDGET_DROPLIST function.

Set this keyword to an integer that specifies the droplist element to be current (i.e., the element that is displayed on the droplist button). Positions start at zero. If the specified element is outside the possible range, no new selection is set.

SET_LIST_EVENTS

This keyword sets the LIST_EVENTS keyword, which generats events when the dropdown list is navigated by arrow up and arrow down keys.

SET_LIST_SELECT

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to an integer scalar or vector that specifies the list element or elements to be highlighted. The previous selection (if there is a selection) is cleared. Positions start at zero. If the specified element is outside the possible range, no new selection is set. Note that the MULTIPLE keyword to WIDGET_LIST must have been set if more than a single list element is specified.

If the selected position is not currently on the screen, the list widget automatically move the current scrolling viewport to make it visible. The resulting topmost visible element is toolkit specific. To ensure a certain element is at the top of the list, use the SET_LIST_TOP keyword (described below) to explicitly set the viewport.

SET_LIST_TOP

This keyword applies to widgets created with the WIDGET_LIST function.

Set this keyword to an integer that specifies the element of the list widget to be positioned at the top of the scrolling list. If the specified element is outside the range of list elements, nothing happens.

SET_MASK

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

When set to 1, all bitmap pixels that match the lower left pixel are treated as transparent, allowing the parent widget's background color to show through. When the keyword is not supplied or is explicitly set to 0, then transparency is not used in the bitmap.

For WIDGET_TREE, use this keyword in conjunction with SET_TREE_BITMAP to create a tree node icon that has transparency. This keyword is ignored when not used with SET_TREE_BITMAP.

The WIDGET_BUTTON MASK functionality is available only on the Microsoft Windows platform.

SET_SLIDER_MAX

This keyword applies to widgets created with the WIDGET_SLIDER function.

Set this keyword to a new maximum value for the specified slider widget.

Note: This keyword does not apply to floating-point sliders created with the CW_FSLIDER function.

SET_SLIDER_MIN

This keyword applies to widgets created with the WIDGET_SLIDER function.

Set this keyword to a new minimum value for the specified slider widget.

Note: This keyword does not apply to floating-point sliders created with the CW_FSLIDER function.

SET_TAB_CURRENT

This keyword applies to widgets created with the WIDGET_TAB function.

Set this keyword equal to the zero-based index of the tab to be set as the current (visible) tab. If the index value is invalid, the value is quietly ignored.

SET_TAB_MULTILINE

This keyword applies to widgets created with the WIDGET_TAB function.

This keyword controls how tabs appear on the tab widget when all of the tabs do not fit on the widget in a single row. This keyword behaves differently on Windows and UNIX systems.

Windows

Set this keyword to cause tabs to be organized in a multi-line display when the width of the tabs exceeds the width of the largest child base widget. If possible, IDL will create tabs that display the full tab text.

If MULTILINE=0 and LOCATION=0 or 1, tabs that exceed the width of the largest child base widget are shown with scroll buttons, allowing the user to scroll through the tabs while the base widget stays immobile.

If LOCATION=1 or 2, a multiline display is always used if the tabs exceed the height of the largest child base widget.

Note: The width or height of the tab widget is based on the width or height of the largest base widget that is a child of the tab widget. The text of the tabs (the titles of the tab widget’s child base widgets) may be truncated even if the MULTILINE keyword is set.

UNIX

Set this keyword equal to an integer that specifies the maximum number of tabs to display per row in the tab widget. If this keyword is not specified (or is explicitly set equal to zero) all tabs are placed in a single row.

Note: The width or height of the tab widget is based on the width or height of the largest base widget that is a child of the tab widget. The text of the tabs (the titles of the tab widget’s child base widgets) is never truncated in order to make the tabs fit the space available. (Tab text may be truncated if the text of a single tab exceeds the space available, however.) This means that if MULTILINE is set to any value other than one, some tabs may not be displayed.

SET_TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

• In standard selection mode, specify a four-element array, of the form [ left, top, right, bottom ] specifying the cells to act upon.
• In disjoint selection mode, specify a 2 x n element array of column/row pairs specifying the cells to act upon.

Specifications for cell locations are zero-based (that is, the first data column is column number zero). You can use the value -1 to indicate that IDL should select an entire row or column. For example, to select all of Rows 3 and 4, you can specify either [-1,3,-1,4] or [[-1,3],[-1,4]], depending on the table’s selection mode (standard or disjoint, respectively). This method differs from explicitly specifying all the cells of the rows in that IDL also selects the header cells, as if you had clicked on them. To deselect all cells, specify either [-1,-1,-1,-1] (in standard selection mode) or [-1,-1] (in disjoint selection mode).

See USE_TABLE_SELECT for details on the selection modes.

If the selected position is not currently on the screen, the table widget automatically moves the current scrolling viewport to make a portion of it visible. The resulting top-left visible cell is toolkit specific. To ensure a certain element is at the top of the list, use the SET_TABLE_VIEW keyword to explicitly set the viewport.

SET_TABLE_VIEW

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to a two-element array of zero-based cell indices that specifies the cell of the table widget to the positioned at the top-left of the widget. If the specified cell is outside the range of valid cells, nothing happens.

SET_TEXT_SELECT

This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions.

Use this keyword to clear any current selection in the specified table cell or text widget, and either set a new selection, or set the text insertion point. To set a selection, specify a two-element integer array containing the starting position and the length of the selection. For example, to set a selection covering characters 3 though 23:

WIDGET_CONTROL, widgetID, SET_TEXT_SELECT=[3, 20]

To move the text insertion point without setting a selection, omit the second element, or set it to zero.

SET_TEXT_TOP_LINE

This keyword applies to widgets created with the WIDGET_TEXT function.

Set this keyword to the zero-based line number of the line to be positioned on the topmost visible line in the text widget’s viewport. No horizontal scrolling is performed. Note that this is a line number, not a character offset.

SET_TREE_BITMAP

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword equal to an MxNx3 array representing an RGB image or an MxNx4 array representing an RGBA image that will be displayed next to the node in the tree widget.

Set this keyword equal to zero to revert to the appropriate default system bitmap.

SET_TREE_CHECKED

This keyword applies to widgets created with the WIDGET_TREE function, using the CHECKBOX and CHECKED keywords.

Set this keyword to change the state of a node's checkbox. The interpretation of the value depends on the type of tree widget, as described below:

Widget	Value	Effect on Checked State
Folder	0	Unchecked
	1	Checked
	2	The state is mixed. This state should indicate that the node has at least one, but not all child nodes checked or mixed.
Leaf	0	Unchecked
	1	Checked

Note: This keyword is ignored for the root node.

SET_TREE_EXPANDED

This keyword applies to widgets created with the WIDGET_TREE function.

Set this keyword equal to a nonzero value to expand the specified tree widget folder. Set this keyword equal to zero to collapse the specified tree widget folder.

SET_TREE_INDEX

This keyword applies to widgets created with the WIDGET_TREE function.

Use this keyword to change the position of a tree widget node relative to its siblings. The supplied value will be the new zero-based index of the node. Values of -1 and those greater than or equal to the number of siblings result in the node being positioned as the last of the children.

SET_TREE_SELECT

This keyword applies to widgets created with the WIDGET_TREE function.

This keyword has two modes of operation, depending on the widget ID passed to WIDGET_CONTROL:

• If the specified widget ID is for the root node of the tree widget (the tree widget whose Parent is a base widget):
• If the tree widget is in multiple-selection mode and SET_TREE_SELECT is set to an array of widget IDs corresponding to tree widgets that are nodes in the tree, those nodes are selected.
• If the tree widget is not in multiple-selection mode and SET_TREE_SELECT is set to a single widget ID corresponding to a tree widget that is a node in the tree, that node is selected.
• If the keyword is set to zero, all selections in the tree widget are cleared.
• If the specified widget ID is a tree widget that is a node in a tree:
• If the keyword is set to a nonzero value, the specified node is selected.
• If the keyword is set to zero, the specified node is deselected.

Note: If the tree widget is in multiple-selection mode, the selection changes made to the tree widget via this keyword are additive; the current selections are retained and any additional nodes specified by SET_TREE_SELECT are also selected.

SET_TREE_VISIBLE

This keyword applies to widgets created with the WIDGET_TREE function and whose parent widget was also created using the WIDGET_TREE function (that is, tree widgets that are nodes of another tree).

Set this keyword to make the specified tree node visible to the user. Setting this keyword has two possible effects:

1. If the specified node is inside a collapsed folder, the folder and all folders above it are expanded to reveal the node.
2. If the specified node is in a portion of the tree that is not currently visible because the tree has scrolled within the parent base widget, the tree view scrolls so that the selected node is at the top of the base widget.

Note: Use of this keyword does not affect the tree widget selection state.

SET_UNAME

This keyword applies to all widgets.

Set this keyword to a string that can be used to identify the widget. 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. You can set the name at creation time, using the UNAME keyword with the creation function.

To query the widget hierarchy, use the WIDGET_INFO function 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_UVALUE

This keyword applies to all widgets.

Each widget can contain a user-set value. This value is not used by IDL in any way, and exists entirely for the convenience of the IDL programmer. This keyword allows you to set this value.

To improve the efficiency of the data transfer, consider using the NO_COPY keyword with SET_UVALUE.

SET_VALUE

This keyword applies to widgets created with the WIDGET_BUTTON, WIDGET_COMBOBOX, WIDGET_DROPLIST, WIDGET_LABEL, WIDGET_LIST, WIDGET_PROPERTYSHEET, WIDGET_SLIDER, WIDGET_TABLE, WIDGET_TEXT, and WIDGET_TREE functions.

Sets the value of the specified widget. The meaning of the value differs between widget types:

• Button: The label to be used for the button. This value can be either a scalar string, or a 2D byte array containing a bitmap.
• Combobox: The contents of the combobox widget (string or string array).
• Droplist: The contents of the droplist widget (string or string array).
• Label: The text to be displayed by the label widget.
• List: The contents of the list widget (string or string array).
• Property Sheet: Object references to one or more component objects to be displayed in the property sheet. Any existing associations are lost and the property sheet is reloaded with the new list of properties. To completely clear the property sheet, use a null object reference.
• Slider: The current position of the slider (integer).

• Table: Normally, the data for the whole table is changed to the specified data, which must be of the form of a two dimensional array or a vector of structures. In this form, the table is resized to fit the given data (unless the TABLE_XSIZE or TABLE_YSIZE keywords are given).

  If the USE_TABLE_SELECT keyword is set, the value given is treated as a subset of the whole data, and only the given range of cells are updated. Used in this form, the type of data stored in the table cannot be changed. The data passed in is converted, as appropriate, to the type of the selected cells. If less data is passed in than fits in the current selection, the cells outside the range of data (but inside the selection) are left unchanged. If more data is passed in than fits in the current selection, the extra data is ignored.

• If the table is in standard selection mode, the data should be a two-dimensional array of values for a single-type table, or a vector of structures for a table that contains structure data.

• If the table is in disjoint selection mode, the data should be a one-dimensional array of values for a single-type table, or a single structure with each field corresponding to a cell for a table that contains structure data.

  If the USE_TEXT_SELECT keyword is present, the value must be a string, which replaces the currently-selected text in the currently-selected cell.

• Text: The text to be displayed. If the APPEND keyword is also specified, the text is appended to the current contents instead of instead of completely replacing it (string or string array). If the USE_TEXT_SELECT keyword is specified, the new string replaces only the currently-selected text in the text widget.
• Tree: The text to be displayed next to the tree widget node. Setting the value of the root node of a tree has no effect and is quietly ignored.
• Widget types not listed above do not allow the setting of a value. Attempting to set the value of such a widget causes an error.

The value of a widget can also be set with the VALUE keyword to the routine that created it.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

SHOW

This keyword applies to all widgets.

Controls the visibility of a widget hierarchy. If set to zero, the hierarchy containing Widget_ID is pushed behind any other windows on the screen. If nonzero, the hierarchy is pulled in front.

TAB_MODE

This keyword applies to widgets created with the WIDGET_BASE, WIDGET_BUTTON, WIDGET_COMBOBOX, WIDGET_DROPLIST, WIDGET_LIST, WIDGET_SLIDER, WIDGET_TAB, WIDGET_TABLE, WIDGET_TEXT, and WIDGET_TREE.

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 at creation time 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.

When WIDGET_CONTROL is used to change the TAB_MODE value, the change affects only the widget upon which it is explicitly set. The change is not propagated along the widget hierarchy after it has been created. The TAB_MODE keyword also cannot be explicitly set for the following widgets:

• Draw widgets
• Label widgets
• Grouped, exclusive button widgets (radio buttons)
• Menu items or menu bases

Attempting to set TAB_MODE on these widgets will generate an error.

Note: It is not possible to tab to disabled (SENSITIVE=0) or hidden (MAP=0) widgets.

Valid settings are:

0	Disable navigation onto or off of the widget. This is the default value 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: 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. Tabbing behavior may vary significantly between UNIX platforms; do not rely on a particular behavior being duplicated on all UNIX systems.

After creating the widget hierarchy, you can 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.

TABLE_BLANK

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to a nonzero value to cause the specified cells to be blank. Set this keyword equal to zero to cause the specified cells to display values as usual.

Note: Hiding cell contents using this keyword is a display-only operation. The cell contents are not removed from the table, they are hidden from view. Any operation that evaluates or changes the value of a cell will operate in the same way on a cell whose contents are hidden as it will on a cell whose contents are visible.

If the USE_TABLE_SELECT keyword is set equal to one, the currently selected cells are blanked or restored. If USE_TABLE_SELECT is set equal to an array, the specified cells are blanked or restored. If USE_TABLE_SELECT is not set, the entire table is hidden or displayed.

TABLE_DISJOINT_SELECTION

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to enable the ability to select multiple rectangular regions of cells.

TABLE_XSIZE

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to the number of data columns in the table widget. Note that if the table widget was created with row titles enabled (that is, if the NO_HEADERS or NO_COLUMN_HEADERS keywords to WIDGET_TABLE were not set), the table will contain one column more than the number specified by TABLE_XSIZE.

If the table is made smaller as a result of the application of the TABLE_XSIZE keyword, the data outside the new range persists, but the number of columns and/or rows changes as expected. If the table is made larger, the data type of the cells in the new columns is set according to the following rules:

1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR keywords set (if the table is an array rather than a vector of structures), the new cells have the same type as all the original cells.
2. If the SET_VALUE keyword is given, the types of all columns are set according to the new structure.
3. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE keyword is not specified, the cells in the new columns inherit their type from the cells to their left.
4. ²If the table was created with the COLUMN_MAJOR keyword set, and the SET_VALUE keyword is not specified, any new columns default to type INT.

TABLE_YSIZE

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword equal to the number of data rows in the table widget. Note that if the table widget was created with column titles enabled (that is, if the NO_HEADERS or NO_ROW_HEADERS keywords to WIDGET_TABLE were not set), the table will contain one row more than the number specified by TABLE_YSIZE.

If the table is made smaller as a result of the application of the TABLE_YSIZE keyword, the data outside the new range persists, but the number of columns and/or rows changes as expected. If the table is made larger, the data type of the cells in the new rows is set according to the following rules:

1. If the table was not created with either the ROW_MAJOR or COLUMN_MAJOR keywords set (if the table is an array rather than a vector of structures), the new cells have the same type as all the original cells.
2. If the SET_VALUE keyword is given, the types of all rows are set according to the new structure.
3. If the table was created with the COLUMN_MAJOR keyword set, and the SET_VALUE keyword is not specified, the cells in the new rows inherit their type from the cells above.
4. If the table was created with the ROW_MAJOR keyword set, and the SET_VALUE keyword is not specified, any new rows default to type INT.

TIMER

This keyword applies to all widgets.

If this keyword is present, a WIDGET_TIMER event is generated. Set this keyword to a floating-point value that represents the number of seconds before the timer event arrives. Note that this event is identical to any other widget event except that it contains only the 3 standard event tags. These event structures are defined as:

{ WIDGET_TIMER, ID:0L, TOP:0L, HANDLER:0L }

It is left to the caller to tell the difference between standard widget events and timer events. The standard way to do this is to use a widget that doesn’t normally generate events (e.g., a base or label). Alternately, the TAG_NAMES function can be called with the STRUCTURE_NAME keyword to differentiate a WIDGET_TIMER event from other types of events. For example:

IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $

   'WIDGET_TIMER' THEN ...

Using the TIMER keyword is more efficient than the background task functionality found in the XMANAGER procedure because it doesn’t “poll” like the original background task code. The background task functionality will eventually be eliminated from XMANAGER. We encourage all users to modify their code to use the TIMER keyword instead.

See Timer Events for additional details.

TLB_GET_OFFSET

This keyword applies to all widgets.

Set this keyword to a named variable in which the offset of the upper left corner of the top-level base of the specified widget is returned, in units specified by the UNITS keyword (pixels are the default). The offset is measured in device coordinates relative to the upper-left corner of the screen.

Note: On Windows and Mac platforms, the returned position is the upper-left corner of the window including border and title bar. On non-Mac Motif platforms, the returned position represents the upper-left corner of the window’s client area (not including border and titlebar).

TLB_GET_SIZE

This keyword applies to all widgets.

Set this keyword to a named variable in which the size of the top-level base of the specified widget is returned, in units specified by the UNITS keyword (pixels are the default). The size is returned as a two-element vector that contains the horizontal and vertical size of the base in device coordinates.

TLB_ICONIFY_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to make the top-level base return an event when the base is iconified or restored by the user.

TLB_KILL_REQUEST_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Use this keyword to set or clear kill request events for the specified top-level base. For more information on these events see TLB_KILL_REQUEST_EVENTS.

TLB_MOVE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to make the top-level base return an event when the base is moved by the user. Note that if TLB_SIZE_EVENTS are also enabled, a user resize operation that causes the top left corner of the base widget to move will generate both a move event and a resize event.

TLB_SET_TITLE

This keyword applies to all widgets.

Set this keyword to a scalar string to change the title of the specified top-level base after it has been created.

TLB_SET_XOFFSET

This keyword applies to all widgets.

Use this keyword to set the horizontal position of the top level base of the specified widget. The offset is measured from the upper-left corner of the screen to the upper-left corner of the base, in units specified by the UNITS keyword (pixels are the default).

TLB_SET_YOFFSET

This keyword applies to all widgets.

Use this keyword to set the vertical position of the top-level base of the specified widget. The offset is measured from the upper-left corner of the screen to the upper-left corner of the base, in units specified by the UNITS keyword (pixels are the default).

TLB_SIZE_EVENTS

This keyword applies to widgets created with the WIDGET_BASE function.

Set this keyword to make the top-level base return an event when the base is resized by the user. Note that if TLB_MOVE_EVENTS are also enabled, a user resize operation that causes the top left corner of the base widget to move will generate both a move event and a resize event.

TOOLTIP

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

Set this keyword to a string that will be displayed when the cursor hovers over the specified widget. For UNIX platforms, this string must be non-zero in length, which means that a tooltip can be modified but not be removed on UNIX versions of IDL.

Note: Tooltips cannot be created for menu sub-items. The topmost button on a menu can, however, have a tooltip.

Note: If your application uses hardware rendering and a RETAIN setting of either zero or one, tooltips will cause draw widgets to generate expose events if the tooltip obscures the drawable area. This is true even if the tooltip is associated with another widget.

Note: You can use language catalogs to internationalize this value with strings in particular languages.

TRACKING_EVENTS

This keyword applies to all widgets.

Set this keyword to a non-zero value to enable tracking events for the widget specified by Widget_ID. Set the keyword to 0 to disable tracking events for the specified widget. For a description of tracking events, see TRACKING_EVENTS in the documentation for WIDGET_BASE.

UNITS

This keyword applies to all widgets.

Use this keyword to specify the unit of measurement used when supplying measurements or position values. 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. This keyword does not change the units used in a widget event structure or in most of the fields of the geometry structure returned by WIDGET_INFO.

Note: This keyword does not affect all sizing operations. Specifically, the value of UNITS is ignored when setting the XSIZE or YSIZE keywords to WIDGET_LIST, WIDGET_TABLE, or WIDGET_TEXT functions.

UPDATE

This keyword applies to all widgets.

Use this keyword to enable (if set to 1) or disable (if set to 0) screen updates for the widget hierarchy to which the specified widget belongs. This keyword is useful for preventing unwanted intermediate screen updates when changing the values of many widgets at once or when adding several widgets to a previously-realized widget hierarchy. When first realized, widget hierarchies are set to update.

Note: Although this keyword is legal for any widget, it affects every widget in the hierarchy defined for the specified widget’s top-level base widget. In other words, setting UPDATE on a particular widget is equivalent to setting UPDATE on the top-level base widget that is at the top of the specified widget’s hierarchy.

Note: Do not attempt to resize a widget on the Windows platform while UPDATE is turned off. Doing so may prevent IDL from updating the screen properly when UPDATE is turned back on.

USE_TABLE_SELECT

This keyword applies to widgets created with the WIDGET_TABLE function.

Set this keyword to modify the behavior of the ALIGNMENT, BACKGROUND_COLOR, COLUMN_WIDTHS, DELETE_COLUMNS, DELETE_ROWS, EDITABLE, FONT, FOREGROUND_COLOR, FORMAT, GET_VALUE, INSERT_COLUMNS, INSERT_ROWS, ROW_HEIGHTS, SET_VALUE, and TABLE_BLANK keywords. If USE_TABLE_SELECT is set, these other keywords apply only to the currently selected cells. Normally, these keywords apply to the entire contents of a table widget.

Note: If either the header row or the header column of the table is selected, this keyword modifies the behavior of only the ROW_HEIGHTS or COLUMN_WIDTHS keywords.

Note: The Microsoft Windows platforms support the ROW_HEIGHTS keyword with the limitation that all rows have the same height. If you supply an array of values, IDL uses the last value for all rows.

Selection Modes

The table widget supports two selection modes:

• In standard selection mode, only a single selection can be created at a given time. Creating a new selection causes the existing selection to disappear.
• In disjoint selection mode, multiple selections can be created at one time. Creating a new selection does not cause the existing selection(s) to disappear. A table can be created in disjoint selection mode using either the DISJOINT_SELECTION keyword to WIDGET_TABLE or the TABLE_DISJOINT_SELECTION keyword to WIDGET_CONTROL.

The keywords listed above generate different output or expect different input based on the selection mode. See the description of each keyword for details. For more information on table selection modes, see Table Widget Selection Modes. 

Specifying Selections Programmatically

In many cases, your code will use a selection created by the user manually, with the mouse. You can also create selections programmatically, by setting USE_TABLE_SELECT equal to an array.

In standard selection mode, specify a four-element array, of the form [ left, top, right, bottom ] specifying the rectangle of cells to act upon.

In disjoint selection mode, specify a 2 x n element array of column/row pairs specifying the cells to act upon.

Specifications for cell locations are zero-based (that is, the first data column is column number zero). You can specify row and column headers by using -1 in the index. Row header cells are indexed by using -1 for the column; column header cells are indexed by using -1 for the row. Ranges can span header cells and value cells.

Note: Setting USE_TABLE_SELECT equal to an array does not change the current table selection. Operations affect the specified cells without changing the current selection. To change the current table selection, use SET_TABLE_SELECT.

Example

To change the column widths of the title column and the first five data columns of a table widget named wTable, leaving the widths of the other columns unchanged:

WIDGET_CONTROL, wTable, USE_TABLE_SELECT=[-1,0,4,0], $
    COLUMN_WIDTHS=50

This command is equivalent to first calling WIDGET_CONTROL and setting the SET_TABLE_SELECT keyword equal to an array, and then calling WIDGET_CONTROL with USE_TABLE_SELECT set equal to one. Please note that the command might change your selection.

For additional examples, see About Table Widgets.

USE_TEXT_SELECT

This keyword applies to widgets created with the WIDGET_TABLE and WIDGET_TEXT functions.

Set this keyword to modify the behavior of the GET_VALUE and SET_VALUE keywords. If USE_TEXT_SELECT is set, GET_VALUE and SET_VALUE apply only to the current text selection. Normally, these keywords apply to the entire contents of a text widget.

Note: If the target widget is a table, the selected cell must be in edit mode for WIDGET_CONTROL to return the selected text. (A table cell can be selected without being in edit mode; see About Table Widgets for a discussion of the table widget’s edit mode.) In most cases, to retrieve the value of a table cell, use the USE_TABLE_SELECT keyword rather than USE_TEXT_SELECT.

X_BITMAP_EXTRA

This keyword applies to widgets created with the WIDGET_BUTTON function.

When the value of a button widget is a bitmap, the usual width is taken to be 8 times the number of columns in the source byte array. This keyword can be used to indicate the number of bits in the last byte of each row that should be ignored. The value can range between 0 and 7.

XOFFSET

This keyword applies to all widgets.

Set this keyword to an integer value that specifies the widget’s new horizontal offset, in units specified by the UNITS keyword (pixels are the default). Attempting to change the offset of a widget that is the child of a ROW or COLUMN base or a widget that is part of a menubar or pulldown menu causes an error.

XSIZE

This keyword applies to all widgets.

Set this keyword to an integer or floating-point value that represents the widget’s new horizontal size.

• Text and List widgets: Size is specified in characters. The UNITS keyword is ignored.
• Table widgets: Size is specified in columns. The width of the row labels is automatically added to this value. The UNITS keyword is ignored.
• All other widgets: If the UNITS keyword is present, size is in the units specified. If the UNITS keyword is not present, the size is specified in pixels.

Note that [XY]SIZE sets client area and SCR_[XY]SIZE sets total area (title bar, borders, menu, client area). For scrollable widgets (e.g., scrolling bases and scrolling draw widgets), this keyword adjusts the viewport size. Use the DRAW_XSIZE keyword to change the width of the drawing area in scrolling draw widgets. Attempting to resize a widget that is part of a menubar or pulldown menu causes an error.

YOFFSET

This keyword applies to all widgets.

Set this keyword to an integer value that specifies the widget’s new vertical offset, in units specified by the UNITS keyword (pixels are the default). Attempting to change the offset of a widget that is the child of a ROW or COLUMN base or a widget that is part of a menubar or pulldown menu causes an error.

YSIZE

This keyword applies to all widgets.

Set this keyword to an integer or floating-point value that represents the widget’s new vertical size

• Text and List widgets: Size is specified in lines. The UNITS keyword is ignored.
• Table widgets: Size is specified in rows. The height of the column labels is automatically added to this value. The UNITS keyword is ignored.
• All other widgets: If the UNITS keyword is present, size is in the units specified. If the UNITS keyword is not present, the size is specified in pixels.

Note that [XY]SIZE sets client area and SCR_[XY]SIZE sets total area (title bar, borders, menu, client area). For scrollable widgets (e.g., scrolling bases and scrolling draw and table widgets), this keyword adjusts the viewport size. Use the DRAW_YSIZE keyword to change the height of the drawing area in scrolling draw widgets. Attempting to resize a widget that is part of a menubar or pulldown menu causes an error.

Version History

---

Pre-4.0	Introduced
5.6	Added COMBOBOX_ADDITEM, COMBOBOX_DELETEITEM, COMBOBOX_INDEX, DRAW_KEYBOARD_EVENTS, SET_BUTTON, SET_COMBOBOX_SELECT, SET_TAB_CURRENT, SET_TAB_MULTILINE, SET_TREE_BITMAP, SET_TREE_EXPANDED, SET_TREE_SELECT, SET_TREE_VISIBLE, TABLE_BLANK, TABLE_DISJOINT_SELECTION, TLB_ICONIFY_EVENTS, TLB_MOVE_EVENTS, TLB_SIZE_EVENTS, TOOLTIP keywords
6.0	Added PUSHBUTTON_EVENTS and REFRESH PROPERTY keywords
6.1	Added EDITABLE, MULTIPLE_PROPERTIES, PROPERTYSHEET_SETSELECTED, and TAB_MODE keywords
6.2	Added BACKGROUND_COLOR, DRAW_WHEEL_EVENTS, FONT, FOREGROUND_COLOR, and IGNORE_ACCELERATORS keywords Deprecated CANCEL_BUTTON and DEFAULT_BUTTON keywords
6.3	Added SET_DRAG_NOTIFY, SET_DRAGGABLE, SET_DROP_EVENTS, SET_MASK, and SET_TREE_INDEX keywords
8.2	Modified the SET_MASK keyword to include WIDGET_BUTTON Added REDRAW, SET_TREE_CHECKED keywords
8.2.1	Added SET_LIST_EVENTS keyword
8.7.2	Added BROWSER_CANCEL, BROWSER_GO_BACK, BROWSER_GO_FORWARD, BROWSER_NOTIFY, BROWSER_RELOAD keywords.

See Also

---

WIDGET_BASE, WIDGET_BROWSER, WIDGET_INFO, Working with Widget Events