Previous User Interface Programming: Using the IDL GUIBuilder Next

Creating an Example Application

The following example takes you through the process of creating your first application with the IDL GUIBuilder and the IDLDE. You will create the user interface and write the event callback routines.

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 smooth operations on the displayed image.

This example introduces you to some of the basic procedures you will use to create applications with the IDL GUIBuilder; it shows you how to define menus, create widgets, 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 then the top-level base to a reasonable size for displaying an image. For example, drag the base out so that it has an X Size attribute value of 500 and a Y Size attribute value of 400. To view the attribute 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 attribute values.

    3.  

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

    4.  

  4. In the Menu Editor Menu Caption field, enter "File" and click Insert to set the entered value and add a new line after the currently selected line. The new line becomes the selected line.

    5.  

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

      2.  

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

      3.  

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

      4.  

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

      5.  

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

      6.  

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

      7.  

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

      8.  

    8. 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:
    1. With the new line selected, click the left arrow to make the line a top-level menu.

      2.  

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

      3.  

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

      4.  

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

      5.  

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

      6.  

    6. 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:
    1. With the new line selected, click the left arrow to make the line a top-level menu.

      2.  

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

      3.  

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

      4.  

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

      5.  

    5. In the Event Procedure field, enter "DoSmooth".

Your entries should look like those shown in the following figure.

 

Figure 3-2: Menu Editor Dialog with Example Menus

Figure 3-2: Menu Editor Dialog with Example Menus

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

    2.  


    Note
    For more information about using the Menu Editor, see Using the Menu Editor.

     

  2. At this time you can click on the menus to test them. Your interface should look similar to the one in the figure below.

    3.  

  3. Select File Save from the IDLDE menu, which opens the "Save As" dialog.

    4.  

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

 

Figure 3-3: IDL GUIBuilder with Example Application

Figure 3-3: IDL GUIBuilder with Example Application

Creating a Draw Widget

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

  1. Click on the Draw Widget tool button, 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 to open the Properties dialog for the draw area.

    3.  

  3. In the Properties dialog, click the push pin button so the dialog will stay open and on top.

    4.  

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

    5.  

    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 and to type.

     


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

     

  5. 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.

    6.  

  6. In the Properties dialog, change the base widget Component Sizing attribute to Default. This sizes the base to the draw widget size you created.

    7.  

    When you first dragged out the size of the base, the Component Sizing attribute 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.

     

  7. In the Properties dialog, change the base widget Layout attribute to Column.

    8.  

  8. Select File Save to save your new modifications to the example.prc file. The application should look like the one shown in the following figure.

 

Figure 3-4: Complete Example Application

Figure 3-4: Complete Example Application

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, do one of the following:

Both these actions display the interface as it will look when it runs. You can click on the menus, but there is no active event handling in test mode.

To exit test mode, do one of the following:

Generating the IDL Code

To generate the code for the example application, select File Generate .pro. 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 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. If you generate code after you have modified this file, any new event handling code will not be overwritten but will instead be appended. For information on ways to handle regenerating the *_eventcb.pro file, see Notes on Generating Code a Second Time.

For more information on interface definitions and generated code, see Generating Files.


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. Select File Open from the IDLDE menu. In the "Open" dialog, select the example_eventcb.pro file, and click Open. This file contains the event handling routine place holders, which you will now complete.

    2.  

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

     


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

     

  3. Add the following code between the PRO and END statements to handle the event:
    4.    ; 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 attribute. 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.

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 routine 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 selects a color table, it is loaded and the displayed image changes accordingly.

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. Select File Save, to save all your changes to the example_eventcb.pro file.

Compiling and Running the Example Application

To compile and run your example application, type example at the IDL> command prompt. The following figure shows the example application and the IDL color table dialog.

In the running application, you can open and display a PNG file. Then, you can open the XLOADCT dialog and change the color table used in displaying the image, or you can perform the smooth procedure on the image.

Figure 3-5: Running Example Application and XLOADCT Dialog

Figure 3-5: Running Example Application and XLOADCT Dialog

  IDL Online Help (March 06, 2007)