WIDGET_BASE

The WIDGET_BASE function is used to create base widgets. Base widgets serve as containers for other widgets, including other base widgets. Base widgets can optionally contain scroll bars that allow the base to be larger than the space on the screen. In this case, only part of the base is visible at any given time, and the scroll bars are used to control which part is visible.

Tip: In most cases, you will want to let IDL determine the placement of widgets within the base widget. Do this by specifying either the COLUMN keyword or the ROW keyword. See Positioning Child Widgets Within a Base for details.

Syntax

Result = WIDGET_BASE( [Parent] [, /ALIGN_BOTTOM | , /ALIGN_CENTER | , /ALIGN_LEFT | , /ALIGN_RIGHT | , /ALIGN_TOP] [, /BASE_ALIGN_BOTTOM | , /BASE_ALIGN_CENTER | , /BASE_ALIGN_LEFT | , /BASE_ALIGN_RIGHT | , /BASE_ALIGN_TOP] [, BITMAP=value] [, COLUMN=value | , ROW=value] [, /CONTEXT_EVENTS] [, /CONTEXT_MENU] [, EVENT_FUNC=string] [, EVENT_PRO=string] [, /EXCLUSIVE | , /NONEXCLUSIVE] [, /FLOATING] [, FRAME=value] [, FUNC_GET_VALUE=string] [, /GRID_LAYOUT] [, GROUP_LEADER=widget_id] [, /KBRD_FOCUS_EVENTS] [, KILL_NOTIFY=string] [, /MAP] [, /MASK] [, MBAR=variable | , /MODAL] [, /NO_COPY] [, NOTIFY_REALIZE=string] [, PRO_SET_VALUE=string] [, SCR_XSIZE=value] [, SCR_YSIZE=value] [, /SCROLL] [, /SENSITIVE] [, SPACE=value] [, TAB_MODE=value] [, TITLE=string] [, TLB_FRAME_ATTR=value] [, /TLB_ICONIFY_EVENTS] [, /TLB_KILL_REQUEST_EVENTS] [, /TLB_MOVE_EVENTS] [, /TLB_RESIZE_NODRAW] [, /TLB_SIZE_EVENTS] [, /TOOLBAR] [, /TRACKING_EVENTS] [, UNAME=string] [, UNITS=value] [, UVALUE=value] [, XOFFSET=value] [, XPAD=value] [, XSIZE=value] [, X_SCROLL_SIZE=value] [, YOFFSET=value] [, YPAD=value] [, YSIZE=value] [, Y_SCROLL_SIZE=value] )

Motif Keywords: [, DISPLAY_NAME=string] [, RESOURCE_NAME=string] [, RNAME_MBAR=string]

Return Value

The returned value of this function is the widget ID of the newly-created base.

Arguments

Parent

The widget ID of the parent widget. To create a top-level base, omit the Parent argument.

Keywords

ALIGN_BOTTOM

Set this keyword to align the new widget with the bottom of its parent base. To take effect, the parent must be a ROW base.

ALIGN_CENTER

Set this keyword to align the new widget with the center of its parent base. To take effect, the parent must be a ROW or COLUMN base. In ROW bases, the new widget will be vertically centered. In COLUMN bases, the new widget will be horizontally centered.

ALIGN_LEFT

Set this keyword to align the new widget with the left side of its parent base. To take effect, the parent must be a COLUMN base.

ALIGN_RIGHT

Set this keyword to align the new widget with the right side of its parent base. To take effect, the parent must be a COLUMN base.

ALIGN_TOP

Set this keyword to align the new widget with the top of its parent base. To take effect, the parent must be a ROW base.

To apply actions triggered by menu items to widgets other than the base that includes the menubar, use the KBRD_FOCUS_EVENTS keyword to keep track of which widget has (or last had) the keyboard focus.

BASE_ALIGN_BOTTOM

Set this keyword to make all children of the new base align themselves with the bottom of the base by default. To take effect, you must also set the ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created.

BASE_ALIGN_CENTER

Set this keyword to make all children of the new base align themselves with the center of the base by default. To take effect, you must also set the COLUMN or ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created. In ROW bases, child widgets will be vertically centered. In COLUMN bases, child widgets will be horizontally centered.

BASE_ALIGN_LEFT

Set this keyword to make all children of the new base align themselves with the left side of the base by default. To take effect, you must also set the COLUMN keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created.

BASE_ALIGN_RIGHT

Set this keyword to make all children of the new base align themselves with the right side of the base by default. To take effect, you must also set the COLUMN keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created.

BASE_ALIGN_TOP

Set this keyword to make all children of the new base align themselves with the top of the base by default. To take effect, you must also set the ROW keyword for the new base. The default can be overridden for individual child widgets by setting a different ALIGN_XXX keyword when the child widget is created.

BITMAP

Set this keyword to specify a custom top level base icon that will be used in the title bar, the task bar and the Windows task switching window (accessed using Alt+Tab).

There are three allowed value types:

Value Type	Description
String	The full path to a bitmap or icon file (BMP or ICO)
String Array	The full paths to one or more bitmap files
Byte Array	An [n, n, 3] byte array containing the red, green, and blue values for the icon.

Specifying an icon file or an array of bitmap files allows the top level base icon to be legible at a wide range of sizes. IDL chooses the image whose size best matches the needed use (title bar, task switcher, etc.). It is recommended that ICO files and arrays of bitmap files include both 16x16 pixel and 32x32 pixel images. In rare cases a 48x48 pixel image might be useful because users can customize window properties, such as the height of title bars. When there is no exact match the image is automatically scaled.

When the keyword is not set, the top level base inherits the icon of its group leader. An application-wide icon can be specified by applying the icon to just the group leaders.

To enable transparency in BMP files and byte arrays, set the MASK keyword. Icon files (.ICO) define their own transparency.

Note: The base widget icon functionality is only available on the Microsoft Windows platform. On Motif platforms the BITMAP and MASK keywords are quietly ignored.

COLUMN

If this keyword is included, the base lays out its children in columns. The value of this keyword specifies the number of columns to be used. The number of child widgets in each column is determined by distributing the children as evenly as possible across the columns.

Specifying both the COLUMN and ROW keywords causes an error.

Column Width

The width of each column is determined by the width of the widest widget in that column. If the GRID_LAYOUT keyword is set, all columns are as wide as the widest widget in the base.

Horizontal Size of Widgets

If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its “natural” width, determined either by the value of the widget or by the XSIZE keyword. Similarly, if any of the child widgets specifies one of the ALIGN_* keywords, that widget will have its “natural” width. If none of the BASE_ALIGN_* or (ALIGN_*) keywords are set, all widgets in the base are as wide as their column.

Vertical Placement

Child widgets are placed vertically one below the other, with no extra space. If the GRID_LAYOUT keyword is set, each row is as high as its tallest member.

CONTEXT_EVENTS

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.

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

CONTEXT_MENU

Set this keyword to create a base widget that can be used as the base for a context-sensitive menu (also known as a pop-up or shortcut menu). A context menu base must have as its parent one of the following types of widgets: WIDGET_BASE, WIDGET_DRAW, WIDGET_TEXT, WIDGET_LIST, WIDGET_PROPERTYSHEET, WIDGET_TABLE, WIDGET_TEXT or WIDGET_TREE.

For more on creating context menus, see Context-Sensitive Menus.

DISPLAY_NAME

Set this keyword equal to a string that specifies the name of the X Windows display on which the base should be displayed. This keyword has no effect on Microsoft Windows platforms.

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 rooted at the newly-created widget.

Note: If you are using XMANAGER to manage events for your widget application, do not specify an event processing routine for the top-level base of the application using this keyword. Instead, specify the event processing routine using the EVENT_HANDLER keyword to XMANAGER.

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 rooted at the newly-created widget.

EXCLUSIVE

Set this keyword to specify that the base can have only button-widget children and that only one button can be set at a time. These buttons, unlike normal button widgets, have two states—set and unset.

When one exclusive button is pressed, any other exclusive buttons (in the same base) that are currently set are automatically released. Hence, only one button can ever be set at one time.

This keyword can be used to create exclusive button menus. See the CW_BGROUP and CW_PDMENU functions for high-level menu-creation utilities.

Note: If this keyword is set, the XOFFSET and YOFFSET keywords are ignored for any widgets in this base. Exclusive bases are always laid out in columns or rows. If neither the COLUMN nor ROW keyword is specified for an exclusive base, the base defaults to COLUMN layout.

FLOATING

Set this keyword—along with the GROUP_LEADER keyword—to create a “floating” top-level base widget. If the windowing system provides Z-order control, floating base widgets appear above the base specified as their group leader. If the windowing system does not provide Z-order control, the FLOATING keyword has no effect.

See Iconizing, Layering, and Destroying Groups of Top-Level Bases.

FRAME

The value of this keyword specifies the width of a frame (in pixels) to be drawn around the borders of the widget. Note that this keyword is only a hint to the toolkit, and may be ignored in some instances.

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

GRID_LAYOUT

Set this keyword to force the base to have a grid layout, in which all rows have the same height, and all columns have the same width. The row heights and column widths are taken from the largest child widget.

GROUP_LEADER

The widget ID of an existing widget that serves as “group leader” for the newly-created widget. Widget application hierarchies are defined by group membership relationships between top-level widget bases. When a group leader is killed, for any reason, all widgets in the group are also destroyed. See Iconizing, Layering, and Destroying Groups of Top-Level Bases.

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.

If the group leader specified by this keyword uses a custom title bar icon (as specified by the BITMAP keyword), the same icon will be used in the title bar of a new top-level base widget. If a top-level base has more than one group leader, the icon associated with the first group leader assigned is used.

On multi-monitor configurations, the widget will appear at the upper-left corner [0,0] of the monitor that contains the group leader if no explicit offset was specified.

Note: If you specify a modal base (created with the MODAL keyword) as a group leader, all member bases will automatically be created as modal. If you specify a floating base (created with the FLOATING keyword) as a group leader, all non-modal member bases will automatically be created as floating.

Note: If you are creating a MODAL base you must set the GROUP_LEADER keyword.

KBRD_FOCUS_EVENTS

Set this keyword to make the base return keyboard focus events whenever the keyboard focus of the base changes. See the “Events Returned by Base Widgets” section below for more information.

KILL_NOTIFY

Set this keyword to a string that contains the name of a procedure to be called automatically when the specified widget dies. Each widget is allowed a single such “callback” procedure. It can be removed by setting the routine 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.

Note: A procedure specified via the CLEANUP keyword to XMANAGER will override a procedure specified for your application’s top-level base with WIDGET_BASE, KILL_NOTIFY.

MAP

Once a widget hierarchy has been realized, it can be mapped (visible) or unmapped (invisible). This keyword specifies the initial map state for the given base and its descendants. Specifying a non-zero value indicates that the base should be mapped when realized (the default). A zero value indicates that the base should be unmapped initially.

After the base is realized, its map state can be altered using the MAP keyword to the WIDGET_CONTROL procedure.

Note: Modal bases cannot be mapped and unmapped.

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

MASK

Set this keyword along with the BITMAP keyword to create a top level base icon that has transparency. When set to 1 (one), all bitmap pixels that match the lower left pixel are treated as transparent, allowing the background color to show through. The default value is 0. The MASK keyword has no effect when the BITMAP keyword references an icon file (.ico) because images in icon files define their own transparency.

Note: The base widget icon functionality is only available on the Microsoft Windows platform. On Motif platforms the BITMAP and MASK keywords are quietly ignored.

MBAR

Set this keyword to a named variable to cause a menubar to be placed at the top of the base (the base must be a top-level base). The menubar is itself a special kind of base widget that can only have buttons as children. Upon return, the named variable contains the widget ID of the new menubar base. This widget ID can then be used to fill the menubar with pulldown menus. For example, the following widget creation commands first create a base with a menubar, then populate the menubar with a simple pulldown menu (CW_PDMENU could also have been used to construct the pulldown menu):

base = WIDGET_BASE(TITLE = 'Example', MBAR=bar)

file_menu = WIDGET_BUTTON(bar, VALUE='File', /MENU)

file_bttn1=WIDGET_BUTTON(file_menu, VALUE='Item 1',$

   UVALUE='FILE1')

file_bttn2=WIDGET_BUTTON(file_menu, VALUE='Item 2',$

   UVALUE='FILE2')

Note that to set X Window System resources for menubars created with this keyword, you must use the RNAME_MBAR keyword rather than the RESOURCE_NAME keyword.

If you use CW_PDMENU to create a menu for the menubar, be sure to set the MBAR keyword to that function as well.

Note also that the size returned by the GEOMETRY keyword to WIDGET_INFO does not include the size of the menubar.

Note: You cannot specify both the MBAR and MODAL keywords for the same widget. Doing so will cause an error.

Note: You cannot specify both an APP_MBAR and an MBAR for the same top-level base widget. Doing so will cause an error.

MODAL

Set this keyword to create a modal dialog. While a modal dialog is displayed, IDL blocks event processing.

Note: Modal dialogs must have a group leader. Specify the group leader for a modal top-level base via the GROUP_LEADER keyword.

Modal dialogs cannot be scrollable, nor can they support menubars. Setting the SCROLL, MBAR, or APP_MBAR keywords in conjunction with the MODAL keyword will cause an error. Modal dialogs cannot be mapped or unmapped. Setting the MAP keyword on a modal base will cause an error. Modal dialogs cannot be resized, regardless of the setting of the TLB_SIZE_EVENTS keyword.

Note: On Windows platforms, the group leader of a modal base must be realized before the modal base itself can be realized. If the group leader has not been realized, it will be realized automatically.

See “Iconizing, Layering, and Destroying Groups of Top-Level Bases”.

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 UVALUE keyword to WIDGET_BASE or 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.

NONEXCLUSIVE

Set this keyword to specify that the base can only have button widget children. These buttons, unlike normal button widgets, have two states—set and unset. Non-exclusive bases allow any number of the toggle buttons to be set at one time.

Note: If this keyword is set, the XOFFSET and YOFFSET keywords are ignored for any widgets in this base. Non-exclusive bases are always laid out in columns or rows. If neither the COLUMN nor ROW keyword is specified for a non-exclusive base, the base defaults to COLUMN layout.

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. It can be removed by setting the routine to an empty 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. See the description of the PRO_SET_VALUE keyword to WIDGET_CONTROL for information on using this keyword.

RESOURCE_NAME

A string containing an X Window System resource name to be applied to the widget. Once defined, this name can be used in the user’s .Xdefaults file to customize widget resources not directly supported via the IDL widget routines. This keyword is accepted by all widget creation routines. This keyword only works with the “X” device and is ignored on Microsoft Windows platforms.

RESOURCE_NAME allows unrestricted access to the underlying Motif widgets within the following limitations:

Users must have the appropriate resources defined in their .Xdefaults or application default resource file, or IDL will not see the definitions and they will not take effect.
Motif resources are documented in the OSF/Motif Programmer’s Reference Manual. To use them with RESOURCE_NAME, the IDL programmer must determine the type of widget being used by IDL, and then look up the resources that apply to them. Hence, RESOURCE_NAME requires some programmer-level familiarity with Motif.
Only resources that are not set within IDL can be modified using this mechanism. Although it is not an error to set resources also set by IDL, the IDL settings will silently override user settings. These IDL resources are not documented since the actual resources used may differ from release to release as the IDL widgets evolve. Therefore, you should set only those resources that are obviously not being set by IDL. Among the resources that are not being set by IDL are those that control colors, menu mnemonics, and accelerator keys.

Example

The sample code below produces a pulldown menu named “Menu” with 2 entries named “Item 1” and “Item 2”.

Using the RESOURCE_NAME keyword in conjunction with X resource definitions, we can alter “Item 1” in several ways not possible through the standard IDL widgets interface. We’ll give Item 1 a red background color. We’ll also assign “I” as the keyboard mnemonic. Note that Motif automatically underlines the “I” in the title to indicate this. We’ll also select Meta-F4 as the keyboard accelerator for selecting “Item 1”. If Meta-F4 is pressed while the pointer is anywhere over this application, the effect will be as if the menu was pulled down and “Item 1” was selected with the mouse.

; Simple event handler:

PRO test_event, ev

   HELP, /STRUCTURE, ev

END

; Simple widget creation routine:

PRO test

   ; The base gets the resource name "test":

   a = WIDGET_BASE(RESOURCE_NAME = 'test')

   b = WIDGET_BUTTON(a, VALUE='Menu', /MENU)

   ; Assign the Item 1 button the resource name "item1":

   c = WIDGET_BUTTON(b, VALUE='Item 1', $

      RESOURCE_NAME='item1')

   c = WIDGET_BUTTON(b, VALUE='Item 2')

   WIDGET_CONTROL, /REALIZE, a

   XMANAGER, 'test', a

END

Note that we gave the overall application the resource name “test”, and the “Item 1” button the resource name “item1”. Now we can use these names in the following .Xdefaults file entries:

Idl*test*item1*mnemonic: I

Idl*test*item1*accelerator: Meta<Key>F4

Idl*test*item1*acceleratorText: Meta-F4

Idl*test*item1*background: red

Note on Specifying Color Resources

To specify unique colors for your widgets, it is generally a good idea to use a color name (“red” or “lightblue”, for example) rather than specifying an exact color match with a color string (such as “#b1b122222020”). If IDL is not able to allocate an exact color, the entire operation may fail. Specifying a named color implies “closest color match,” an operation that rarely fails.

If you need an exact color match and IDL fails to allocate the color, try modifying the Idl.colors resource in the $IDL_DIR/resource/X11/lib/app-defaults/Idl file.

RNAME_MBAR

A string containing an X Window System resource name to be applied to the menubar created by the MBAR keyword. This keyword is identical to the RESOURCE_NAME keyword except that the resource it specifies applies only to the menubar.

ROW

If this keyword is included, the base lays out its children in rows. The value of this keyword specifies the number of rows to be used. The number of child widgets in each row is determined by distributing the children as evenly as possible across the rows.

Specifying both the COLUMN and ROW keywords causes an error.

Row Height

The height of each row is determined by the height of the tallest widget in that row. If the GRID_LAYOUT keyword is set, all rows are as tall as the tallest widget in the base.

Vertical Size of Widgets

If any of the BASE_ALIGN_* keywords to WIDGET_BASE is set, each widget has its “natural” height, determined either by the value of the widget or by the YSIZE keyword. Similarly, if any of the child widgets specifies one of the ALIGN_* keywords, that widget will have its “natural” height. If none of the BASE_ALIGN_* or (ALIGN_*) keywords are set, all widgets in the base are as tall as their row.

Horizontal Placement

Child widgets are placed horizontally one next to the other, with no extra space. If the GRID_LAYOUT keyword is set, each column is as wide as its widest member.

SCR_XSIZE

Set this keyword to the desired “screen” width of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the XSIZE keyword.

SCR_YSIZE

Set this keyword to the desired “screen” height of the widget, in units specified by the UNITS keyword (pixels are the default). In many cases, setting this keyword is the same as setting the YSIZE keyword.

SCROLL

Set this keyword to give the widget scroll bars that allow viewing portions of the widget contents that are not currently on the screen. You must also set X_SCROLL_SIZE and Y_SCROLL_SIZE to set the viewport size.

Note: Under UNIX, base widgets with scroll bars do not automatically size themselves to fit their contents. Use the XSIZE and YSIZE keywords to explicitly specify the size of the base widget.

Note: You cannot specify both the SCROLL and MODAL keywords for the same widget.

SENSITIVE

Set this keyword to control the initial sensitivity state of the widget.

If SENSITIVE is zero, the widget becomes insensitive. If nonzero, it becomes sensitive. When a widget is sensitive, it has normal appearance and can receive user input. For example, a sensitive button widget can be activated by moving the mouse cursor over it and pressing a mouse button. When a widget is insensitive, it indicates the fact by changing its appearance, looking disabled, and it ignores any input.

Sensitivity can be used to control when a user is allowed to manipulate the widget. Note that some widgets do not change their appearance when they are made insensitive, but they cease generating events.

Note: Under Microsoft Windows, a top-level base that is insensitive does not allow the user to control the window using the system close or minimize/maximize buttons.

After creating the widget hierarchy, you can change the sensitivity state using the SENSITIVE keyword with the WIDGET_CONTROL procedure.

SPACE

The space, in units specified by the UNITS keyword (pixels are the default), between children of a row or column major base. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present.

TAB_MODE

Set this keyword to one of the values shown in the table below to determine how the widget hierarchy can be navigated using the Tab key. The TAB_MODE setting is inherited by lower-level bases and child widgets unless it is explicitly set on an individual widget.

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. 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 change tabbing support using the WIDGET_CONTROL procedure’s TAB_MODE keyword, or query a widget’s support for tabbing using the WIDGET_INFO procedure’s TAB_MODE keyword.

See Tabbing in Widget Applications for usage details and examples.

TITLE

A string containing the title to be used for the widget. Base widgets use the title only if they are top-level widgets or if they are children of a tab widget. For top-level base widgets, the title appears in the “window dressing” at the top of the base widget; the appearance is platform-specific. For base widgets that have a tab widget as their parent widget, the title is used as the text of the tab.

Note that if the widget base is not wide enough to contain the specified title, the title may appear truncated. If you must be able to see the full title, you have several alternatives:

Rearrange the widgets in the base so that the base becomes naturally wide enough. This is the best solution.
Don’t worry about this issue. If the user needs to see the entire label, they can resize the window using the mouse.
Create the base without using the COLUMN or ROW keywords. Instead, use the XSIZE keyword to explicitly set a usable width. This is an undesirable solution that can lead to strange-looking widget layouts.

For bases that are children of tab widgets, the title may be truncated depending on the width of the largest base that is a child of the tab widget. See the description of the MULTILINE keyword to WIDGET_TAB for additional details.

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

TLB_FRAME_ATTR

Set this keyword to one of the values shown in the table below to suppress certain aspects of a top-level base’s window frame. This keyword applies only to top-level bases. The settings are merely hints to the window system and may be ignored by some window managers. Valid settings are:

1	Base cannot be resized, minimized, or maximized.
2	Suppress display of system menu.
4	Suppress title bar.
8	Base cannot be closed.
16	Base cannot be moved.

This keyword is set bitwise, so multiple effects can be set by adding values together. For example, to make a base that has no title bar (value 4) and cannot be moved (value 16), set the TLB_FRAME_ATTR keyword to 20 (that is, 4+16).

TLB_ICONIFY_EVENTS

Set this keyword when creating a top-level base to make that base return an event when the base is iconified or restored by the user. See the Events Returned by Base Widgets section below for more information.

TLB_KILL_REQUEST_EVENTS

Set this keyword, usable only with top-level bases, to send the top-level base a WIDGET_KILL_REQUEST event if a user tries to destroy the widget using the window manager (by default, widgets are destroyed). See the “Events Returned by Base Widgets” section below for more information.

Use this keyword to perform complex actions before allowing a widget application to exit. Note that widgets that have this keyword set are responsible for killing themselves after receiving a WIDGET_KILL_REQUEST event—they cannot be destroyed using the usual window system controls.

Use a call to TAG_NAMES with the STRUCTURE_NAME keyword set to differentiate a WIDGET_KILL_REQUEST event from other types of widget events. For example:

IF TAG_NAMES(event, /STRUCTURE_NAME) EQ $

   'WIDGET_KILL_REQUEST' THEN ...

TLB_MOVE_EVENTS

Set this keyword when creating a top-level base to make that base return an event when the base is moved on the screen by the user. See the “Events Returned by Base Widgets” section below for more information.

TLB_RESIZE_NODRAW

Set this keyword when creating a top-level base. If this keyword is set then the base widget (and all of its children) will not be redrawn while a user is resizing the widget. By default, IDL redraws the entire widget while the user is resizing the base, which may cause flashing for very complex widget applications. This keyword only has an effect on Windows platforms and is quietly ignored on other platforms. This keyword can only be set on the initial call to WIDGET_BASE and may not be changed later.

TLB_SIZE_EVENTS

Set this keyword, when creating a top-level base, to make that base return an event when the base is resized by the user. See the Events Returned by Base Widgets section below for more information.

TOOLBAR

Set this keyword to indicate that the base is used to hold bitmap buttons that make up a toolbar.

Note: Setting this keyword does not cause any changes in behavior; its only affect is to slightly alter the appearance of the bitmap buttons on the base for cosmetic reasons.

Note: On Motif platforms, if bitmap buttons are on a toolbar base that is also EXCLUSIVE or NONEXCLUSIVE, they will not have a separate “toggle” indicator, they will be grouped closely together, and will have a two-pixel shadow border.

TRACKING_EVENTS

Set this keyword to cause widget tracking events to be issued for the widget whenever the mouse pointer enters or leaves the region covered by that widget. Widget tracking events are returned as structures with the following definition:

{ WIDGET_TRACKING, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }

ID, TOP, and HANDLER are the standard fields found in every widget event. ENTER is 1 if the tracking event is an entry event, and 0 if it is an exit event.

See Tracking Events for more information.

UNAME

Set this keyword to a string that can be used to identify the widget in your code. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID.

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

UNITS

Set this keyword to specify the units 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.

UVALUE

The “user value” to be assigned to the widget.

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

If UVALUE is not present, the widget’s initial user value is undefined.

The user value for a widget can be accessed and modified at any time by using the GET_UVALUE and SET_UVALUE keywords to the WIDGET_CONTROL procedure.

XOFFSET

The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent.

Specifying an offset relative to a row or column major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.

XPAD

The horizontal space, in units specified by the UNITS keyword (pixels are the default), between child widgets and the edges of a row or column major base. The default value of XPAD is platform dependent. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present.

XSIZE

The width of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a “hint” to the toolkit and may be ignored in some situations.

X_SCROLL_SIZE

The XSIZE keyword always specifies the width of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the width of the visible area. The X_SCROLL_SIZE keyword allows you to set the width of the scrolling viewport independently of the actual width of the widget. X_SCROLL_SIZE must be less than XSIZE for scrollbars to appear.

Use of the X_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when X_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify Y_SCROLL_SIZE when specifying X_SCROLL_SIZE.

Note: X_SCROLL_SIZE and Y_SCROLL_SIZE are ignored if you specify the screen size using the SCR_XSIZE and SCR_YSIZE keywords to the widget creation routine.

YOFFSET

The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.

YPAD

The vertical space, in units specified by the UNITS keyword (pixels are the default), between child widgets and the edges of a row or column major base. The default value of YPAD is platform-dependent. This keyword is ignored if either the EXCLUSIVE or NONEXCLUSIVE keyword is present.

YSIZE

The height of the widget in units specified by the UNITS keyword (pixels are the default). Most widgets attempt to size themselves to fit the situation. However, if the desired effect is not produced, use this keyword to override it. This keyword is only a “hint” to the toolkit and may be ignored in some situations.

Y_SCROLL_SIZE

The YSIZE keyword always specifies the height of a widget. When the SCROLL keyword is specified, this size is not necessarily the same as the height of the visible area. The Y_SCROLL_SIZE keyword allows you to set the height of the scrolling viewport independently of the actual height of the widget. Y_SCROLL_SIZE must be less than YSIZE for scrollbars to appear.

Use of the Y_SCROLL_SIZE keyword implies SCROLL. This means that scroll bars will be added in both the horizontal and vertical directions when Y_SCROLL_SIZE is specified. Because the default size of the scrolling viewport may differ between platforms, it is best to specify X_SCROLL_SIZE when specifying Y_SCROLL_SIZE.

Note: X_SCROLL_SIZE and Y_SCROLL_SIZE are ignored if you specify the screen size using the SCR_XSIZE and SCR_YSIZE keywords to the widget creation routine.

Keywords to WIDGET_CONTROL

A number of keywords to the WIDGET_CONTROL procedure affect the behavior of base widgets. In addition to those keywords that affect all widgets, the following are particularly useful: CONTEXT_EVENTS, KBRD_FOCUS_EVENTS, TLB_ICONIFY_EVENTS, TLB_MOVE_EVENTS, TLB_SIZE_EVENTS.

Keywords to WIDGET_INFO

A number of keywords to the WIDGET_INFO function return information that applies specifically to base widgets. In addition to those keywords that apply to all widgets, the following are particularly useful: CONTEXT_EVENTS, KBRD_FOCUS_EVENTS, MODAL, STRING_SIZE, TLB_ICONIFY_EVENTS, TLB_KILL_REQUEST_EVENTS, SCR_YSIZE, TLB_SIZE_EVENTS.

Events Returned by Base Widgets

Base widgets do not generate any events by default. They can be configured to generate events when the base widget receives the keyboard focus or the user clicks the right-hand mouse button. In addition, top-level bases can be configured to generate events when the base is resized, moved, iconified, or killed.

Resize Events

Top-level widget bases return the following event structure only when they are resized by the user and the base was created with the TLB_SIZE_EVENTS keyword set:

{ WIDGET_BASE, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L }

ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The X and Y fields return the new width of the base, not including any frame provided by the window manager.

Move Events

Top-level widget bases return the following event structure when the base is moved and the base was created with the TLB_MOVE_EVENTS keyword set:

{ WIDGET_TLB_MOVE, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L }

ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. X and Y are the new location of the top left corner of the base.

Note: On Windows, move events are generated while dragging. On UNIX, move events are generated only on the mouse-up.

Note: If both TLB_SIZE_EVENTS and TLB_MOVE_EVENTS are enabled, a user resize operation that causes the top left corner of the base to move will generate both a move event and a resize event.

Iconify Events

Top-level widget bases return the following event structure when the base is iconified or restored and the base was created with the TLB_ICONIFY_EVENTS keyword set:

{ WIDGET_TLB_ICONIFY, ID:0L, TOP:0L, HANDLER:0L, ICONIFIED:0 }

ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. ICONIFIED is 1 (one) if the user iconified the base and 0 (zero) if the user restored the base.

Keyboard Focus Events

Widget bases return the following event structure when the keyboard focus changes and the base was created with the KBRD_FOCUS_EVENTS keyword set:

{ WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }

ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine. The ENTER field returns 1 (one) if the base is gaining the keyboard focus, or 0 (zero) if the base is losing the keyboard focus.

Kill Request Events

Top-level widget bases return the following event structure only when a user tries to destroy the widget using the window manager and the base was created with the TLB_KILL_REQUEST_EVENTS keyword set:

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

ID is the widget ID of the base generating the event. TOP is the widget ID of the top level widget containing ID. HANDLER contains the widget ID of the widget associated with the handler routine.

Context Menu Events

A base widget created with the CONTEXT_EVENTS keyword set returns the following event structure in response to a right mouse button click:

{WIDGET_CONTEXT, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L,

   ROW:0L, COL:0L}

The first three fields are the standard fields found in every widget event. The X and Y fields give the device coordinates at which the event occurred, measured from the upper left corner of the base widget. The ROW and COL fields return meaningful information for table widgets and values of zero (0) for other widgets.

Additional Information

Exclusive And Non-Exclusive Bases

If the EXCLUSIVE or NONEXCLUSIVE keywords are specified, the base only allows button widget children.

Positioning Child Widgets Within a Base

The standard base widget does not impose any placement constraints on its child widgets. Children of a “bulletin board” base (a base that was created without setting the COLUMN or ROW keywords) have an offset of (0,0) unless an offset is explicitly specified via the XOFFSET or YOFFSET keywords. This means that if you do not specify any of COLUMN, ROW, XOFFSET, or YOFFSET keywords, child widgets will be placed one on top of the other in the upper left corner of the base.

However, laying out widgets using the XSIZE, YSIZE, XOFFSET, and YOFFSET keywords can be both tedious and error-prone. Also, to have the widget application to display properly on different platforms, use the COLUMN and ROW keywords to influence child widget layouts instead of explicitly formatting your interfaces.

When the ROW or COLUMN keywords are specified, the base decides how to lay out its children, and any XOFFSET and YOFFSET keywords specified for such children are ignored.

Positioning Top-Level Bases

Top-level bases are a special class of base widget created without a parent widget ID. Every widget hierarchy has exactly one top-level base. (Multiple widget hierarchies, represented by their top-level bases, can be organized into an application hierarchy by specifying the GROUP_LEADER keyword. (See Using Multiple Widget Hierarchies for additional discussion of widget applications with multiple widget hierarchies.)

When locating a new top level window, some window managers ignore the program’s positioning requests and either choose a position or allow the user to choose. In such cases, the XOFFSET and YOFFSET keywords to WIDGET_BASE will not have an effect. The window manager may provide a way to disable this positioning style. The Motif window manager (mwm) can be told to honor positioning requests by placing the following lines in your .Xdefaults file:

Mwm*clientAutoPlace: False

Mwm*interactivePlacement: False

Top-Level Base Positioning in Multi-Monitor Situations

In multi-monitor environments you can place your widget on any desired monitor. To do this, use the XOFFSET and YOFFSET keywords to WIDGET_BASE to position the widget on the desired monitor. If the monitors are configured as an extended desktop, XOFFSET and YOFFSET will be sufficient for locating the widget base on any monitor. In X Multi-Screen environments, you must also use the DISPLAY_NAME keyword to select the desired monitor. For more details, see IDLsysMonitorInfo.

If position is not specified, the top-level base widget is placed at [0,0] on the primary monitor.

If a position is specified that does not exist on any available monitor, or if a position selected would cause the widget to be partly off-screen, the widget will be positioned so that it is completely on the monitor that is closest to the specified position.

To move a widget off-screen, use the WIDGET_CONTROL function.

Note: Direct Graphics draw widgets cannot be used on the non-default DISPLAY in the X Multi-Screen environment.

Iconizing, Layering, and Destroying Groups of Top-Level Bases

Group membership (defined via the GROUP_LEADER keyword) controls the way top-level base widgets are iconized, layered, and destroyed.

Note: A group can contain sub-groups. Group behavior affects all members of a group and its sub-groups. For example, suppose we create three top-level base widgets with the following group hierarchy:

base1 = WIDGET_BASE()

base2 = WIDGET_BASE(GROUP_LEADER=base1)

base3 = WIDGET_BASE(GROUP_LEADER=base2)

Effectively, two groups are created. One group has base2 as its leader and base3 as its member. The other group has base1 as its leader and both base2 and base3 as members. If base1 is iconized, both base2 and base3 are iconized as well. If base2 is iconized, base3 is iconized but base1 is not.

Widgets behave slightly differently when displayed on different platforms, and depending on whether they are floating or modal bases. The following rules apply to groups of widgets within a group leader/member hierarchy. Widgets that do not belong to the same group hierarchy cannot influence each other.

Iconization and Mapping

Bases and groups of bases can be iconized (or minimized) by clicking the system minimize control. Bases and groups of bases can also be mapped (made visible) and unmapped (made invisible).

Mapping or unmapping a group leader has no effect on the mapped state of the group members. Iconifying or mapping a group member has no effect on the group leader. Modal bases cannot be unmapped.

Bases and groups of bases can be iconized (or minimized) by clicking the system minimize control. When a group leader is iconized, all members of the group are iconized as well. Similarly, when a group leader is restored, all members of the group are restored.

Layering

Layering is the process by which groups of widgets seem to share the same plane on the display screen. Within a layer on the screen, widgets have a Z-order, or front-to-back order, that defines which widgets appear to be on top of other widgets.

Motif

All elements on the screen—widgets, the workbench, other Motif applications—share a single layer and have an arbitrary Z-order. There is no special layering of IDL widgets.

Windows

All non-floating and non-modal widgets within a group hierarchy share the same layer—that is, when one group member has the input focus, all members of the group hierarchy are displayed in a layer that appears in front of all other groups or applications. Within the layer, the widgets can have an arbitrary Z-order.

Widgets that are floating or modal always float above their group leaders.

Destruction

When a group leader widget is destroyed, either programmatically or by clicking on the system “close” button, all members of the group and all sub-groups are destroyed as well.

If a modal base is on the display, it must be dismissed before any widget can be destroyed.

Version History

Pre-4.0	Introduced
5.6	Added TLB_ICONIFY_EVENTS, TLB_MOVE_EVENTS, and TOOLBAR keywords; added new event structures for iconify and move events
6.1	Added TAB_MODE keyword Added ROW and COL fields to WIDGET_CONTEXT event structure
6.2	Deprecated APP_MBAR keyword
6.4	Added BITMAP and MASK keywords
8.3	Added TLB_RESIZE_NODRAW keyword

Product	IDL

Version	9.0