Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]

IDL GUIBuilder Examples

After you define your interface and generate IDL code using the IDL GUIBuilder, you will write the code that controls the application's behavior. You can modify the code, compile it, and run it using the IDLDE.

Generally, you will be writing the event-handler callbacks for the procedures located in the generated *_eventcb.pro file. While doing this, you might like to handle initialization states, have multiple GUIs work together, add compound widgets, or control widget display. For examples of how to handle these different types of events, see the following sections:

Understanding IDL GUIBuilder Event Handling Code

When using the IDL GUIBuilder, you assign event procedures to specific events using the Events tab of the Properties dialog. The calling sequence for the events that you set are added to the generated *_eventcb.pro event callback code.

The argument that is passed into the specified event routine depends on the type of event being processed. Creation, realization, and destruction event routines are usually passed the ID of the involved widget, and all other callback routines are passed the appropriate IDL widget event structure.

It is a normal operation in applications to change the attributes of the interface when certain events occur. One method used in handling events for IDL GUIBuilder generated applications is the UNAME keyword, or the Name attribute, given to all created widgets. (In a programmatically-created IDL application, this action is handled using information stored in a widget component's user value.)

When you create a widget in the IDL GUIBuilder, IDL gives it a name unique to the widget hierarchy to which it belongs. You can rename the widget using the Name attribute.

In the generated code, this name is specified by the UNAME keyword. Because these names are unique, you can use the WIDGET_INFO function with the FIND_BY_UNAME keyword in your event callback routines to get the IDs of widgets in the interface application.

Note
For information on properties, see Using the Properties Dialog, and see Widget Properties.

Writing Event Callback Routines

This short example shows how basic event processing works in code generated by the IDL GUIBuilder. The example demonstrates how to use the FIND_BY_UNAME keyword to obtain the IDs of other widgets in the interface.

To create this simple example application, follow these steps:

  1. Select File ® New ® GUI from the IDLDE menu. This opens a new IDL GUIBuilder window.
  2. In the IDL GUIBuilder window, right-click on the contained top-level base, and choose Properties from the menu. This opens the Properties dialog.
  3. In the open Properties dialog, click the push pin button to keep the dialog open and on top.
  4. On the Attributes tab of the Properties dialog, set the top-level base Layout attribute to Column.
  5. On the IDL GUIBuilder toolbar, click the Label Widget button, and click on the top-level base area to add a label widget to the base.
  6. With the label widget selected, set the following attributes in the Properties dialog:
  7. On the IDL GUIBuilder toolbar, click the Button Widget button.
  8. Click on the top-level base area, which adds a button widget to the interface.
  9. With the button selected, set the Label attribute to "Time".
  10. In the Properties dialog, click the Events tab and set OnButtonPress to "OnPress".

Your interface definition should look like the one shown in the following figure.

  1. Select File ® Save from the IDLDE menu, which opens the "Save As" dialog.
  2. In the "Save As" dialog, select a location, enter "time.prc" in the File name field, and click Save. This saves the interface definition to a resource file.
  3. Select File ® Generate .pro from the IDLDE menu. In the "Save As" dialog, select the location, enter "time.pro" in the File name field, and click Save. This saves the time.pro widget code file and the time_eventcb.pro event callback code to the specified directory.
  4. Select File ® Open from the IDLDE menu. In the "Open" dialog, select the time_eventcb.pro file and click Open.
  5. In the time_eventcb.pro file, locate the OnPress event procedure place holder, which looks like this:
    6.    pro OnPress, Event 
 
   end
  6. Add the following IDL code between the PRO and END statements to handle a button press:
    7.    ; Get the widget ID of the label widget. 
   Label = widget_info(Event.top, find_by_uname='clock') 
 
   ; Set the value of the label widget to current time. 
   widget_control, Label, set_value=Systime(0)

    The first command gets the ID of the label widget by searching the widget hierarchy for a widget named "clock". This is the name that you gave the label widget in the IDL GUIBuilder Properties dialog. Once the ID is found, the second command sets the value of the label widget to the current system time.

  7. Select Run ® Compile time_eventcb.pro to save and compile the file.
  8. To execute the program, enter time at the IDL command prompt.

This compiles and runs the time.pro file. In the running application, you can press the Time button to cause the current time to be displayed in the label.

Handling Initialization Arguments

You can provide runtime initialization information to the generated *.pro widget code by modifying the *_eventcb.pro file. Keywords provided to the generated widget interface procedure are passed to the post creation routines using the _EXTRA keyword.

If a routine is defined with the _EXTRA keyword parameter, you can add unrecognized keyword and value pairs, and the pairs are placed in an anonymous structure. The name of each unrecognized keyword becomes a tag name, and each value becomes the tag value.

You will use this feature most often when your application launches floating or modal dialogs, but the functionality is always available.

For example, if you want to display a dialog at the creation of an application, you would follow these basic steps:

  1. Create an interface using the IDL GUIBuilder.
  2. After creating the interface, open the Properties dialog for the top-level base and set the PostCreation event for the top-level base widget to a routine name, such as "OnCreate".
  3. Save the interface definition and generate the IDL source code.
  4. In the generated *_eventcb.pro event code file, locate the "OnCreate" routine place holder, which looks like this:
    5.    pro OnCreate, wWidget, _EXTRA=_VWBExtra_ 
 
   end
  5. To process a specific keyword in this post creation routine, declare the keyword in the procedure statement and add the processing code to the procedure.

    6. For example, to process the DO_DIALOG keyword in the defined OnCreate procedure, add the DO_DIALOG keyword to the procedure, and add the logic to handle it to the event callback routine. The completed procedure should look like this:

       pro OnCreate, wWidget, DO_DIALOG=DO_DIALOG, _EXTRA=_VWBExtra_ 
 
      ; If DO_DIALOG is set, display a simple message box. 
      if( Keyword_Set(DO_DIALOG) )then $ 
        status = Dialog_Message("On Dialog Set") 
 
   end
  6. Save the file, then compile and generate the application. To show the dialog at creation time, enter the following at the IDL command prompt:
    7.    <ProgramName>, /DO_DIALOG

Integrating Multiple Interfaces

You can create multiple interfaces with the IDL GUIBuilder then integrate them to form the complete application hierarchy. This example shows you how to construct two interfaces and integrate them.

The first interface you will create is the main window, and it will consist of a simple push button that will launch a modal dialog. The second interface you will create is the modal dialog, and it will display a close button.

Creating the Main Window

To create the main window, follow these steps:

  1. Select File ® New ® GUI from the IDLDE menu to open a new IDL GUIBuilder window with a top-level base.
  2. On the IDL GUIBuilder toolbar, click on the Button Widget button, then click on the top-level base. This adds a button of the default size to the base. You can place the button anywhere in the base.
  3. Right-click on the newly created button, and choose Properties from the context menu to open the Properties dialog.
  4. In the Properties dialog, click the push pin button to keep the dialog open and on top.
  5. Set the button's Label attribute to "Modal Dialog".
  6. Click on the Properties dialog Events tab, and set the OnButtonPress value to "OnPress".
  7. Select File ® Save. In the "Save As" dialog, select a location, enter "maingui.prc" in the File name field, and click Save. This saves the interface definition to an IDL resource file.
  8. Select File ® Generate .pro. In the "Save As" dialog, select a location, enter "maingui.pro" in the File name field, and click Save. This saves the maingui.pro widget code and the maingui_evnetcb.pro event-handler code.
  9. Select File ® Open. In the "Open" dialog, select the maingui_eventcb.pro file, and click Open.
  10. In the maingui_eventcb.pro file, locate the OnPress event procedure place holder, which looks like this:
    11.    pro OnPress, Event 
 
   end
  11. Add the following code between the PRO and END statements:
    12.    modalgui, group_leader=Event.top

    You will create the "modalgui" dialog in the next set of steps. Note that you set the GROUP_LEADER keyword here because the modal dialog requires it.

  12. Select Run ® Compile maingui_eventcb.pro. This saves and compiles the file.

Creating the Modal Dialog

To create the modal dialog, follow these steps:

  1. Open a new IDL GUIBuilder window.
  2. In the IDL GUIBuilder window, select the top-level base, and set the following in the Properties dialog:
    • Set the Modal attribute to True.
    • In the Title field, enter "Modal Dialog".
  3. On the IDL GUIBuilder toolbar, click the button widget, then click on the top-level base. This adds a button to the top-level base. Place it anywhere in the base.
  4. With the new button selected, set the Label attribute value to "OK".
  5. On the Events tab of the Properties dialog, set the OnButtonPress value to "OnModalPress".
  6. Select File ® Save. In the "Save As" dialog, select a location, enter "modalgui.prc" in the File name field, and click Save. This saves the interface definition to an IDL resource file.
  7. Select File ® Generate .pro. In the "Save As" dialog, select a location, enter "modalgui.pro" in the File name field, and click Save. This saves the modalgui.pro widget code file and the modalgui_eventcb.pro event callback file.
  8. Open the modalgui_eventcb.pro file and locate the OnModalPress procedure place holder. Then add the following code between the PRO and END statements so that the dialog closes when the button is pushed:
    9.    widget_control, Event.top, /destroy
  9. Save and compile this file.

Running the Example Application

Enter maingui at the IDL command prompt. This command runs the main window. You can press the Modal Dialog button, and the modal dialog is displayed. When you press the OK button on the modal dialog, the dialog exits.

Adding Compound Widgets

The IDL GUIBuilder tools do not allow you to add a compound widget directly to your interface. You can, however, modify your event code to add a compound widget.

To add a compound widget to an IDL GUIBuilder generated interface, follow these basic steps:

  1. Add the compound widget to the widget tree in a PostCreation event callback procedure.
  2. Handle the events generated by the compound widget in the Handle Event callback function. Set this event function value for the base widget that will contain the compound widget.

Adding a Compound Widget to an Interface

This example demonstrates how to add a compound widget to an application constructed with the IDL GUIBuilder. The application contains a label and a CW_FSLIDER compound widget. In the running application, the values generated by CW_FSLIDER will be displayed in the label widget.

To create this application, follow these steps:

  1. Select File ® New ® GUI from the IDLDE menu to open a new IDL GUIBuilder window with a top-level base.
  2. Right-click on the base and choose Properties to open the Properties dialog for the top-level base.
  3. In the Properties dialog, click the push pin button to keep the dialog on top.
  4. In the Properties dialog of the top-level base, set the Layout attribute to Column.
  5. To add the label, click the Label Widget button on the toolbar, then click on the top-level base. This creates a label widget of the default size.
  6. With the label selected, set the following in the Properties dialog:
  7. Click the Base Widget button on the toolbar, and click on the top-level base. This adds a base to the top-level base.
  8. With the new base widget selected, set the Component Sizing attribute to Default.
  9. In the Properties dialog, click on the Events tab and set the following base widget event values:
    • In the Handle Event Value field, enter "HandleEvent". This is the name of the function that will handle the compound widget events.
    • In the PostCreation Value field, enter "AddCW". This is the name of the event routine that will create the compound widget.
  10. Select File ® Save. In the "Save As" dialog, select a location, enter "compound.prc" in the File name field, and click Save. This saves the interface definition to an IDL resource file.
  11. Select File ® Generate .pro. In the "Save As" dialog, enter "compound.pro", and click Save. This generates the compound.pro widget code file and the compound_eventcb.pro event-handler file.
  12. Select File ® Open, and open the compound_eventcb.pro file.
  13. In the compound_eventcb.pro file, locate the AddCW event routine place holder, and insert the code to add the CW_FSLIDER compound widget to the base widget. The routine should look like this:
    14.    pro AddCw, wWidget 
 
      idslide = CW_FSLIDER(wWidget, /SUPPRESS_VALUE) 
 
   end
  14. Add the event callback routines to the generated HandleEvent function. The function should look like this:
    15.    FUNCTION HandleEvent, Event 
 
      ; Fslider event structure is an anonymous structure, so 
      ; the following will return "" if it is from fslider. 
 
      IF(TAG_NAMES(Event, /STRUCTURE_NAME) eq "")THEN BEGIN 
 
         ; Get the id of the label widget using its name. 
         id = widget_info(Event.top, find_by_uname='label') 
 
         ; Set the value of the label, to the value in the slider. 
         WIDGET_CONTROL, id, set_value= $ 
            String(Event.value, format='(f5.2)') 
         RETURN,0  
         ; Halt event processing here. 
      ENDIF 
 
      RETURN, Event 
 
   END

    Note that the callback routine finds the label widget using the FIND_BY_UNAME keyword with the name value you gave the widget in the Properties dialog.

  15. Select Run ® Compile compound_eventcb.pro to save and compile the file.

Running the Example

To run the application, enter compound at the IDL command prompt. This complies and runs the application. In the running application, move the CW_FSLIDER and the value is placed in the label.

Controlling Widget Display

This example demonstrates how to use the IDL GUIBuilder to create an interface that contains overlapping sub-bases containing different types of widgets. The example shows how you can display and hide overlapping controls in an interface created in the IDL GUIBuilder, and it incorporates using the Widget Browser. Note that this example is slightly more complicated than the others.

This example constructs an interface with the following widgets:

The two contained sub-bases overlap and the visibility of each is controlled by the value selected in the droplist. When users select an item in the droplist, one sub-base is hidden and the other one is displayed.

Creating the Interface

To create this application interface, follow these steps:

  1. Select New ® GUI from the IDLDE File menu to open a new IDL GUIBuilder window with a top-level base.
  2. Right-click on the top-level base, and choose Properties from the menu. This opens the Properties dialog.
  3. In the Properties dialog, click the push pin button to keep the dialog open and on top.
  4. In the Properties dialog, set the Layout attribute to Column.
  5. On the IDL GUIBuilder toolbar, click on the Droplist Widget button, then click on the top-level base. This creates a droplist in the base area.
  6. With the droplist selected, set the following in the Properties dialog:
    • In the Title value field, enter "Active Base".
    • In the Initial Value field, click on the arrow. This displays a popup edit control. Enter "Base One", press Control+Enter to move to the next line, enter "Base Two", and press Enter to close the popup edit control.
  7. On the Events tab of the Properties dialog, set OnSelectValue to "OnSelect".
  8. On the IDL GUIBuilder toolbar, click on the Base Widget button, then click on the top-level base. This adds a base widget of the default size to the interface.
  9. With the new base selected, set the following attributes in the Properties dialog:
    • In the Name value field, enter "base0".
    • Set the Frame attribute to True.
  10. On the IDL GUIBuilder toolbar, click on the Base Widget button, then click on the base you just added. This adds a base widget to the "base0" widget.
  11. With the newly-added base selected, set the following attributes in the Properties dialog:
  12. Right-click on a base, and choose Browse from the context menu. This opens the Widget Browser.
  13. In the Widget Browser, right-click on base1, and choose Copy, which copies the widget to the local clipboard.
  14. In the Widget Browser, right-click on "base0", and choose Paste, which pastes the copied base in to the "base0" widget. The new base is called "base1_0".
  15. In the Widget Browser, select "base1_0". This selects the base in the IDL GUIBuilder window and updates the Properties dialog with the appropriate properties and values.
  16. With "base1_0" selected, set the following attributes in the Properties dialog:
  17. Select File ® Save. In the "Save As dialog", select a location, enter "visible.prc" in the File name field, and click Save. This saves the interface definition.
  18. In the Widget Browser, select "base1".
  19. With "base1" selected, set the Visible attribute to False. This will hide "base1" and make "base2" visible.
  20. On the IDL GUIBuilder toolbar, click the Button Widget button, then click on "base2" in the IDL GUIBuilder. This adds a button to the base widget. Place the button anywhere in this base.
  21. With the button selected, set the Label attribute to "Button 2".
  22. In the Widget Browser, select "base2", and using the Properties dialog, set the Visible attribute to False to hide the base.
  23. In the Widget Browser, select "base1", and set the Visible attribute to True to show the base.
  24. On the IDL GUIBuilder toolbar, click the Label Widget button, then click on "base1". This adds a label to "base1". Place the label anywhere in this base.
  25. With the label widget selected, set the Text attribute to "Label 1".
  26. Select File ® Save to save the changes to the visible.prc resource file.

The interface is now complete. It should look similar to the one shown in the following figure.

Generating and Modifying the Code

To generate and modify the code, follow these steps:

  1. Select File ® Generate .pro. In the "Save As" dialog, select a location, enter "visible.pro" in the File name field, and click Save. This saves the visible.pro widget code file and the visible_eventcb.pro event-handler file.
  2. Select File ® Open, select the visible_eventcb.pro file, and click Open.
  3. In the visible_eventcb.pro file, locate the OnSelect event procedure place holder, which looks like this:
    4.    pro OnSelect, Event 
 
   end
  4. Add the following code between the PRO and END statements:
    5.    ; Toggle the mapping of the two IDL sub-bases and 
   ; get the Widget IDs of the two sub-bases. 
   wBase1 = Widget_Info(Event.top, find_by_uname="base1") 
   wBase2 = Widget_Info(Event.top, find_by_uname="base2") 
 
   ; Now update the mapping. 
   widget_control, wBase1, map=(Event.index eq 0) 
   widget_control, wBase2, map=(Event.index eq 1)

    The added IDL code gets the Widget IDs of the sub-bases that you created and sets the mapping (hide or show) of these bases depending on the selected value of the droplist.

  5. Select Run ® Compile visible_eventcb.pro to save and compile the file.

Running the Application

To run this application, enter visible at the IDL command prompt. This command executes the visible application. In the running application, you can change the selection in the droplist, and the action will change the displayed widget.

Home | Categories | Alphabetical | Classes | All Contents | [ < ] | [ > ]