WIDGET_CONTROL

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

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] [, /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 widgets created with WIDGET_ACTIVEX: [, GET_VALUE=value]

Keywords that apply to widgets created with WIDGET_BASE: [, BASE_SET_TITLE=string] [, CANCEL_BUTTON=widget_id{for modal bases}] [, /CONTEXT_EVENTS] [, DEFAULT_BUTTON=widget_id{for modal bases}] [, /ICONIFY] [, /KBRD_FOCUS_EVENTS] [, /TLB_ICONIFY_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] [, /TLB_MOVE_EVENTS] [, /TLB_SIZE_EVENTS]

Keywords that apply to widgets created with WIDGET_BUTTON: [, /BITMAP] [, /DYNAMIC_RESIZE] [, GET_VALUE=value] [, /INPUT_FOCUS] [, /PUSHBUTTON_EVENTS] [, /SET_BUTTON] [, SET_VALUE=value] [, TOOLTIP=string] [, X_BITMAP_EXTRA=bits]

Keywords that apply to widgets created with WIDGET_COMBOBOX: [, COMBOBOX_ADDITEM=string] [, COMBOBOX_DELETEITEM=integer] [, COMBOBOX_INDEX=integer] [, ./DYNAMIC_RESIZE] [, GET_VALUE=value] [, SET_COMBOBOX_SELECT=integer] [, SET_VALUE=value]

Keywords that apply to widgets created with WIDGET_DRAW: [, /DRAW_BUTTON_EVENTS] [, /DRAW_EXPOSE_EVENTS] [, DRAW_KEYBOARD_EVENTS={0 | 1 | 2}] [, /DRAW_MOTION_EVENTS] [, /DRAW_VIEWPORT_EVENTS] [, DRAW_XSIZE=integer] [, DRAW_YSIZE=integer] [, GET_DRAW_VIEW=variable] [, GET_UVALUE=variable] [, GET_VALUE=variable] [, /INPUT_FOCUS] [, SET_DRAW_VIEW=[x, y]] [, TOOLTIP=string]

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

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

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

Keywords that apply to widgets created with WIDGET_PROPERTYSHEET: [, REFRESH_PROPERTY=string, array of strings, or integer]

Keywords that apply to widgets created with WIDGET_SLIDER: [, GET_VALUE=value] [, SET_SLIDER_MAX=value] [, SET_SLIDER_MIN=value] [, SET_VALUE=value]

Keywords that apply to widgets created with WIDGET_TAB: [, SET_TAB_CURRENT=index] [, SET_TAB_MULTILINE=value]

Keywords that apply to widgets created with WIDGET_TABLE: [, ALIGNMENT={0 | 1 | 2}] [, /ALL_TABLE_EVENTS] [, AM_PM=[string, string]] [, COLUMN_LABELS=string_array] [, COLUMN_WIDTHS=array] [, 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]] [, FORMAT=value] [, GET_VALUE=variable] [, 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] [, /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 widgets created with WIDGET_TEXT: [, /ALL_TEXT_EVENTS] [, /APPEND] [, /CONTEXT_EVENTS] [, /EDITABLE] [, GET_VALUE=variable] [, /INPUT_FOCUS] [, /KBRD_FOCUS_EVENTS] [, /NO_NEWLINE] [, SET_TEXT_SELECT=[integer, integer]] [, SET_TEXT_TOP_LINE=line_number] [, SET_VALUE=value] [, /USE_TEXT_SELECT]

Keywords that apply to widgets created with WIDGET_TREE: [, SET_TREE_BITMAP=array] [, /SET_TREE_EXPANDED] [, SET_TREE_SELECT={0 | 1 | widget ID | array of widget IDs}] [, /SET_TREE_VISIBLE]

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

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 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.

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

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

ALL_TEXT_EVENTS

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

AM_PM

Supplies a string array of 2 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.

APPEND

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.

BAD_ID

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

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

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

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.

CANCEL_BUTTON

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

Set this keyword equal to the widget ID of a button widget that will be the cancel button on a modal base widget.

On Motif and Windows platforms, selecting Close from the system menu (generally located at the upper left of the base widget) generates a button event for the Cancel button.

CLEAR_EVENTS

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

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.

COLUMN_WIDTHS

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.

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

Set this keyword to a non-null 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

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

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.

CONTEXT_EVENTS

Set this keyword to cause context menu events (or simply context events) to be issued when the user clicks the right mouse button over the widget. Set the keyword to 0 (zero) to disable such events. Context events are intended for use with context-sensitive menus (also known as pop-up or shortcut menus); pass the context event ID to the WIDGET_DISPLAYCONTEXTMENU procedure within your widget program's event handler to display the context menu.

DAYS_OF_WEEK

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.

DEFAULT_BUTTON

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

Set this keyword equal to the widget ID of a button widget that will be the default button on a modal base widget. The default button is highlighted by the window system.

DEFAULT_FONT

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

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 About Device Fonts for details on specifying names for device fonts. If this keyword is omitted, the default font is used.

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

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.

DELETE_ROWS

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 columns that contain selected cells are deleted.

DESTROY

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

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

DRAW_EXPOSE_EVENTS

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

DRAW_KEYBOARD_EVENTS

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.

DRAW_MOTION_EVENTS

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

DRAW_VIEWPORT_EVENTS

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

DRAW_XSIZE

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

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

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

Set this keyword to allow direct user editing of the contents of a text or table widget. Normally, the text in text and table widgets is read-only. See the descriptions of the ALL_TABLE_EVENTS and ALL_TEXT_EVENTS keywords for additional details.

EDIT_CELL

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:

EVENT_FUNC

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 a null string ('').

EVENT_PRO

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 a null string ('').

FORMAT

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

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

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

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

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:

ActiveX: An object reference to the IDLcomActiveX object that underlies the ActiveX widget. See "Using ActiveX Controls in IDL" in the External Development Guide manual for details.

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:

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.

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.

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.

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

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.

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

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.

INPUT_FOCUS

If Widget_ID is a text widget, you can 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). This keyword has no effect for other widget types.

INSERT_COLUMNS

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.

INSERT_ROWS

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.

KBRD_FOCUS_EVENTS

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.

KILL_NOTIFY

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 the null 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. Calling XMANAGER with the CLEANUP keyword overrides any previous setting of KILL_NOTIFY. Similarly, calling WIDGET_CONTROL with KILL_NOTIFY overrides any previous setting of CLEANUP.

MANAGED

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

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

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.

NO_COPY

Usually, when setting or getting widget user values, either at widget creation or using the SET_UVALUE and GET_UVALUE keywords to WIDGET_CONTROL, IDL makes a second copy of the data being transferred. Although this technique 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 these 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 all 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.

NO_NEWLINE

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

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 the null string (''). The callback routine is called with the widget ID as its only argument.

PRO_SET_VALUE

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 2 arguments- a widget ID and a value. Using this technique allows you to designate a routine that sets the value for a widget. Compound widgets use this ability to define their values transparently to the user.

PUSHBUTTON_EVENTS

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

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.

REFRESH _PROPERTY

This keyword applies to widgets created with the WIDGET_PROPERTYSHEET function. Set this keyword to a property identifier or array of property identifiers to have just those properties synchronized with their values in the component(s). Recall that property identifiers are strings that uniquely determine a property. The keyword can also be set to a numeric value-non-zero values refresh all properties. The REFRESH_PROPERTY keyword also updates with respect to a property's sensitivity and visibility.

When all properties need synchronizing, it is more efficient to use /REFRESH_PROPERTY than WIDGET_CONTROL's SET_VALUE keyword to reload the property sheet.

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

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

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.

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 columns. 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.

SCR_XSIZE

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

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

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.

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

SENSITIVE

Set this keyword to control the sensitivity state of a widget after creation. This keyword applies to all widgets. 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.

Sensitivity can be used to control when a user is allowed to manipulate a widget. It should be noted that some widgets do not change their appearance when they are made insensitive, and simply cease generating events.

SET_BUTTON

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

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_DRAW_VIEW

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:

SET_DROPLIST_SELECT

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_SELECT

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 in set. Note that the MULTIPLE keyword to WIDGET_LIST must have been set in 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. If you wish 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

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

SET_SLIDER_MAX

SET_SLIDER_MIN

SET_TAB_CURRENT

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 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.

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.

SET_TABLE_SELECT

In standard selection mode, specify a four-element array, of the form [ left, top, right, bottom ] specifying the 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). The value -1 is used to refer to the title row or title column.

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. If you wish 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

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

Use this keyword to clear any current selection in the specified table cell or text widget, and either set a new selection, or simply 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:

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

SET_TEXT_TOP_LINE

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

Set this keyword equal to a 16x16x3 array representing an RGB image that will be displayed next to the node in the tree widget.

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

SET_TREE_EXPANDED

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_SELECT

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.

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:

If the specified node is inside a collapsed folder, the folder and all folders above it are expanded to reveal the node.

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.

SET_UNAME

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

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

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: Associates one or more component objects with a property sheet. Any existing associations are lost and the property sheet is reloaded with the new list of properties. Use the SET_VALUE keyword to WIDGET_CONTROL. Use the return value of obj_new() to clear out a property sheet.

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.

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.

SHOW

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.

TABLE_BLANK

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.

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

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

TABLE_XSIZE

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 keyword to WIDGET_TABLE was 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:

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.

If the SET_VALUE keyword is given, the types of all columns are set according to the new structure.

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.

·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

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 keyword to WIDGET_TABLE was 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:

If the SET_VALUE keyword is given, the types of all rows are set according to the new structure.

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.

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

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:

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:

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. RSI will eventually eliminate the background task functionality from XMANAGER. We encourage all users to modify their code to use the TIMER keyword instead.

TLB_GET_OFFSET

Set this keyword to a named variable in which the offset 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.

TLB_GET_SIZE

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

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

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

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

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

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

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

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

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.

TRACKING_EVENTS

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

Use this keyword to specify the unit of measurement used for most widget sizing operations. Set UNITS equal to 0 to specify that all measurements are in pixels (this is the default), to 1 to specify that all measurements are in inches, or to 2 to specify that all measurements are in centimeters.

UPDATE

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.

USE_TABLE_SELECT

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 to 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 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 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). The value -1 is used to refer to the title row or title column.

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.

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:

USE_TEXT_SELECT

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.

X_BITMAP_EXTRA

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

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

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

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

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

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 added: 5.6