Example 1: A Simple Widget Application

Example 1: A Simple Widget Application

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, don't be dismayed if parts of this example are not immediately clear to you. As you read further through this chapter, the principles of the event-driven programming model and IDL's specific implementation of that model will become clearer.

Note

This example is included in the file widget1.pro in the examples/widgets subdirectory of the IDL distribution. You can either open the file in an IDL editor window and compile and run the code using items on the Run menu, or simply enter

   widget1

at the IDL command prompt. See Running the Example Code if IDL does not run the program as expected.

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

While this simple example does nothing particularly useful, it does illustrate some basic concepts of event-driven programming. Let's examine how the example is constructed.

First, note that the "application" consists of two parts: an event handling routine and a creation routine. Let's first examine the second part - the creation routine - contained in the widget1 procedure.

The widget1 procedure does the following:

Creates a top-level base widget whose widget ID is stored in the variable base. All widget applications have at least one base.

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.

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.

Invokes the XMANAGER routine to manage the widget event loop, providing the name of the calling routine (widget1) and the widget ID of the top-level base on which the widget hierarchy is built (base).

The 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 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 in the IDL Reference Guide.