Tutorial Three: Creating a Dialog


Tutorial Three: Creating a Dialog

In this tutorial, you will create an interface containing a BulletinBoard and two PushButtons. Clicking one PushButton will exit the application. Clicking the other will cause a dialog to appear. The dialog will consist of a BulletinBoard and a PushButton. Clicking this PushButton will dismiss the dialog.

Clear the Builder Xcessory display by selecting New from the Browser File menu.

Note: This tutorial assumes that you have chosen C as your language.

Creating Objects

Create a BulletinBoard and two PushButton children. If you are uncertain about how to do this, review See Creating and Resizing a Widget Instance and See Placing a Child Widget .

Creating a Dialog Shell

To create the dialog shell as a child of the bulletinBoard:

The dialog shell appears on your display. The Browser should now display dialogShell as the child of bulletinBoard and the parent of bulletinBoard1.
  1. Select BulletinBoard in the Containers group on the Palette.
  2. Position the upper-left corner of the BulletinBoard atop the existing bulletinBoard, and place it as a dialog by clicking MB3.

Completing the Collection

At this point you would add whatever widgets were to make up the dialog as descendents of bulletinBoard1. The dialog described in the remainder of this tutorial contains a single PushButton that dismisses the dialog. If you wish, you can experiment with Builder Xcessory and customize your own dialog for this example.

Adding a PushButton

Add a PushButton as the child of bulletinBoard1. This PushButton is created on the Browser object instance hierarchy as pushButton2.

The object instance hierarchy of your interface, displayed on the Browser, should now appear like the following figure:

Dialog Collection Instance Hierarchy

Editing Resources

Now you will use the Resource Editor or Builder Xcessory's extended editors to set widget resources. If you are uncertain about these procedures, review Using an Extended Editor and Setting Callback Resources .

labelString = DIALOG
activateCallback = DialogCallback()
labelString = EXIT
activateCallback = BxExitCB(0)
The latter is a predefined callback. If you have questions about using predefined callbacks, refer to Using Predefined Callbacks .
labelString = DISMISS
activateCallback = DismissCallback()
  1. Update the Resource Editor for pushButton.
  2. 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.
  3. Set the following resource values for pushButton:
  4. Set the following resource values for pushButton1:
  5. Set the following resource values for pushButton2:

Your interface should now appear like the following figure:

Top Level of Interface

Creating a Global Widget

You will now set bulletinBoard1 to have a Global scope, so that it can be referenced in the PushButton's DialogCallback.

The Storage Location dialog appears.
  1. Make bulletinBoard1 the currently selected object.
  2. Select Storage Location from the Resource Editor Component menu.
  3. Click on the Scope options menu, select Global.
  4. Confirm that Widget reflects the instance name bulletinBoard1.
  5. Click OK to dismiss the Storage Location dialog.

Generating Code

Save the interface code by writing a combination of C and UIL files. Then edit the file containing the callback structures to connect the functionality of the interface.

Save the UIL file and generate C code for your interface. If you have questions about these procedures, review Generating Code .

Confirming the Global Widget

Load <tutorial_path>/Tut3/creation-c.h into a text editor.

Observe that the following structure has been generated:

* Global widget declarations.
* - EXTERNAL is set to extern if the
* defs file is not included from the
* main file.
#define EXTERNAL
#define EXTERNAL extern
* Start Global Widget Declarations.
EXTERNAL Widget bulletinBoard1;
* End Global Widget Declarations.

Close the file.

Editing the Callback Structures

#include <Xm/Xm.h>
add the following:
#include "creation-c.h"
add the line:
add the line:
The stubs in the callbacks-c.c , with your additions marked in bold, should now look like this:
The DialogCallback stub:
DialogCallback(w, client_data, call_data)
Widget w;
XtPointer client_data;
XtPointer call_data;
The DismissCallback stub:
DismissCallback(w, client_data, call_data)
Widget w;
XtPointer client_data;
XtPointer call_data;
  1. Load <tutorial_path>/Tut3/callbacks-c.c into a text editor.
  2. At the top of the file, after the line:
  3. Inside the procedure DialogCallback, after the line:
  4. Inside the procedure DismissCallback, after the line:
  5. Save and close the file.

Compiling and Running

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

Testing the Interface

The application shell collection should appear on the screen.

  1. Pop up the dialog by clicking MB1 on the PushButton labeled "DIALOG". The dialog should look like the following figure:

Pop-up Dialog

  1. Remove the dialog by clicking "DISMISS".
  2. Exit the application by clicking "EXIT".

You have now completed Tutorial Three.