Tutorial One: Simple Actions

In this tutorial, you will create a BulletinBoard with two PushButtons. Clicking one PushButton displays an xterm, while clicking the other exits the application.

Starting Builder Xcessory

Start Builder Xcessory by entering the following command on the command line:

% bx50

Builder Xcessory, the Palette, Browser, and Resource Editor, are displayed. Refer to Starting Builder Xcessory for more detailed information about starting Builder Xcessory.

Note: By default, Builder Xcessory starts with an interface named uil.uil. If you are creating a new interface, you can keep this name or rename the interface upon saving it (Browser:File:Save As).

Clearing an Interface

If a current Builder Xcessory is already running, clear the interface as follows:

If you have any pixmaps, styles, procedures, identifiers, user-defined types, or literals that will be destroyed, Builder Xcessory displays a message dialog. Set the toggle if you wish to retain these items, then click the OK button to dismiss the dialog.

If an old interface exists, another dialog is displayed warning you that it will be destroyed. Click the OK button to dismiss the dialog.

Select New from the Browser File menu.
Select Choose a Language from the Options menu of the Browser.
Select C and Save As Default.

The remainder of this example assumes you have chosen C.

Creating and Resizing a Widget Instance

To create and resize an instance of the BulletinBoard widget, use the following procedure:

An outline of a BulletinBoard appears with the resize cursor in its upper-left corner.

Notice that the resizing cursor has moved to the lower-right corner of the BulletinBoard widget.

Your interface now contains a single BulletinBoard:

Select BulletinBoard by clicking MB1 on its image in the Containers group on the Palette.
Using the pointing device, move the cursor to the position on the display where you wish to place the upper-left corner of the BulletinBoard.
Press MB1, and move the cursor slightly to the right.
With the mouse button still depressed, resize the BulletinBoard outline to approximately three inches square. Release the mouse button.

Resized BulletinBoard

Placing a Child Widget

Select PushButton from the Primitives group on the Palette.
Place the PushButton inside the BulletinBoard, resized to be about an inch square.
Note: The Browser displays the widget instance pushButton as the child of bulletinBoard.

Placing an Automatically Resized Widget

Place a second PushButton, without resizing it, inside the BulletinBoard to the right of the first PushButton.

Notice that the second PushButton is created with the same height and width as pushButton. This is pushButton1. Your interface should look like the following figure:

BulletinBoard with Two PushButtons

Selecting a Widget

To make pushButton the currently selected widget, click MB1 on pushButton. You can click on the object either in the interface itself, or on the Browser display.

Updating the Resource Editor

To update the Resource Editor for pushButton1, double-click MB1 on pushButton1.

You can select the object either in the interface itself, or on the Browser display. You can also select Automatic Update from the Resource Editor Options menu, forcing the Resource Editor to update whenever a widget is selected. This is not recommended for very large interfaces, because it slows Builder Xcessory significantly.

Resource Editor Forms

You can customize the resources displayed on the Resource Editor by selecting an item from the View menu. Available options allow you to display All Resources, Simple Resources, Programmer Resources, Modified Resources, or Not Equal Resources. Refer to View Menu for a description of these categories.

Confirm that the Resource Editor is displaying all of the resources of the currently selected widget by selecting All Resources from the Resource Editor View menu.

Searching the Resource Editor

Confirm that pushButton1 is the currently selected widget. Its name should be displayed in the Resource Editor Instance Name field. Locate the labelString resource:

If the Find Resource field is not already displayed at the bottom of the Resource Editor, position the cursor within the Resource Editor and press Ctrl+F to display it.
Enter the name of the sought resource, labelString, into the Find Resource field.
Note: The current value of this resource is pushButton1.

You can also locate a resource by using the scrollbar to the right of the Resource Editor.

Setting a Resource

Now that you have assembled the elements of the interface, the next step is to set the resources of these widgets.

You can set a widget resource with one of the following procedures:

· Type the value directly into the text window to the right of the resource name in the Resource Editor.

· Apply the value to the resource using the appropriate extended editor.

Using an Extended Editor

Setting a resource value

To set the value of the labelString resource of pushButton1 to "EXIT":

This displays the extended editor appropriate for the labelString resource, the XmString Editor. (The window title includes the name of the resource, in this case "labelString".)

Extended editors are discussed in Extended Editors in the Builder Xcessory Reference Manual .

For the XmString Editor, first click MB1 at the end of the text field. Drag the cursor the length of the field while holding down MB1. This highlights the contents of the field. Pressing the delete key deletes the highlighted contents of the text field.

Type "EXIT" (without quotes) in the XmString Editor text window. Do not press return when you finish typing; that would simply add another (blank) line to the label.

This applies the contents of the XmString Editor text window as the labelString resource of pushButton1. Note that the new value is displayed in the text field to the right of the labelString resource on the Resource Editor.

Click the (...) button to the right of the labelString text field.
Enter the new resource value, EXIT, in the text area of the extended editor. (The instance name is displayed in this text area by default.)
Click the Apply button at the bottom of the Multiline Editor.

Setting a Resource in Multiple Widgets

A major advantage of extended editors is that they allow you to apply resource values to a series of widgets without updating the Resource Editor.

To set the value of the labelString resource of pushButton to XTERM:

Without dismissing the extended editor, select pushButton.
In the XmString Editor, delete EXIT, and type XTERM.
Click Apply to apply the new resource value to pushButton.
Click Dismiss to remove the XmString Editor.

Your interface should appear as follows:

Labeled PushButtons

Setting Callback Resources

Callback resources are set like any other resource in Builder Xcessory. You could type the callback information into the text window to the right of the resource in the Resource Editor. However, because you will change this resource for more than one widget, you should again use an extended editor, in this case, the Callback Editor.

Updating callback resources

This time start with the PushButton labeled XTERM, since it is the currently selected widget.

This displays the Callback Editor.

AppCallback

Click the OK button to the right of the text field. A dialog prompts you to confirm that you wish to declare AppCallback as a new procedure in the interface. Click OK to confirm this.

The new procedure was originally created with a default Parameter Type of Undeclared. You have changed the type to String.

"xterm&"

Remember to click the OK button to the right of the text field.

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 an xterm being created when AppCallback is called.

Update the Resource Editor for pushButton, the PushButton labeled XTERM.
In the Resource Editor, locate the activateCallback resource.
Click the (...) button to the right of the resource.
In the Callback Editor, enter the following in the text field to the right of the Procedure Name label:
Click on the arrow next to Parameter Type, and select String from the list of types.
Enter (with quotes) the following in the Parameter Name text field:
Click the Apply button to apply the contents of the Callback List as the resource value of activateCallback.
Click Edit to display your pre-set editor (chosen from Browser:Options:Tools Preferences) with the callback stub loaded.
After the line:

Do not dismiss the Callback Editor; you will use it for pushButton1.

Using Predefined Callbacks

Builder Xcessory has a number of predefined callbacks to save you the time and effort of continually rewriting certain common callbacks. Predefined callbacks are also active in Play Mode, enabling you to observe the effect of the callback without having to build the executable.

Setting a callback resource

To set the callback resource for the PushButton labeled EXIT:

Do so either by clicking Reset, which sets the list to the current (null) value of activateCallback for the EXIT PushButton, or by highlighting any callbacks appearing in the Callback List and then clicking Delete.

Display the list by clicking the arrow button to the right of the Procedure Name text field on the Callback Editor. Select an item by clicking on it in the list. The list is automatically unposted, and the selected item is displayed in the text field.

Select pushButton1, the PushButton labeled EXIT.
Clear the Callback List on the Callback Editor.
Select BxExitCB from the list of predefined callbacks.
Note: The Parameter Type is automatically associated with the default type for the selected callback, in this case, Integer for BxExitCB.

The value BxExitCB(0) should now be displayed for activateCallback in the Resource Editor.

You do not need to edit the BxExitCB procedure. As a predefined callback, it already contains all code necessary for it to function.

Enter the value 0 in the Parameter Name text field on the Callback Editor.
Apply the contents of the Callback List to pushButton1.
Click Dismiss to remove the Callback Editor.

Generating Code

You have constructed the interface and set up the callbacks. The next step is to write out the code for the interface. You will then edit the code and test the interface.

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

This writes out the file uil . uil (the default interface name; see Starting Builder Xcessory ), which can be read back into Builder Xcessory to reconstruct the collection.

It is a good idea to regenerate the callbacks-c.c file each time.

Select Save from the File menu on the Browser, then click OK.
Select Generate from the Browser File menu.

Reviewing the Callback Structures

To review the callback structures, do the following:

The callbacks-c.c file should contain the following procedures (not necessarily in this order):

/* ARGSUSED */

void

AppCallback(w, client_data, call_data)

Widget w;

XtPointer client_data;

XtPointer call_data;

{

XmAnyCallbackStruct
*acs=(XmAnyCallbackStruct*)call_data;

system((char*)client_data);

}

void

BxExitCB ARGLIST((w, client, call))

UARG(Widget, w)

ARG(XtPointer, client)

GRAU(XtPointer, call)

{

int exitValue = (int)client;

exit(exitValue);

}

Load <tutorial_path>/Tut1/callbacks-c.c into a text editor (for example, vi , or emacs).
Save and close the file.

Compiling and Running

You are ready to compile the C code in order to implement the callbacks that you set up. To compile the code:

make -f makefile-c

If the compile fails, select the Makefile tab on the Code Generation Preferences dialog (from the Browser Options menu) and confirm that the CFLAGS field of the Makefile tab contains

-I/usr/include/Xm -D_NO_PROTO

main-c

cd to the directory to which you wrote the output files.
Type the following command at the prompt:
Type the following command at the prompt:

Your interface should appear on the screen.

Testing the Interface

If you click MB1 on the PushButton labeled XTERM, an outline of an xterm should appear on your display. If you click on the PushButton labeled EXIT, your interface should disappear and the program should exit.

Note: On some systems, exit does not kill the parent process before all of its children have been killed. This means that you are not able to kill your interface before you exit out of all of the xterms that you created with the interface. To avoid this situation, kill all of the xterms before you select the EXIT button.

You have now completed Tutorial One.

Documentation:

Builder Xcessory 5.0 Users Guide

Search form

Documentation: