UpPreviousNext

Tutorial Two: Simple Objects

In this tutorial, you will experiment with the creation of more complex interface objects. You will create a MenuBar with three CascadeButtons, each of which will be associated with a menu. Selecting a given item from one of these menus will execute a program. As part of this exercise, you will incorporate into your new collection the PushButtons that you built in Tutorial One.

  1. Clear Builder Xcessory.
  2. If you have questions about clearing the interface, review Clearing an Interface .
  3. Select MainWindow from the Containers group on the Palette, resize the widget outline to about three inches square, and position it on your display.
  4. If you have questions about these actions, review Creating and Resizing a Widget Instance .

Using Keep Parent

A convenient shortcut for creating a menu with several CascadeButtons is to use Keep Parent mode. Do the following:

  1. Select MenuBar from the Menus group of the Palette and place it as a child of the MainWindow.
  2. If you have questions about these actions, review Placing a Child Widget .
    Do not worry about the size of the MenuBar, it will be resized automatically by the MainWindow.
  3. Select Keep Parent on the Browser View menu.
  4. Notice that as soon as you select Keep Parent, all widgets on the Palette are grayed out except PulldownMenu and PopupMenu. This is because these collections are the only legal children of a MenuBar.
  5. double-click MB1 on PulldownMenu in the Menus group on the Palette.
  6. A number of things happen. Builder Xcessory does not merely create a menu. Rather, it creates a collection of three widgets: a CascadeButton, a menu, and a PushButton. This is the collection stored in the Palette under the name "PulldownMenu". Further, because Keep Parent is active, the top-most parent in this collection, cascadeButton, automatically becomes a child of the currently selected widget, menuBar. Note also that menuBar remains the currently selected widget.
  7. Place another PulldownMenu collection as a child of menuBar.
  8. If the MainWindow is not large enough, one or both of these collections will not be visible on your display, and you will need to resize both the MainWindow and the MenuBar. Your interface now appears like MainWindow with CascadeButtons .
 

MainWindow with CascadeButtons

  1. Unset Keep Parent on the View menu.

Setting CascadeButton Resources

Use the Resource Editor to change the following attributes of each of the CascadeButtons.

  1. Set the labelString resource to "Tools" for cascadeButton, and "Exit" for cascadeButton1.
  2. You can edit the Resource Editor text field directly, or use the Compound String Editor to make these changes.
  3. Set the mnemonic resource to "T" for the Tools CascadeButton, and "E" for the Exit CascadeButton.
  4. Notice that, when set, the mnemonics appear underlined in the respective labels. Your interface should now appear as follows:
 

Labeled CascadeButtons with Mnemonics

Creating Additional Widgets

You are now going to add two PushButtons to one of the PulldownMenus. By an amazing coincidence, they are the same as those you created in the first tutorial. If you still have the UIL file from Tutorial One, skip down to the section Reading Files .

If you do not have the UIL file from Tutorial One, do the following in order to add two PushButtons to your interface.

  1. Place two PushButtons as their own top level shells.
  2. If you have questions about doing this, refer to Creating and Resizing a Widget Instance .
  3. Set the labelString resource of one PushButton to XTERM, and of the other to EXIT.
  4. If you have questions about doing this, refer to Setting a Resource .
  5. Use the predefined callbacks to set the activateCallback resource of the XTERM PushButton to BxSystemCB("xterm&") and of the EXIT PushButton to BxExitCB(0).
  6. If you have questions about doing this, refer to Using Predefined Callbacks .

Proceed to Deleting Widgets .

Reading Files

If you saved the UIL file from Tutorial One, read that file into your interface by doing the following:

  1. Select Read from the Browser File menu.
  2. The File Selection window appears.
  3. Enter the absolute path <tutorial_path>/Tut1 into the Filter text field.
  4. You can do this either by editing the field itself, or by selecting a name from the Directories list, clicking the Filter button to display the appropriate subdirectory and parent, and repeating this process until the Filter field displays the full path.
  5. Select the UIL file for the collection from the first tutorial by clicking on its name in the Files list.
  6. The name is the default, <tutorial_path>/Tut1/uil.uil , unless you changed it during code generation.
  7. Click the OK button.
  8. The interface, a BulletinBoard containing two PushButtons, should appear on the display. Note that it is displayed on the Browser as the child of its own top-level application shell, the two top-level widgets and their descendents exist as separate collections.

Deleting Widgets

Now you remove the menus' default PushButton children and replace them with copies of the PushButtons that you created in the first tutorial.

  1. Select the PushButton that is the child of the Tools PulldownMenu on your interface by clicking MB1 on its instance name, pushButton, in the Browser display.
  2. Select Delete on the Browser Edit menu.
  3. The PushButton is removed from your interface.
  4. If you read in the UIL file from Tutorial One, drag each of the PushButtons outside of the BulletinBoard and place them as top-level objects.
  5. The addition to your interface is a BulletinBoard and two PushButtons.
    The object instance hierarchy, as shown on your Browser display, should now appear as follows:
 

Object Instance Hierarchy

Copying and Reparenting Widgets

You will now copy the XTERM PushButton to create a set of PushButtons that appear on the menu invoked by the Tools CascadeButton.

  1. Press MB2 over the PushButton labeled XTERM on your interface.
  2. An icon appearing as a white square with a grey border is displayed as soon as you begin to move the cursor.
  3. Holding down the mouse button, drag the icon over the widget instance pulldownMenu in the Browser display.
  4. Press the Ctrl key, and then release the mouse button.
  5. Because you used the Ctrl key during the previous operation, you copied the PushButton as a child of the menu, while preserving the original. Performing the operation without the Ctrl key would have moved the same widget instance from one place on the display to another.
  6. Repeat this procedure to create three more copies of the XTERM PushButton as children of pulldownMenu.

Setting PushButton Resources

You will now use the Resource Editor to change the PushButton resources so that selecting the PushButtons calls standard X Window System utility programs. Use the Resource Editor to change the following attributes of the PushButtons.

  1. Set the labelString resource of three of the PushButtons to XBIFF, XLOAD and XCLOCK respectively.
  2. Use the XmString Editor to make these changes. If you have questions about this procedure, review Setting a Resource .
  3. Set the Parameter Name for the activateCallback resource, AppCallback(), to "xbiff&" for the PushButton labeled XBIFF, "xload&" for that labeled XLOAD, and "xclock&" for that labeled XCLOCK.
  4. Remember to click the OK button to the right of the Parameter field before Applying each new value.
  5. Make sure that the activateCallback resource for the XTERM PushButton is set to AppCallback("xterm&").
  6. If you have questions about these procedures, review Setting Callback Resources .

Editing the Callback Structures

To edit the callback structures, do the following:

  1. Click Edit to display the callback stub loaded into your text editor.
  2. Within the procedure AppCallback, after the line:
  3. XmAnyCallbackStruct
    *acs=(XmAnyCallbackStruct*)call_data;
    insert the line:
    system((char *)client_data);
    This command passes the input parameter, client_data , to the system call, system , which in turn passes its parameter to the operating system. This transaction is the same as typing the parameter on the command line, and results in the client being invoked when AppCallback is called.
  4. Save and close the file.

Using Play Mode

You can test the look and feel of your interface in Play Mode. To test the cascade menu that you have just created, do the following:

  1. Set Play Mode on the Browser Project menu.
  2. Click on the Tools CascadeButton. Your MainWindow should now appear like Tools Menu :
 

Tools Menu

When you select an item from the menu, the Message Window notifies you which application would be called (in this case AppCallback). Builder Xcessory does not execute callbacks (other than predefined callbacks) in Play Mode.
  • Set Build Mode from the Browser Project menu before continuing.
  • Completing the Interface

    1. Delete the PushButton that is the child of the Exit PulldownMenu (pulldownMenu1) on your interface.
    2. Copy the EXIT PushButton from the first collection to be the child of the Exit PulldownMenu.
    3. Since the widget is copied with all of its resources, you do not have to set its callback routine. If you have questions about this procedure, review Copying and Reparenting Widgets .
      In Play Mode, with the EXIT PushButton depressed, your interface should look something like the following figure:
     

    Exit Menu

    Removing a TopLevelShell

    Remove the read-in collection by the following method:

    1. Select TopLevelShell1 on the Browser display.
    2. Select Delete from the Browser Edit menu.
    3. The object instance hierarchy of your interface, as displayed in the Browser, should now appear as in Object Instance Hierarchy .
    4. Delete the two stand-alone PushButtons.
     

    Object Instance Hierarchy

    Generating Code

    When Builder Xcessory writes a Callbacks file to a directory containing another file with the same name, new callback stubs are appended to the old Callbacks file. Any callback structures in the original file are left untouched; you do not overwrite your old edited structures with blank stubs. In writing out the code for this interface, you could take advantage of this feature by building on the callbacks-c.c file from the first tutorial, which already contains the edited callback structures for the XTERM and EXIT PushButtons. You can accomplish this either by writing out the new Callbacks file into the directory that contains the old file, or by copying the old file into your present Output Files directory and then generating your output files. Of course, if you did not save the original file, or did not complete Tutorial One, you can write out a new Callbacks file and add all of the callback information.

    For the purposes of this tutorial, you will write out the callbacks-c.c file into directory Tut2 .

    You will probably want to change the destination directory to Tut2 . If you have questions about how to do this, review Changing the Destination Directory .

    1. Select Save from the Browser File menu.
    2. This writes the file uil.uil , which can be read back into Builder Xcessory to reconstruct the collection.
    3. Select Generate C from the Browser File menu.
    4. This writes out the C files, including the templates for the callback structures in the file callbacks-c.c .

    Compiling and Running

    Compile and run your program. If you have questions about these procedures, review Compiling and Running .

    Testing the Interface

    Your interface should appear on the screen.

    1. Click MB1 on the label "Tools".
    2. The "Tools" menu appears. You can select any item on this menu by clicking on it.
      You can loop through the menu using the arrow keys on the keyboard and select from the menu by pressing return when the option you want is highlighted.
    3. Test the mnemonics on the "Tools" menu. (For more information on how to do this, see Palette Mnemonics .)
    4. Scroll through the menu several times by repeatedly clicking either the up or down arrow key.
    5. Click on the label "Exit".
    6. The "Exit" menu appears.
    7. Click on the EXIT button.
    8. The program exits.

    You have now completed Tutorial Two.

    UpPreviousNext