Previous Getting Started with IDL: Creating Interfaces with the IDL GUIBuilder Next

Creating an Example Application

This simple example application contains a menu and a draw widget. When complete, the running application allows the user to open and display a graphics file in PNG format, change the color table for the image display, and perform a smooth operation on the displayed image.

The following example shows in various steps how to create a widget, set widget properties, and write IDL code to handle events:

Defining Menus for the Top-Level Base

To define the menu, follow these steps:

  1. Open a new IDL GUIBuilder window by selecting File New GUI from the IDLDE menu, or click the "New GUI" button on the IDLDE toolbar.

    2.  

  2. Drag out the window so that the top-level base to a reasonable size for displaying an image.

    3.  

    To view the property values, right-click on the base, and choose Properties from menu. In the Properties dialog, scroll down to view the X Size and Y Size property values.

     

  3. Right-click on the top-level base in the IDL GUIBuilder window, then choose Edit Menu. This action opens the Menu Editor.

    4.  

  4. In the Editor's Menu Caption field, enter "File" and click Insert. Clicking Insert sets the entered value and adds a new line after the currently selected line, and the new line becomes the selected line.

    5.  

  5. To define the File menu items:
    • With the new line selected, click on the right arrow in the Menu Editor, which indents the line and makes it a menu item.

      •  

    • Click in the Menu Caption field and enter "Open".

      •  

    • Click in the Event Procedure field and enter "OpenFile". The OpenFile routine will be called when the user selects this menu.

      •  

    • To create a separator after the Open menu, click the line button at the right side of the dialog (above the arrow buttons).

      •  

    • To set the values and move to a new line, click Insert.

      •  

    • In the Menu Caption field, enter "Exit".

      •  

    • In the Event Procedure field, enter "OnExit".

      •  

    • To set the values and move to a new line, click Insert.

     

  6. To define the Tools menu and its one item, do the following:
    • With the new line selected, click the left arrow to make the line a top-level menu.

      •  

    • In the Menu Caption field, enter "Tools", then click Insert.

      •  

    • Click the right arrow to make the new line a menu item.

      •  

    • In the Menu Caption field, enter "Load Color Table".

      •  

    • In the Event Procedure field, enter "OnColor".

      •  

    • To set the values and move to a new line, click Insert.

     

  7. To define the Analyze menu and its one menu item, do the following:
    • With the new line selected, click the left arrow to make the line a top-level menu.

      •  

    • In the Menu Caption field, type "Analyze", then press Enter.

      •  

    • Click the right arrow to make the new line a menu item.

      •  

    • In the Menu Caption field, enter "Smooth".

      •  

    • In the Event Procedure field, enter "DoSmooth"

     

  8. Save your menu definitions by clicking OK in the Menu Editor.

    9.  

  9. At this time you can click on the menus to test them.

    10.  

  10. From the IDLDE File menu, choose Save, which opens the "Save As" dialog.

    11.  

  11. In the "Save As" dialog, select a location, enter "example.prc" in the File name field, and click Save. This action writes the portable resource code to the specified file.

To create a draw area that will display PNG image files, follow these steps:

  1. Click on the Draw Widget tool button (the dark square icon), then drag out an area that fills the top-level base display area. Leave a small margin around the edge of the draw area when you drag it out.

    2.  

  2. Right click on the draw area, and choose Properties. This action opens the Properties dialog for the draw area; the draw widget properties are displayed in the dialog.

    3.  

  3. In the Properties dialog, click the push pin button (in the top right corner of the dialog box) so the dialog will stay open and on top.

    4.  


    Note
    This Properties dialog floats and is resizeable.

     

  4. In the Properties dialog, change the draw widget Name attribute value to "Draw".

Later, you will write code to handle the display of the image in this draw area widget. Renaming the widget now will make it easier to write the code later; the "Draw" name is easy to remember.


Note
The Name property must be unique to the widget hierarchy.

  1. In the IDL GUIBuilder window, click on the top-level base widget to select it. When you do so, the Properties dialog will update and display the attributes for this base widget.

    2.  

  2. In the Properties dialog, locate the Component Sizing property, and select Default from the droplist values. This action sizes the base to the draw widget size you created.

    3.  

    When the size of the base was first dragged out, the Component Sizing property changed from Default to Explicit—you explicitly sized the widget. Now that the base widget contains items, you can return it to Default sizing, and IDL will handle the sizing of this top-level base.

     

  3. From the File menu, choose Save.

Running the Application in Test Mode

You can run the application in test mode, which allows you to test the display of widgets and menus.

To run your application in test mode:

To exit test mode:

Generating the IDL Code

To generate the code for the example application, follow these steps:

  1. From the File menu, choose Generate .pro. This action opens the "Save As" dialog.

    2.  

  2. In the "Save As" dialog, find the location where you want the files saved, enter "example.pro" in the File name field, and click Save.

This action generates an example.pro widget definition file and an example_eventcb.pro event-handling file.

The example.pro file contains the widget definition code, and you should never modify this file. If you decide later to change your interface, you will need to regenerate this interface code, and thus overwrite the widget code file.

The example_eventcb.pro contains place holders for all the event procedures you defined in the IDL GUIBuilder Menu Editor and Properties dialog. You must complete these event procedures by filling in event callback routines. This file will only be appended to when new event handlers are added so changes made will not be lost.


Note
You should modify only the generated event-handling file (*_eventcb.pro); you should never modify the generated interface code (the *.pro file).

Handling the Open File Event

You can now modify the generated example_eventcb.pro file to handle the events for the application. First, you will modify the OpenFile routine.

When the user selects Open from the File menu of the example application, the appropriate event structure is sent, and the OpenFile routine handles the event. For this application, the Open menu item will launch an Open dialog to allow the user to choose a PNG file, and then the routine will check the selected file's type, read the image, and display it in the draw area.

To open the file and add the code to handle the OpenFile event, follow these steps:

  1. From the File menu in the IDLDE, choose Open, which launches the Open dialog.

    2.  

  2. In the Open dialog, locate and select the example_eventcb.pro file, and click Open. This file contains the event handling routine place holders, which you will now complete.

    3.  

  3. In the example_eventcb.pro file, locate the OpenFile procedure, which looks like this:
    4. PRO OpenFile, Event

END

     


    Tip
    To find the OpenFile routine, select OpenFile from the Functions/Procedures drop-down list on the IDLDE toolbar.

     

  4. Add the following code between the PRO and END statements to handle the event:
    5. ; If there is a file, draw it to the draw widget.  
sFile = DIALOG_PICKFILE(FILTER='*.png')  
IF(sFile NE "")THEN BEGIN  
   ; Find the draw widget, which is named Draw.  
   wDraw = WIDGET_INFO(Event.top, FIND_BY_UNAME='Draw');  
   ; Make sure something was found.  
   IF(wDraw GT 0)THEN BEGIN  
      ; Make the draw widget the current, active window.  
      WIDGET_CONTROL, wDraw, GET_VALUE=idDraw  
      WSET,idDraw  
      ; Read in the image.  
      im = READ_PNG(sFile, r, g, b)  
      ; If TrueColor image, quantize image to pseudo-color:  
      IF (SIZE(im, /N_DIM) EQ 3) THEN $  
         im = COLOR_QUAN(im, 1, r, g, b)  
      ; Size the image to fill the draw area.  
      im = CONGRID(im, !D.X_SIZE, !D.Y_SIZE)  
      ; Handle TrueColor displays:  
      DEVICE, DECOMPOSED=0  
      ; Load color table, if one exists:  
      IF (N_ELEMENTS(r) GT 0) THEN TVLCT, r, g, b  
      ; Display the image.  
      TV, im  
      ; Save the image in the uvalue of the top-level base.  
      WIDGET_CONTROL, Event.top, SET_UVALUE=im, /NO_COPY  
   ENDIF  
ENDIF


Note
In the added code, you used the FIND_BY_UNAME keyword to find the draw widget using its name property. In this example, the widget name, "Draw", is the one you gave the widget in the IDL GUIBuilder Properties dialog. The widget name is case-sensitive.

Now re-save example.pro to be sure that the changes are retained.

Handling the Exit Event

To add the code that causes the example application to close when the user chooses Exit from the File menu, follow these steps:

  1. Locate the OnExit procedure place holder, which looks like this:
    2. PRO OnExit, Event

END

     

  2. Add the following statement between the PRO and END statements to handle the destruction of the application:
    3. WIDGET_CONTROL, Event.top, /DESTROY

Handling the Load Color Table Event

To add the code that causes the example application to open the IDL color table dialog when the user chooses Load Color Table from the Tools menu, follow these steps:

  1. Locate the OnColor routine place holder, which looks like this:
    2. PRO OnColor, Event

END

     

  2. Add the following code between the PRO and END statements:
    3. XLOADCT, /BLOCK  
; Find the draw widget, which is named Draw:  
wDraw = WIDGET_INFO(Event.top, FIND_BY_UNAME='Draw')  
IF(wDraw GT 0) THEN BEGIN  
   ; Make the draw widget the current, active window:  
   WIDGET_CONTROL, wDraw, GET_VALUE=idDraw  
   WSET, idDraw  
   WIDGET_CONTROL,Event.top, GET_UVALUE=im, /NO_COPY  
   ; Make sure the image exists:  
   IF (N_ELEMENTS(im) NE 0) THEN BEGIN  
   ; Display the image:  
      TV, im  
      ; Save the image in the uvalue of the top-level base:  
      WIDGET_CONTROL, Event.top, SET_UVALUE=im, /NO_COPY  
   ENDIF  
ENDIF

This procedure opens a dialog from which the user can select from a set of predefined color tables. When the user clicks the name of a color table, it is loaded and the displayed image changes appropriately.


Note
The XLOADCT color table dialog affects only 8-bit display devices.

Handling the Smooth Event

When the user selects Smooth from the Analyze menu, a smooth operation is performed on the displayed image. The smooth operation displays a smoothed image with a boxcar average of the specified width, which in the example code is 5.

To add the callback routines to handle the smooth operation, follow these steps:

  1. Locate the DoSmooth routine place holder, which looks like this:
    2. PRO DoSmooth, Event

END

     

  2. Add the following code between the PRO and END statements to handle the smooth operation:
    3. ; Get the image stored in the uvalue of the top-level-base.  
WIDGET_CONTROL, Event.top, GET_UVALUE=image, /NO_COPY  
; Make sure the image exists.  
IF(N_ELEMENTS(image) GT 0)THEN BEGIN  
   ; Smooth the image.  
   image = SMOOTH(image, 5)  
   ; Display the smoothed image.  
   TV, image  
   ; Place the new image in the uvalue of the button widget.  
   WIDGET_CONTROL, Event.top, SET_UVALUE=image, /NO_COPY  
ENDIF

     

  3. From the File menu, choose Save, which saves all your changes to the example_eventcb.pro file.

Compiling and Running the Example Application

To compile and run your example application, follow these steps:

  1. Type example at the IDL> command prompt. This compiles and runs the example application, opening the GUI interface that has been created.

    2.  

  2. Now open a PNG image to try out the new application. From the File menu choose Open, locate a PNG file, and click "Open".

    3.  

  3. You will now see the image opened in your GUI window. To manipulate the color schemes, click Tools/Load Color Table. The following figure shows the example application and the IDL color table dialog. You can also perform the smooth procedure on the image.

    4.  

    Figure 14-2: The Example GUI Application

    Figure 14-2: The Example GUI Application

  IDL Online Help (March 06, 2007)