UpPreviousNext

Tutorial Seven: Classes

Using Builder Xcessory, you can group a set of widgets together into a new reusable component. This new component is called a class, and is added to the User Defined Classes group on the Palette.

Once created, a class can be instantiated in the same manner as any other Palette object. A class can be modified at any time and changes to a class will appear in all instances of that class.

One big advantage of classes is that in C, C++, ViewKit, Java, and UIL the generated code consists of only one block of code for a given class. This block of code is reused for the creation of the various instances of the class.

A Builder Xcessory class should not be confused with an X Toolkit Widget Class.


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

Constructing the Interface

  1. Clear the Builder Xcessory display. If you have questions about this procedure, review Clearing an Interface .
  2. Create a Form widget, resized to approximately three inches high and four inches wide.
  3. If you have questions about this procedure, review Creating and Resizing a Widget Instance .
  4. Place a Label widget across the top of the Form. Set the Instance Name field in the Resource Editor to "title".
  5. If you have questions about this procedure, review Setting a Resource .
  6. Place a ScrolledList widget down the left side of the Form and under the Label.
  7. It should be about half the width of the Form.
  8. Add another Label on the right side of the Form under the first Label.
  9. It should be about half as wide as the Form. Set the Instance Name field in the Resource Editor to "question".
  10. Add a Frame under the Label, and resize it to be the same width as the Label.
  11. Add a Label inside the Frame. Set the Instance Name field in the Resource Editor to "answer".

The interface should now have the instance tree shown in the following figure:

 

Instance Tree

The interface itself should look something like the following figure:

 

Interface

Setting Resources

  1. 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.
  2. Use the Form Editor and the Resource Editor to set the following constraint resource values. If you have questions about these procedures, refer to Setting Constraint Resources .
  3. Widget 

    Resource

    Resource Value

    title

    bottomAttachment

    Xm_ATTACH_NONE

    title

    leftAttachment

    XmATTACH_FORM

    title

    leftOffset

    0

    title

    rightAttachment

    XmATTACH_FORM

    title

    rightOffset

    0

    title

    topAttachment

    XmATTACH_FORM

    title

    topOffset

    0

    scrolledWindow

    bottomAttachment

    XmATTACH_FORM

    scrolledWindow

    bottomOffset

    15

    scrolledWindow

    leftAttachment

    XmATTACH_FORM

    scrolledWindow

    leftOffset

    15

    scrolledWindow

    rightWidget

    question

    scrolledWindow

    rightAttachment

    XmATTACH_WIDGET

    scrolledWindow

    rightOffset

    15

    scrolledWindow

    topWidget

    title

    scrolledWindow

    topAttachment

    XmATTACH_WIDGET

    scrolledWindow

    topOffset

    15

    question

    bottomAttachment

    XmATTACH_NONE

    question

    rightAttachment

    XmATTACH_FORM

    question

    rightOffset

    15

    question

    leftAttachment

    XmATTACH_NONE

    question

    topWidget

    title

    question

    topAttachment

    XmATTACH_WIDGET

    question

    topOffset

    20

    frame

    bottomAttachment

    XmATTACH_NONE

    frame

    leftWidget

    scrolledWindow

    frame

    leftAttachment

    XmATTACH_WIDGET

    frame

    leftOffset

    0

    frame

    rightAttachment

    XmATTACH_FORM

    frame

    rightOffset

    15

    frame

    topWidget

    question

    frame

    topAttachment

    XmATTACH_WIDGET

    frame

    topOffset

    30

Your interface should now look something like the following figure:

 

Interface after Setting Constraint Resources

Creating a Class

You will now define this dialog as a class.

  1. Select the top-most widget, the Form, and select Make Class from the Browser Edit menu.
  2. A popup dialog prompts you for the name of the class.
  3. Enter "SelectDialog" in the dialog.
  4. The tree beneath the top level widget is replaced by a single icon representing the new class, SelectDialog. Note that you can no longer edit the constituent widgets of the class in the interface itself.

Editing a Class

  1. Switch to Classes view by clicking on the arrow button at the left of the Browser and selecting Classes.
  2. The list of your top level widgets switches to a list of your classes. The class SelectDialog should be the only one in the list.
    The Browser now displays the object instance hierarchy of your class, allowing you to set resources of the member widgets. Resources are set just as in Instances view.
  3. Select the Title widget and set the labelString resource to "Select Dialog".
  4. The resource setting of the labelString resource should be set to Code. Pull down the option menu and click on Expose.
  5. A small eye icon appears next to Code. (After Code is selected, Expose is sensitized and can be selected on the Placement option menu. Widget instances that are members of a class are the only instances that can be exposed.)
    When editing a class, you can force a resource to take the class value in all instances of the class or you can allow it to be overridden in a given class instance. To allow a class resource to be overridden in a class instance, you set it to be Exposed by clicking Expose on the resource setting options menu. Note that resources set to Style or None can not be Exposed.
  6. Select the Question widget, and set the labelString resource to "The item selected is..." and its resource setting to Code. Expose the resource.
  7. Select the List widget and set the following resources to these resource values (and resource settings):
  8. items = "None", Code (Exposed)
    singleSelectionCallback = Selector(), Code
    selectionPolicy = XmSINGLE_SELECT, Code
    If you plan on generating C, pass parameter class_in of parameter type SelectDialogDataPtr to Selector() .

Adding a Member

You can add data members to your class.

  1. Select the SelectDialog class in the Browser, and update the Resource Editor.
  2. Click on the (...) button next to the Protected Data field to bring up the Class Member Editor.
  3. Add a data member with Data Name selection and Data Type Compound String. Click Apply.

Adding a Method

You can also add a method to your class.

  1. Click on the (...) next to the Protected Methods field and toggle the Item Type option menu in the Class Member Editor.
  2. Add a method with a Method Name of get_selection and a Return Type of Compound String.
  3. Leave the Parameter Name and Parameter Type fields blank. Click Apply.

Creating a Class Instance

You have now finished designing the SelectDialog class.

  1. Switch back to Instances view.
  2. The Browser now displays the object instance hierarchy of your interface, including all instances of your class. You can easily create another class instance.
  3. Scroll the Palette until the SelectDialog class comes into view.
  4. Create an instance of SelectDialog by selecting it on the Palette and dragging it to your display.
  5. Set the Instance Name field on the Resource Editor to "selectItem" for the first class instance and "selectBuilder" for the second class instance.
  6. If you will be generating C, set the Storage Location for selectItem and selectBuilder to Global (Component:Storage Location). Accept the default Widget Name of each.
  7. You access the Storage Location dialog from the Resource Editor Component menu.

Editing a Class Instance

To edit an instance of your class:

  1. Update the Resource Editor for selectItem.
  2. All the exposed resources available in this class instance are displayed in the Resource Editor. You will find all the resources that you set as Exposed listed under Class Widget Resources, with a resource setting of Class. If you do not edit any of these fields, they will have the values you specified for the class. To override a resource, enter a new value.
  3. Set the following values:
  4. list1.items = item1,item2,item3
    question.labelString = You selected the following item:
    Your selectItem instance has overridden the label and the list items but it has the same title that was specified in the class. Note that the resource setting for the overridden resources has changed to Code.
    Your interface should now look something like the following figure:
 

Edited Class Instance

  1. Now override all the resources in the selectBuilder instance by entering the following resources:
  2. question.labelString = The best builder tool is:
    list.items = Builder Xcessory,
    Acme Builder Tool,
    Legos,
    Fred
    title.labelString = Select a Builder Tool

Generating Code

You have now constructed an interface with two instances of your class. The next step is to write out the code for your interface. Save the UIL file and generate either C or C++ code for your interface. If you have questions about these procedures, review Generating Code .

When you generate code for an interface that contains classes, Builder Xcessory creates some additional files for your class. These files depend on the language you choose to generate.

C files

If you generate C files, Builder Xcessory generates two new files for each class in your interface. For this example, it generates SelectDialog.c and SelectDialog.h .

The SelectDialog.h file defines a structure that contains the widgets in your class as well as any data members or methods you defined. In SelectDialog.c the class widgets are created and their default resources are set.

C++ files

If you generate C++ code, Builder Xcessory generates files for each class in your interface.

For this example, it generates SelectDialog.C and SelectDialog.h .

The SelectDialog.C and SelectDialog.h files are similar to the SelectDialog.c and SelectDialog.h files generated for C code.

SelectDialog.h defines the class SelectDialog containing all the widget instances and data members or methods you defined.

In SelectDialog.C the class widgets and their default resources are set in the class constructor.

Editing the Callback Structures

C files

If you have generated C files, load the callbacks-c.c file into your editor. If you have questions about this procedure, refer to Setting Callback Resources .

  1. At the top of the file, add this line:
  2. #include "SelectDialog.h"
  3. Within the procedure Selector, after the line:
  4. XmAnyCallbackStruct
    *acs=(XmAnyCallbackStruct*)call_data;
    insert the lines:
    XmListCallbackStruct *list_call =
    (XmListCallbackStruct*) call_data;
    SelectDialogDataPtr
    select = (SelectDialogDataPtr) client_data;
    XtVaSetValues(select->answer,
    XmNlabelString, list_call->item, NULL);
  5. Save and close the file.

C++ files

If you have generated C++ files, load the file SelectDialog.C into your editor. If you have questions about this procedure, refer to Setting Callback Resources .

  1. At the top of the file in the user code block <head>, add this line:
  2. #include <Xm/Xm.h>
  3. Within the user code block, inside the method Selector, add the following lines:
  4. XmListCallbackStruct *list_call =
    (XmListCallbackSruct*)call_data;
    XtVaSetValues(_answer,XmNlabelString,
    list_call->item, NULL);
  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 .

You have now completed Tutorial Seven.

UpPreviousNext