When you create and use a widget application, you do the following things:

  1. Construct the Widget Hierarchy
  2. Provide an Event-Handling Routine
  3. Realize the Widgets
  4. Register the Program with the XMANAGER
  5. Interact with the Application
  6. Destroy the Widgets

Construct the Widget Hierarchy

You must first build a widget hierarchy using the WIDGET_* functions. Start by creating a top-level base with the WIDGET_BASE function.

Combine other widget creation functions (WIDGET_BUTTON, CW_PDMENU, etc.) to create and organize the user interface of your widget application. At this point, the widgets are unrealized; they exist only as IDL widget records, and nothing has been created or displayed on the screen.

Note: Widget applications can include multiple widget hierarchies headed by multiple top-level base widgets. See Using Multiple Widget Hierarchies for more on creating a hierarchy of widget hierarchies.

Provide an Event-Handling Routine

In order for a widget application to do anything, you must provide a routine that examines events, determines what action to take, and implements that action. Actions may involve computation, graphics display, or updates to the widget interface itself.

For best performance, event processing routines must run and return to the calling routine as quickly as possible. Widgets won’t respond to user input while the event-processing routine is running. Widget-based programs should wait for user-generated events, handle them as quickly as possible, and return to wait for more events. Event processing is discussed in detail in Widget Event Processing.

Event handling routines can manipulate widgets via the WIDGET_CONTROL procedure. Possible actions include the following:

  • Obtain or change the value of a widget (see Widget Values) using the APPEND, GET_VALUE, and SET_VALUE keywords.
  • Obtain or change the value of a widget’s user value using the GET_UVALUE and SET_UVALUE keywords. (User values are discussed in Widget User Values)
  • Map and unmap widgets using the MAP keyword. Unmapped widgets are removed from the screen and become invisible, but they still exist in memory.
  • Change a widget’s sensitivity using the SENSITIVE keyword. A widget indicates that it is insensitive by changing its appearance (often by graying itself or displaying text with dashed lines) and ignoring any user input. It is useful to make widgets insensitive at points where it would be inconvenient to get events from them (for example, if your program is waiting for input from another source).
  • Change the settings of toggle buttons using the SET_BUTTON keyword.
  • Push a widget hierarchy behind the other windows on the screen, or pull it in front, using the SHOW keyword.
  • Display the “hourglass” cursor while the application is busy and not able to respond to user actions by setting the HOURGLASS keyword. (See Indicating Time-Consuming Operations.)

Realize the Widgets

To convert the IDL widget records representing your widget hierarchy into a set of platform-specific user interface toolkit elements, use the REALIZE keyword to the WIDGET_CONTROL procedure. Unless you have specifically unmapped the widgets before realizing them, the REALIZE keyword causes the widgets to be displayed on screen. See Manipulating Widgets for additional details.

Register the Program with the XMANAGER

Your widget application waits for events to be reported to it and reacts as specified in the event handling routine after being registered with the XMANAGER procedure.

Events are obtained by XMANAGER via the WIDGET_EVENT function and passed to the calling routine (your event handler) in the form of an IDL structure variable. Each type of widget returns a different type of structure, as described in the documentation for the individual widget creation functions. Every event structure has three common elements: long integers named ID, TOP, and HANDLER:

  • ID is the widget ID of the widget generating the event.
  • TOP is the widget ID of the top-level base containing the widget that generated the event.
  • HANDLER is important for event handler functions, which are discussed later in this section.

When an event occurs, XMANAGER arranges for the event structure to be passed to an event-handling procedure specified by the program, and the event handler takes some appropriate action based on the event. This means that multiple widget applications can run simultaneously; XMANAGER arranges for the events be dispatched to the appropriate routine.

Interact with the Application

Once the widget application has been realized and registered with XMANAGER, the user can interact with the application to accomplish whatever tasks the application is designed to accomplish.

Destroy the Widgets

When the application has finished (usually when the user clicks on a “Done” or “Quit” button), destroy the widget hierarchy using the DESTROY keyword to the WIDGET_CONTROL procedure. This causes all resources related to the hierarchy to be freed and removes it from the screen.