This section discusses some basic ideas and concepts that are central to the process of writing IDL widget applications.
Widget Values
Many widget primitives and compound widgets have widget values associated with them. Depending on the type of widget, the widget value may represent a static item set by the programmer (the label of a button widget, for example) or a dynamic value set by the user (the numerical value of a slider widget, for example).
Widget values are retrieved from a widget using the GET_VALUE keyword to the WIDGET_CONTROL procedure, and set either when the widget is created or using the SET_VALUE keyword to WIDGET_CONTROL. Descriptions of widget value data types and default values are included along with the descriptions of individual widgets in the following sections. (See Manipulating Widgets for details on using WIDGET_CONTROL.)
Widgets can also have user values. A widget’s user value is an IDL variable, and can thus be of any of IDL’s data types. User values can contain any information the programmer wants to include; they are not examined or used by IDL except as specified by the widget application programmer. User values and their role in widget programming are discussed in Widget User Values.
Note: If a widget value is a string (as for a button label), you can use language catalogs to internationalize the widget with sets of strings in particular languages.
Widget IDs
IDL widgets are uniquely identified via theirwidget IDs. The widget ID is a long integer assigned to the widget when it is first created; this integer is returned as the value of the widget creation function. For example, you might create a base widget with the following IDL command:
base = WIDGET_BASE()
Here, the IDL variable base receives the widget ID of the newly-created top-level base widget.
Routines within your widget application that need to retrieve data from widgets or change their appearance need access to the widgets’ IDs. Techniques for passing widget IDs between independent routines in your widget application are discussed in Working With Widget IDs.
Widget Parent/Child Relationships
With one exception (described below), when you create a new widget using one of the WIDGET_* functions, you specify the widget ID of the new widget’s parent widget. This parent-child relationship defines a widget hierarchy.
For example, suppose you have created a base widget whose widget ID is contained in the IDL variable base. The following IDL command creates a button widget that is a child of the base widget whose widget ID is stored in the variable base:
button1 = WIDGET_BUTTON(base, VALUE='Test button')
In addition to being below base in the widget hierarchy, button1 appears inside base when the base widget is realized on the screen.
The exception to this parent-child rule is a special instance of a base widget called a top-level base. A top-level base is different from an “ordinary” base widget in the following ways:
- It does not have a parent widget
- It serves as the top of a widget hierarchy
- Its widget ID is included in the TOP field of every widget event structure generated by other widgets in its hierarchy
In practice, a widget application always begins with a top-level base. The fact that the widget ID of the top-level base widget is always available in the event structure of widget events is very useful for managing the state of a widget application. This topic is discussed in depth in Managing Application State.
Instantiating and Displaying Widgets
When you call a routine that creates a widget, IDL “creates” the widget and assigns it a unique identifier (the widget ID). For example, the following IDL statements create a base widget that holds a button widget, and stores the widgets’ identifiers in the variables base and button:
base = WIDGET_BASE()
button = WIDGET_BUTTON(base, VALUE='My Button')
At this point, the widgets are nothing more than data structures (referred to as widget records) in IDL’s memory. Nothing appears on screen, and in fact IDL has yet to calculate the sizes of the widgets or the way they will appear.
To instantiate the widget (to create the final form of the widget that will be displayed from components supplied by the platform-specific user interface toolkit and (in most cases) make it appear on screen) the widgets must be realized. Realization occurs with a call to the WIDGET_CONTROL procedure, using the REALIZE keyword:
WIDGET_CONTROL, base, /REALIZE
After this command has been issued, the widgets appear on the computer screen. (See Manipulating Widgets for details on using WIDGET_CONTROL.) Between the time when the widget is created as an IDL widget record and when it is realized as a platform-specific interface element, you have control over many, but not all, aspects of the widget’s state. Some details of the final realized widget’s state (such as its exact screen geometry) may remain undetermined until the widget is instantiated. Realization, and the related concepts of mapping and sensitivity, are discussed in greater in following sections.
It is important to note that unrealized widgets in a widget hierarchy can be manipulated programmatically. Examples of attributes you can manipulate before realization are the overall geometry of the user interface, widget values, and user values. You can even retrieve widget values before the widgets are realized. Unrealized widgets do not, however, generate widget events, since the actual platform-specific user interface has yet to be created.
Once a widget has been realized, its corresponding platform-specific user interface toolkit element is instantiated. The native toolkit determines the widget’s exact screen geometry. If the widget is then mapped, it becomes visible on the computer screen, can be manipulated by a user, and generates widget events.
Note: Widgets are mapped by default. This means that when you realize a widget hierarchy, the widgets included in that hierarchy will usually be displayed on screen immediately. You can control the visibility of widget hierarchies, before or after realization, using the MAP keyword to WIDGET_CONTROL. See Controlling Widget Visibility for details.
Note also that widgets that are visible on screen can be made unavailable to the user by setting the SENSITIVE keyword to WIDGET_CONTROL. See Sensitizing Widgetsfor details.