Language > Widgets > Creating Widget Applications > Example: A Simple Widget Application

# Example: 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.

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. 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 `doc_widget1` procedure.

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