|
|
IDL Reference Guide: IDL GUIBuilder Widget Reference |
|
A base widget holds other widgets, including other base widgets. You can create groupings of widgets by using a base widget, thus forming a widget hierarchy.
When you open the IDL GUIBuilder, a top-level base is created, and you build your interface in this base. Top-level bases are a special class of the base widgets that are created without parent widgets; they act as the top-level parent in the widget hierarchy.
In addition, you can make top-level bases float above their group leaders, with the Floating attribute, or you can make them modal dialogs, with the Modal attribute. Modal dialogs interrupt program execution until the user closes them. When you make a top-level base floating or modal, you must provide a group leader when calling the generated code, by using the GROUP_LEADER keyword.
When programming in IDL, you create base widgets using the WIDGET_BASE function. For more information, see WIDGET_BASE.
In the IDL GUIBuilder, you can add a menubar to the top-level base by using the Menu Editor. For more information on the Menu Editor, see Using the Menu Editor.
| Note A base widget's layout is controlled by where you place it and the properties of its parent base. |
For base widgets, you can set common attributes and base-specific attributes. For a list attributes common to all widgets, see Common Attributes.
Some of the base widget attributes apply to top-level bases only, and this limitation is noted in the following list of base widget attributes:
The # of Rows/Columns attribute specifies the number of Columns or Rows to use when laying out the base. This attribute is valid only when the Layout attribute is set to Column or Row. The possible values for this setting are 1 to n, and the default value is 1.
In the generated *.pro file, this value is specified with the COLUMN or the ROW keyword to the widget creation routine.
For information on other properties that control the layout of contained widgets, see Alignment, Layout, Space, X Pad, and Y Pad.
The Alignment attribute defines how components are aligned in the base. The way in which the value of this attribute affects the display of widgets depends on the value of the Layout attribute. The following is a list possible values for the Alignment attribute, and each value description includes information on how it works with the Layout settings:
In the generated *.pro file, these settings are specified with the BASE_ALIGN_CENTER, BASE_ALIGN_TOP, BASE_ALIGN_BOTTOM, BASE_ALIGN_LEFT, and BASE_ALIGN_RIGHT keywords to the widget creation routine.
For information on other properties that control the layout of contained widgets, see # of Rows/Columns, Layout, Space, X Pad, and Y Pad.
The Allow Closing attribute determines if the top-level base can be closed by the user. By default, this value is set to True and the base can be closed. To make it so the top-level base cannot be close, set this value to False.
In the generated *.pro file, this value is specified with the TLB_FRAME_ATTR keyword to the widget creation routine.
For information on other properties that control aspects of top-level bases, see the Allow Moving, Minimize/Maximize, System Menu, and Title Bar properties.
| Note This attribute setting is used with top-level bases only. Note that this setting is only a hint to the window system and might be ignored by some window managers. |
The Allow Moving attribute determines if the base can be moved. By default, this value is set to True, and the base can be moved. To suppress this behavior, set this value to False.
In the generated *.pro file, this value is specified with the TLB_FRAME_ATTR keyword to the widget creation routine.
For information on other attribute settings that control aspects of top-level bases, see the Allow Closing, Minimize/Maximize, System Menu, and Title Bar attributes.
| Note This attribute setting is used with top-level bases only. Note that this setting is only a hint to the window system and might be ignored by some window managers. |
The Floating attribute determines if the top-level base is a floating base (always on top). By default, this setting is False, indicating that the base is not a floating base. To create a floating base, set this attribute to True.
If you make a top-level base floating, you must set the GROUP_LEADER keyword to a valid widget ID when calling the generated procedure.
In the generated *.pro file, this value is specified with the FLOATING keyword to the widget creation routine.
| Note This attribute setting is used with top-level bases only. |
The Grid Layout attribute determines if the base will have a grid layout, in which all columns have the same width, or in which all rows have the same height. These are the possible values:
In the generated *.pro file, this value is specified with the GRID_LAYOUT keyword to the widget creation routine.
The Layout attribute specifies how components are laid out in the base. These are the possible values:
| Note When using code generated by the IDL GUIBuilder on other non-Windows platforms, more consistent results are obtained by using a row or column layout for your bases instead of a bulletin board layout. By using a row or column layout, differences in the default spacing and decorations (e.g., beveling) of widgets on each platform can be avoided |
The number of child widgets placed in each column or row is calculated by dividing the number of created child widgets by the number of columns or rows specified (# of Rows/Columns). When one column or row is filled, a new one is started.
The width of each column or the height of the row is determined by the largest widget in that column or row. If you set the Grid Layout attribute to True, all columns or rows are the same size; they are the size of the largest widget.
If you set the Alignment attribute for the base, the contained widgets are their "natural" size. If you do not set the Alignment attribute for the base or the child widgets, all contained widgets will be sized to the width of the column or the height of the row.
For information on other properties that control the layout of contained widgets, see # of Rows/Columns, Alignment, Space, X Pad, and Y Pad.
In the generated *.pro file, this value is specified with the COLUMN or the ROW keyword to the widget creation routine.
| Note When you create a radio button or checkbox, it is created in a base, and you can add more radio buttons or checkboxes to that base (the added widgets must all be of the same type). The base in which radio buttons and checkboxes are created has a column layout setting, and buttons you add will be lined up in a column format. |
The Minimize/Maximize attribute determines if the top-level base can be resized, minimized, and maximized. By default, this value is set to True. To disable this behavior, set this attribute to False.
In the generated *.pro file, this value is specified with the TLB_FRAME_ATTR keyword to the widget creation routine.
For information on other attribute settings that control aspects of top-level bases, see the Allow Closing, Allow Moving, System Menu, and Title Bar attributes.
| Note This attribute setting is used with top-level bases only. Note that this setting is only a hint to the window system and might be ignored by some window managers. |
The Modal attribute determines if this top-level base is a modal dialog. By default, this value is set to False. To make the base a modal dialog, set this attribute to True.
If you set the Modal attribute to True, you cannot set the Scroll attribute, and you cannot define a menu for the top-level base. In addition, the Sensitive common attribute and the Visible base widget attribute are also disabled.
If you make a top-level base a modal dialog, you must set the GROUP_LEADER keyword to a valid widget ID in the generated procedure.
In the generated *.pro file, this value is specified with the MODAL keyword to the widget creation routine.
| Note This attribute setting is used with top-level bases only. |
The Scroll attribute determines if the base widget will support scrolling. By default, this attribute is set to False, and the base will not support scrolling. To give the widget scroll bars and allow for viewing portions of the widget contents that are not currently in the viewport area, set the Scroll attribute to True. In the IDL GUIBuilder, scroll bars on bases are live so that you can work on the entire virtual area of your application.
If you set the Modal attribute to True, you cannot set the Scroll attribute.
In the generated *.pro file, this value is specified with the SCROLL keyword to the widget creation routine.
To set the size of the scrollable region, use the X Scroll and Y Scroll attributes.
The Space attribute specifies the number of pixels between the contained widgets (the children) in a column or row Layout. By default, this value is set to 3 pixels and that is the space between the contained widgets. Valid values for this attribute are 0 to n pixels.
In the generated *.pro file, this value is specified with the SPACE keyword to the widget creation routine.
To set the space from the edge of the base, use the X Pad and Y Pad properties. For information on other properties that control the layout of contained widgets, see # of Rows/Columns, Alignment, and Layout.
| Note You cannot set this attribute on a base containing radio buttons or checkboxes. |
The System Menu attribute determines if the system menu is displayed or suppressed on a top-level base. By default, this value is set to True, indicating that the system menu will be used. To suppress the menu, set this attribute to False.
In the generated *.pro file, this value is specified with the TLB_FRAME_ATTR keyword to the widget creation routine.
For information on other attribute settings that control aspects of top-level bases, see the Allow Closing, Allow Moving, Minimize/Maximize, and Title Bar attributes.
| Note This attribute setting is used with top-level bases only. |
The Tab Mode attribute specifies what support the base has for receiving or losing focus through tabbing. By default, this value is set to None for a top level base, and to Inherit for subsequent bases.
| Note It is not possible to tab to disabled (Sensitive = False) or hidden (Visible = False) widgets. |
Allowable values are:
| Note The default tab mode of lower level bases and widgets is Inherit. The tabbing support defined for a top level or parent base is inherited by widget children unless otherwise specified. |
| 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. |
In the generated *.pro file, this value is specified with the TAB_MODE keyword to the widget creation routine. For more information on tabbing among widgets, see Tabbing in Widget Applications.
The Title attribute specifies the title of a top-level base. By default, this value is set to IDL, but you can change it to any string.
In the generated *.pro file, this value is specified with the TITLE keyword to the widget creation routine.
| Note This attribute setting is used with top-level bases only. |
The Title Bar attribute determines if the title bar will be displayed. By default, this value is set to True, and the title bar is displayed. To suppress the display of the title bar, set this value to False.
In the generated *.pro file, this value is specified with the TLB_FRAME_ATTR keyword to the widget creation routine.
For information on other attribute settings that control aspects of top-level bases, see the Allow Closing, Allow Moving, Minimize/Maximize, and System Menu attributes.
| Note This attribute setting is used with top-level bases only. Note that this setting is only a hint to the window system and might be ignored by some window managers. |
The Visible attribute specifies whether to show or hide the base component and its descendants. Show, the default value, specifies to display the hierarchy when realized. The Hide value specifies that the hierarchy should not be displayed initially. This mapping operation applies only to base widgets.
In the generated *.pro file, this value is specified with the MAP keyword to the widget creation routine.
| Note If you set the Modal attribute to True, you cannot set the Visible attribute value. |
The X Pad attribute specifies the horizontal space (in pixels) between child widgets and the edges of rows or columns. By default, this value is set to 3 pixels, indicating that there are 3 pixels between the edge of the base and the contained widgets. Valid values for this attribute are 0 to n pixels.
In the generated *.pro file, this value is specified with the XPAD keyword to the widget creation routine.
To set the space between widgets, use the Space attribute. For information on other attributes that control the layout of contained widgets, see # of Rows/Columns, Alignment, Layout, and Y Pad.
| Note You cannot set this attribute for a base that contains radio buttons or checkboxes. In the IDL GUIBuilder, a base is created when you add a radio button or checkbox to an interface, and you can add more radio buttons or checkboxes to that base. When you add the buttons, they are lined up in a column format. |
The X Scroll attribute specifies the width in pixels of the base area, which includes the exposed as well as the virtual area. There is no default value set, but you can set this value to any number of pixels from 0 to n. To add scroll bars to the base, use the Scroll attribute, and to set the height of the scrollable base area, use the Y Scroll attribute.
In the generated *.pro file, this value is specified with the XSIZE keyword to the widget creation routine.
| Note To set the width of the displayed widget, use the X Size common attribute. |
The Y Pad attribute specifies the vertical space (in pixels) between child components and the edge of the base in a row or column Layout. By default, this value is set to 3 pixels, indicating that there are 3 pixels between the edge of the base and the contained widgets. Valid values for this attribute are 0 to n pixels.
In the generated *.pro file, this value is specified with the YPAD keyword to the widget creation routine.
To set the space between widgets, use the Space attribute. For information on other attributes that control the layout of contained widgets, see # of Rows/Columns, Alignment, Layout, and X Pad.
| Note You cannot set this attribute on a base containing radio buttons or checkboxes. In the IDL GUIBuilder, a base is created when you add a radio button or checkbox to an interface, and you can add more radio buttons or checkboxes to that base. |
The Y Scroll attribute specifies the height in pixels of the base area, which includes the exposed as well as the virtual area. There is no default value set, but you can set this value to any number of pixels from 0 to n.
To add scroll bars to the base, use the Scroll attribute, and to set the width of the base area, use the X Scroll attribute.
In the generated *.pro file, this value is specified with the YSIZE keyword to the widget creation routine.
| Note To set the height of the displayed widget, use the Y Size common attribute. |
For base widgets, you can set common event properties and base-specific event properties. By default, event values are not set. For a list of events common to all widgets, see Common Events.
The following is a list of event properties specific to base widgets:
The OnContextEvent value is the routine name that is called when the user clicks the right-hand mouse button over the base widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the returned event structure returned when the user clicks the right-hand mouse button and is of the following type:
{WIDGET_CONTEXT, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L}
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 OnFocus value is the routine name that is called when the keyboard focus of the base changes. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when the keyboard focus changes and is of the following type:
{ WIDGET_KBRD_FOCUS, ID:0L, TOP:0L, HANDLER:0L, ENTER:0 }
ENTER returns 1 if the base is gaining the keyboard focus, and returns 0 if the base is losing the keyboard focus.
The OnIconify value is the routine that is called when the user iconifies or restores the top-level base widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a user iconifies or restores the widget using the window manager and is of the following type:
{ WIDGET_TLB_ICONIFY, ID:0L, TOP:0L, HANDLER:0L, ICONIFIED:0 }
ICONIFIED is 1 (one) if the user iconified the base and 0 (zero) if the user restored the base.
| Note This event procedure is valid for top-level bases only. |
The OnKillRequest value is the routine that is called when the user attempts to kill the top-level base widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a user tries to destroy the widget using the window manager and is of the following type:
{ WIDGET_KILL_REQUEST, ID:0L, TOP:0L, HANDLER:0L }
Note that this event structure contains the standard three fields that all widgets contain.
| Note This event procedure is valid for top-level bases only. |
The OnMove value is the routine that is called when the user moves the top-level base widget. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when a user moves the widget and is of the following type:
{ WIDGET_TLB_MOVE, ID:0L, TOP:0L, HANDLER:0L, X:0L, Y:0L }
X and Y are the new location of the top left corner of the base.
| Note This event procedure is valid for top-level bases only. |
The OnSizeChange value is the name of the routine that is called when the top-level base has been resize. In the generated *_eventcb.pro file, the event calling sequence looks like this:
pro <RoutineName>, Event
where RoutineName is the name of the event procedure you specify. Event is the event structure returned when the top-level base is resized by the user and is of the following type:
{ WIDGET_BASE, ID:0L, TOP:0L, HANDLER:0L, X:0, Y:0 }
The X and Y fields return the new width of the base, not including any frame provided by the window manager.
| Note This event procedure is valid for top-level bases only. |
IDL Online Help (March 06, 2007)