Designing a Simple Widget

The first part of widget programming is understanding widget design. The foundation of a widget program is a base widget known as the top-level base (TLB). All other widgets exist within the TLB widget, which can also control the other widgets. For example, when you close (destroy) the TLB widget, all the dependent widgets are also closed.

The following program shows you how to create the window shown above. This basic code creates only the widget elements. None of the features will be functional until you add the event handlers to define the widget actions.

Note
The best way to learn from this tutorial is to open a new file in IDL, then copy and paste the code into the new file. As you go through each section, copy and paste the code at the appropriate places.

You can also find the entire routine (draw_basic_doc.pro) in the examples\doc\widgets subfolder of your IDL distribution. Open the routine by typing in the following command (or simply click on the following link):
.edit draw_basic_doc.pro

; The main routine that defines the widgets. 
PRO basic_draw_doc 
 
  ; Create the top-level base (TLB) widget. 
  ; The base variable contains the widget id of the 
  ; base widget, which will contain all the other widgets. 
  ; The WIDGET_BASE routine uses the COLUMN keyword to layout 
  ; the widgets in a column orientation. 
  ; The TLB_SIZE_EVENTS keyword tells the widget 
  ; to return resize events. 
  base = WIDGET_BASE(COLUMN=1, TITLE='Widget Example', $ 
    TLB_SIZE_EVENTS=1, xpad=0, ypad=0, /ALIGN_CENTER) 
     
  ; Create the draw widget with a size of 200x200 pixels. 
  draw = WIDGET_DRAW(base, XSize=200, YSize=200) 
   
  ; Create the base widget that contains the 
  ; label, droplist and button widgets. 
  base2 = WIDGET_BASE(base, Column=1, $ 
    xpad=0, ypad=5, /ALIGN_CENTER) 
   
  ; Create a variable containing the values 
  ; to choose from in the droplist widget. 
  select = ['Thorax', 'Head', 'Head and neck'] 
   
  ; Create a label for the droplist. 
  label = WIDGET_LABEL(base2, VALUE='Select an image:') 
   
  ; Create a droplist widget to select an image. 
  ; The values are the items listed in droplist, 
  ; defined above by the select variable. 
  drop = WIDGET_DROPLIST(base2, VALUE=select) 
     
  ; Create some space between the dropdown list and the button. 
  space = WIDGET_BASE(base2, XSIZE=30) 
   
  ; Create a done button to cancel the window 
  button = WIDGET_BUTTON(base2, VALUE='Done', $ 
    UVALUE='done') 
 
  ; Use WIDGET_INFO to determine the size of base2 
  ; so that we can subtract that size from the 
  ; base widget when it is resized. 
  base2Geom = Widget_Info(base2, /Geometry) 
  base2_ysize = base2Geom.ysize 
   
  ; Realize the widgets.  
  WIDGET_CONTROL, base, /Realize 
   
  ; Create a variable containing an image to display. 
  READ_JPEG, FILEPATH('pdthorax124.jpg', $ 
    SUBDIR=['examples', 'data']), image 
 
  ; Retrieve the window ID from the draw widget. 
  WIDGET_CONTROL, draw, GET_VALUE=drawID 
   
  ; Define the widget in which to display the image. 
  WSET, drawID 
   
  ; Display the data. 
  TVSCL, CONGRID(image, 200, 200, /CENTER) 
   
END

Now that you have the primary program written, you can compile and run it. In the IDL Workbench, click the Compile icon and then the Run icon, as shown below:

The Widget Example window displays:

This small program is just the start of building a widget; it is just the shell, and does not do anything yet.

Note
Close the widget example by clicking the close (X) button at the top of the window. The Done button will not work until we add that event handler in Creating the Done Button Event Handler.

In the next sections you will add the functionality for the dropdown list and button using event handlers. You will also learn about state structures and pointers, which you will need to make the widget work correctly.

Tip
See Widget Programming Concepts for more information on widget design and functionality. See Widget User Values to learn about event handling with user values (UVALUE).