The following example demonstrates the simplicity of widget programming. The example program creates a base widget containing a single button, labelled “Done.” When you position the mouse cursor over the button and click, the widget is destroyed.

Note: If you are new to IDL widget programming, some parts of this example may not be immediately clear to you. As you read further through this section, the principles of the event-driven programming model and IDL’s specific implementation of that model will become clearer.

This example is included in the file doc_widget1.pro in the examples/doc/widgets subdirectory of the IDL distribution. Run this example procedure by entering doc_widget1 at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT doc_widget1.pro. See Running the Example Code if IDL does not run the program as expected.

PRO doc_widget1_event, ev
  IF ev.SELECT THEN WIDGET_CONTROL, ev.TOP, /DESTROY
END
 
PRO doc_widget1
  base = WIDGET_BASE(/COLUMN)
  button = WIDGET_BUTTON(base, value='Done')
  WIDGET_CONTROL, base, /REALIZE
  XMANAGER, 'doc_widget1', base
END

While this simple example does nothing particularly useful, it does illustrate some basic concepts of event-driven programming. The following examines how the example is constructed.

The “application” consists of two parts: an event handling routine and a creation routine.

The creation routine in the doc_widget1 procedure does the following:

  1. Creates a top-level base widget whose widget ID is stored in the variable base. All widget applications have at least one base.
  2. Creates a button widget whose widget ID is stored in the variable button. The button widget has base as its parent. The value “Done” is assigned to the button. The value of a button widget is the text that appears on the button’s face.
  3. Realizes the widget hierarchy built on base by calling WIDGET_CONTROL with the /REALIZE keyword. Realizing the widget hierarchy displays the widget on your computer screen.
  4. Invokes the XMANAGER routine to manage the widget event loop, providing the name of the calling routine (doc_widget1) and the widget ID of the top-level base on which the widget hierarchy is built (base).

The doc_widget1_event procedure is the event handling routine for the application. By convention, the XMANAGER procedure looks for an event handling procedure with the same name as the procedure that creates the widgets, with “_event” appended to the end. (This default can be overridden by specifying an event handler directly using the EVENT_HANDLER keyword to XMANAGER.) When an event is received by XMANAGER, the event structure is passed to the doc_widget1_event procedure via the ev argument.

In this example, all the event handling routine does is check the event structure to see if the event passed to it was a select event generated by the button widget. If a SELECT event is received, the routine calls WIDGET_CONTROL with the DESTROY keyword to destroy the widget hierarchy built on the top-level base widget (specified in the TOP field of the event structure).

For further discussion of widget events and event structures, see Widget Event Processing. For details about the event structures returned by different widgets, see the documentation for each widget.