Common Widget Properties

There are several attribute and event property values you can set for all widgets. The attribute properties include the name of the widget and the sizing properties. The event properties include creation, realization, destruction, and tracking events.

Common Attributes

Common Events

Common Attributes

Name

The Name attribute specifies the name of the component. This value can be any string that is unique to the widget hierarchy of the interface, but the string cannot contain spaces. For each widget you create in the IDL GUIBuilder, a default name is supplied, and this name is in the WID_<TYPE>_<NUMBER> format.

If you copy and paste a widget in the IDL GUIBuilder, the new widget is given a unique name based on the name of the one you copied. A number is added to the first widget's name, or an existing number is incremented.

You can use the Name value for the widget in your event callback routines. For example, you can use the specified name to find the widget, using the FIND_BY_UNAME keyword to the WIDGET_INFO function. Set the name for each widget to a name that makes sense to you; set the name value to something that is easy to remember and easy to use in your code.

In the generated *.pro file, this value is specified with the UNAME keyword to the widget creation routines.

Component Sizing

The Component Sizing keyword determines how the component is sized, which is by one of the following methods:

Default: The widget is sized to a natural or implicit size. This is the default setting for the attribute. For example, a label widget's natural size is determined by the size of the text it is displaying with extra space for margins. The default size for each widgets is controlled by several things, including displayed font size and the characteristics of the operating system displaying the interface.

Explicit: The widget size is determined by several attributes, which include Layout for the base and its own X Size and Y Size keywords.

In the generated *.pro widget file, this value is specified with the XSIZE and YSIZE keywords to the widget creation routines.

Frame

The Frame attribute determines if the widget will have a frame or border around it. These are the possible values:

False: The widget will have no frame drawn around it. This is the default value.

True: The widget will have a frame or border around it.

In the generated *.pro widget file, this value is specified by the FRAME keyword to the widget creation routines.

Sensitive

The Sensitive attribute determines if the selected widget is active or not active on startup. You can set this value to determine if the user can access and manipulate the widget immediately after creation. These are the possible values:

True: The widget is initially displayed as enabled and accepts keyboard or mouse input and generates events. This is the default value.

False: The widget is initially displayed as disabled and does not accept keyboard or mouse input. The appearance of most widgets change when the False value is set, but the appearance does not always change to indicate this state.

In the generated *.pro file, this value is specified with the SENSITIVE keyword to the widget creation routines.

X Offset

The X Offset attribute specifies the X offset of the component from its parent. The possible values for X Offset are o to n, in pixels; any number is valid. The Y Offset attribute specifies the Y offset.

In the generated *.pro file, this value is specified with the XOFFSET keyword to the widget creation routines.

X Size

The X Size attribute specifies the width of the visible component in pixels. This attribute is disabled when Component Sizing is set to Default (and the default size is used). To enable this value, set Component Sizing to Explicit. The possible values for X Size are 0 to n, in pixels.

In the generated *.pro file, this value is specified with the SCR_XSIZE keyword to the widget creation routines.

Y Offset

The Y Offset attribute specifies the Y offset of the component from its parent in pixels. The possible values for Y Offset are 0 to n, in pixels; any number is valid. The X Offset attribute specifies the X offset.

In the generated *.pro file, this value is specified by the YOFFSET keyword to the widget creation routines.

Y Size

The Y Size attribute specifies the height of the visible component in pixels. This attribute is disabled when Component Sizing is set to Default (and the default size is used). To enable this value, set Component Sizing to Explicit. The possible values for Y Size are 0 to n, in pixels.

In the generated *.pro file, this value is specified with the SCR_YSIZE keyword to the widget creation routines.

Common Events

The following events are common to all widgets (by default, no event values are set):

Handle Event

The Handle Event value is the function name that is called when an event arrives from a widget that is rooted in an IDL GUIBuilder-created widget in the hierarchy. All events are sent to this event function, except for creation and destruction events.

For example, if you add a compound widget to an interface, using the PostCreation event procedure for a base widget, you should set the Handle Event value for that parent base widget (for the compound widget's parent widget). Then, you can handle all the events returned by the compound widget using this event function value.

In the generated *_eventcb.pro file, the event function place holder looks like this:

Function <Name>, Event 
 
   return, Event 
End

where Name is the name of the event function you specify. Event is the returned event structure, which is specific to the widget event.

For an example of how to handle the generated Handle Event function, see Adding Compound Widgets.

OnDestroy

The OnDestroy value is the routine name that is called when the widget is destroyed. In the generated *_eventcb.pro file, the event calling sequence looks like this:

pro <RoutineName>, wWidget

where RoutineName is the name of the event procedure you specify. wWidget is the IDL widget identifier.

OnRealize

The OnRealize value is the routine name that is called automatically when the widget is realized. In the generated *_eventcb.pro file, the event calling sequence looks like this:

pro <RoutineName>, wWidget

where RoutineName is the name of the event procedure you specify. wWidget is the IDL widget identifier.

OnTimer

The OnTimer value is the routine name that is called when a timer event is detected for a 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, which has the 3 standard event tags and looks like this:

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

You must set timer events for a widget, using the WIDGET_CONTROL function. The code generated by the IDL GUIBuilder only routes the events.

OnTracking

The OnTracking value is the routine name that is called when the widget receives a tracking event, which occurs when the mouse pointer enters or leaves the region of the 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 structure, which is of the following type:

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

ENTER is 1 if the tracking event is an entry event, and 0 if it is an exit event.

PostCreation

The PostCreation value is the routine name that is called after the widget is created, but before it is realized. In the generated *_eventcb.pro file, the calling sequence looks like this:

pro <RoutineName>, wWidget

where RoutineName is the name of the event procedure you specify. wWidget is the IDL widget identifier.