Generic UI Controllers: 3.1 Using Controllers: Using a Basic GenControl Object

| Up: GEOS SDK TechDocs | Up | Prev: 3 Using Controllers | Next: 3.2 Using Tools

To use a typical controller, you have to set up its instance data appropriately and set up the generic tree properly. This section describes the basics of GenControlClass instance data; for full information on GenControlClass , see Creating Your Own Controllers .

Every controller has a default set of features and a default set of tools. When you use a controller in your application, you can use the default configuration, the configuration appropriate to the application's user level, or a specific configuration. Most applications will want to use the second option; the controller queries the GenApplication object for its GAI_appFeatures record and determines from that which of its features and tools should be active.

Controllers can be manifested in any way the specific UI determines appropriate; three main ways, however, are menus or submenus, floating tool boxes (dialogs), and groupings along a tool bar in a window. These three modes correspond to the three manifestations of a typical GenInteraction object: GIV_POPUP (menus), GIV_DIALOG (dialogs and tool boxes), and GIV_SUB_GROUP (groupings of other generic objects). If you use a GenToolControl, you can let the user decide how the controller is displayed; otherwise, you will have to set it manually (as in the samples previously).

Every controller also has two sets of UI objects: The first set represents the UI objects used for menu entries (when the controller is in GIV_POPUP mode). The second set represents the tools that appear in a tool box (GIV_DIALOG mode) or tool bar (GIV_SUB_GROUP mode). Tools are almost always functionally redundant to the "menu" feature set. Because the tool and the menu UI resources contain different objects, the UI objects can exist in any combination of interactable states--for example, a particular feature could be in the menu only, in the tool box only, in both, or in neither. The feature can not, however, be in both a tool bar and a tool box at the same time because the set of tools can be grouped in only one location.

Using Normal Features

ATTR_GEN_CONTROL_REQUIRE_UI, ATTR_GEN_CONTROL_PROHIBIT_UI

GenControlClass has no controller features of its own; instead, each controller class must define the features it supports in both the menu implementation and the tool implementation. Any controller object is free to determine which of the features it will support and which it will not.

To set individual features on or off for a controller object in your application, use the vardata fields ATTR_GEN_CONTROL_REQUIRE_UI and ATTR_GEN_CONTROL_PROHIBIT_UI ; these specify which features will be on and which will be off. For listings of a controller class' features, you must see the description of the individual class.

The example in Declaring a Controller's Features extends the example from earlier in the chapter to turn on only the 10-, 12-, and 24-point as well as the "Larger" and "Smaller" features. It turns off all other features.

Code Display 12-2 Declaring a Controller's Features

/* This example is based on that of  A Sample Controller Application (psctext.goc). It shows what
 * would change in order to turn on only the 10-, 12-, and 24-point as well as the
 * "Larger" and "Smaller" features. Note that only the Controller object must
 * be altered. */
@object PointSizeControlClass PSCTSizeControl = {
    GI_visMoniker = 'z', "Sizes";					/* Give the controller a name */
    GII_visibility = GIV_POPUP;					/* Make the controller a menu */
	/* The following attribute defines which of the controller's
	 * features are to be supported. These menu items will appear
	 * in the controller's Size menu. */
    ATTR_GEN_CONTROL_REQUIRE_UI = (PSCF_10 | PSCF_12 | PSCF_24 |
				PSCF_SMALLER | PSCF_LARGER);
	/* The following attribute defines which of the controller's
	 * features will not be supported. These menu items will not
	 * appear in the controller's Size menu. */
    ATTR_GEN_CONTROL_PROHIBIT_UI = (PSCF_14 | PSCF_18 | PSCF_36 | PSCF_54 |
				 PSCF_72 | PSCF_CUSTOM_SIZE);
}

Adding Application-Specific UI Gadgetry

ATTR_GEN_CONTROL_APP_UI, ATTR_GEN_CONTROL_APP_TOOLBOX_UI

Occasionally, an application will want to add its own UI gadgetry to a controller. This is not the same as changing the controller's functionality--to do that, you would need to subclass the controller class. Rather, this entails simply specifying a group of generic UI objects (e.g. a GenInteraction and some GenTriggers) that will be included with the controller's UI objects.

The GenControlClass vardata attribute ATTR_GEN_CONTROL_APP_UI allows you to specify a generic tree that will be added as a child of the controller. The top node of this tree must be an object that can be a child of a GenInteraction object--typically, it will be a GenInteraction, a GenTrigger, or a GenValue.

For example, if you wanted the sample application to have two extra triggers added to the Size menu, you would use ATTR_GEN_CONTROL_APP_UI as shown in Adding UI to a Controller . This example adds two triggers that turn the bottom GenText object on and off. (Of course, you would not likely put such functionality in the Size menu; this is given for illustration.)

This attribute has no effect on the tools managed by the controller, only on its features. To add application-specific tools to a controller, you must use ATTR_GEN_CONTROL_APP_TOOLBOX_UI .

Code Display 12-3 Adding UI to a Controller

/* This display shows the modified PointSizeControl object and the additional
 * UI gadgetry required to add two triggers to it. Although the triggers are
 * shown here in the same resource block as the controller, they do not have to
 * be. They do, however, have to be run by the same thread as the controller. */
@object PointSizeControlClass PSCTSizeControl = {
    GI_visMoniker = 'z', "Sizes";					/* Give the controller a name */
    GII_visibility = GIV_POPUP;					/* Make the controller a menu */
	/* The following attribute specifies the top object of a generic
	 * tree to be included with the controller's UI. This attribute does
	 * not affect the toolbar implementation of the controller. */
    ATTR_GEN_CONTROL_APP_UI = (@PSCTSpecialTrigs);						/* must be an optr */
}
/* This GenInteraction and its children (the two GenTriggers) will be included in
 * the controller's default representation (typically a menu). The GenInteraction
 * will appear as a submenu in OSF/Motif. All of the objects must be set not
 * usable (~GS_USABLE); they will be made usable by the controller when it becomes
 * usable. */
@object GenInteractionClass PSCTSpecialTrigs = {
    GI_comp = @PSCTEnableTrig, @PSCTDisableTrig;
    GI_states = @default & ~GS_USABLE;
    GII_visibility = GIV_POPUP;					/* Appear as a submenu-type item */
}
/* The triggers set the bottom GenText object usable or not usable. The instance
 * data of the triggers is unimportant for this example, but it is shown here
 * to complete the example. */
@object GenTriggerClass PSCTEnableTrig = {
    GI_visMoniker = "Use Two Text Fields";
    GI_states = @default & ~GS_USABLE;
    GTI_actionMsg = MSG_GEN_SET_USABLE;
    GTI_destination = PSCBotTextObj;
    ATTR_GEN_TRIGGER_ACTION_DATA = (VUM_NOW);
}
@object GenTriggerClass PSCTDisableTrig = {
    GI_visMoniker = "Use One Text Field";
    GI_states = @default & ~GS_USABLE;
    GTI_actionMsg = MSG_GEN_SET_NOT_USABLE;
    GTI_destination = PSCBotTextObj;
    ATTR_GEN_TRIGGER_ACTION_DATA = (VUM_NOW);
}
| Up: GEOS SDK TechDocs | Up | Prev: 3 Using Controllers | Next: 3.2 Using Tools