Tutorial Seven: Classes

 

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

If you have questions about this procedure, review Creating and Resizing a Widget Instance .
If you have questions about this procedure, review Setting a Resource .
It should be about half the width of the Form.
It should be about half as wide as the Form. Set the Instance Name field in the Resource Editor to "question".
  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. Place a Label widget across the top of the Form. Set the Instance Name field in the Resource Editor to "title".
  4. Place a ScrolledList widget down the left side of the Form and under the Label.
  5. Add another Label on the right side of the Form under the first Label.
  6. Add a Frame under the Label, and resize it to be the same width as the Label.
  7. 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

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

  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 .

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.

A popup dialog prompts you for the name of the class.
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.
  1. Select the top-most widget, the Form, and select Make Class from the Browser Edit menu.
  2. Enter "SelectDialog" in the dialog.

Editing a Class

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.
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.
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() .
  1. Switch to Classes view by clicking on the arrow button at the left of the Browser and selecting Classes.
  2. Select the Title widget and set the labelString resource to "Select Dialog".
  3. The resource setting of the labelString resource should be set to Code. Pull down the option menu and click on Expose.
  4. Select the Question widget, and set the labelString resource to "The item selected is..." and its resource setting to Code. Expose the resource.
  5. Select the List widget and set the following resources to these resource values (and resource settings):

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.

The Browser now displays the object instance hierarchy of your interface, including all instances of your class. You can easily create another class instance.
You access the Storage Location dialog from the Resource Editor Component menu.
  1. Switch back to Instances view.
  2. Scroll the Palette until the SelectDialog class comes into view.
  3. Create an instance of SelectDialog by selecting it on the Palette and dragging it to your display.
  4. Set the Instance Name field on the Resource Editor to "selectItem" for the first class instance and "selectBuilder" for the second class instance.
  5. 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.

Editing a Class Instance

To edit an instance of your class:

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.
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:
  1. Update the Resource Editor for selectItem.
  2. Set the following values:

Edited Class Instance

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

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 .

#include "SelectDialog.h"
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);
  1. At the top of the file, add this line:
  2. Within the procedure Selector, after the line:
  3. 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 .

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

 

Documentation Type: