Tutorial Two: Simple Objects

 

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.

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

Using Keep Parent

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

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.
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.
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.
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 likeMainWindow with CascadeButtons .
  1. Select MenuBar from the Menus group of the Palette and place it as a child of the MainWindow.
  2. Select Keep Parent on the Browser View menu.
  3. double-click MB1 on PulldownMenu in the Menus group on the Palette.
  4. Place another PulldownMenu collection as a child of menuBar.

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.

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

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.

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

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:

The File Selection window appears.
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.
The name is the default, <tutorial_path>/Tut1/uil.uil , unless you changed it during code generation.
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.
  1. Select Read from the Browser File menu.
  2. Enter the absolute path <tutorial_path>/Tut1 into the Filter text field.
  3. Select the UIL file for the collection from the first tutorial by clicking on its name in the Files list.
  4. Click the OK button.

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.

The PushButton is removed from your interface.
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:
  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. 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.

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.

An icon appearing as a white square with a grey border is displayed as soon as you begin to move the cursor.
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.
  1. Press MB2 over the PushButton labeled XTERM on your interface.
  2. Holding down the mouse button, drag the icon over the widget instance pulldownMenu in the Browser display.
  3. Press the Ctrl key, and then release the mouse button.
  4. 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.

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

Editing the Callback Structures

To edit the callback structures, do the following:

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.
  1. Click Edit to display the callback stub loaded into your text editor.
  2. Within the procedure AppCallback, after the line:
  3. 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

  • Set Build Mode from the Browser Project menu before continuing.
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.

Completing the Interface

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

Exit Menu

Removing a TopLevelShell

Remove the read-in collection by the following method:

The object instance hierarchy of your interface, as displayed in the Browser, should now appear as in Object Instance Hierarchy .
  1. Select TopLevelShell1 on the Browser display.
  2. Select Delete from the Browser Edit menu.
  3. 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 .

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

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.

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.
The "Exit" menu appears.
The program exits.
  1. Click MB1 on the label "Tools".
  2. Test the mnemonics on the "Tools" menu. (For more information on how to do this, see Palette Mnemonics .)
  3. Scroll through the menu several times by repeatedly clicking either the up or down arrow key.
  4. Click on the label "Exit".
  5. Click on the EXIT button.

You have now completed Tutorial Two.

 

Documentation: