Generic UI Controllers: 4.2 Creating Your Own Controllers: Subclassing GenControlClass

4.1 GenControlClass Instance Data | Next:

When creating your own controller, you must subclass GenControlClass . You must also follow the steps outlined below (each is described in more detail throughout this section):

Define the features and tool records
You must define records and flags for the entire feature set and tool set of the controller. Each bit in one of these records corresponds to a single feature or tool of the controller; by turning these bits on and off, the controller manages which features and tools are available to the user. See Defining a Controller's Feature and Tool Sets .
Define the default UI configuration
Define a resource block containing the objects that will be the controller's default UI representation (typically a menu structure). See Defining the Default UI and Tool Configurations .
Define the tool configuration
Define a resource block containing generic UI objects that will make up the controller's tool set. See Defining the Default UI and Tool Configurations .
Handle MSG_GEN_CONTROL_GET_INFO Every controller must handle this message and return critical information about the controller, its features, and its tools. This is the most involved step of creating a controller. See Mandatory Message Handling .
Intercept appropriate GenControlClass messages
Different controller classes will intercept different GenControlClass messages depending on how much additional functionality they require. Most controllers will intercept MSG_GEN_CONTROL_UPDATE_UI .
Define and handle controller-specific messages
Some controllers will set up their features and tools so that the messages they generate require some translation. For example, if a controller has one feature that sets a value based on all the other values, that feature may send a "set" message to the controller, which will determine the appropriate value to set. The controller will then pass the result on to the output object.

Defining a Controller's Feature and Tool Sets

E very controller must have a definition of all its features and tools. This definition typically resides in the controller class header file (in this case, psCtrl.goh ). Applications that use the controller must be able to turn on and off individual tools and features. These definitions take the form of records in which each bit represents a particular feature or tool. No controller may have more than sixteen features or tools; the controller has just one word representing which features and tools are "on."

To define the feature set of your controller class, define a record type of type WordFlags and one flag for each feature. The record type you define may be named anything; typically, however, its name will consist of the acronym of the controller class with the suffix "Features." For example, the features type and flags of PointSizeControlClass are shown below:

 typedef WordFlags PSCFeatures;
#define PSCF_10				0x0400
#define PSCF_12				0x0200
#define PSCF_14				0x0100
#define PSCF_18				0x0080
#define PSCF_24				0x0040
#define PSCF_36				0x0020
#define PSCF_54				0x0010
#define PSCF_72				0x0008
#define PSCF_SMALLER				0x0004
#define PSCF_LARGER				0x0002
#define PSCF_CUSTOM_SIZE 0x0001

Each of the flags represents one feature of the controller. For example, the PSCF_10 flag represents the "10 Point" trigger in the Sizes menu, and the PSCF_SMALLER flag represents the "Smaller" trigger. When a flag is set, the feature it represents is turned on; when clear, its feature is off.

Each controller class must create a similar record type and flags for its tool set. Because the tools are independent of the default features, two different sets of flags must be defined. An example (the PSCToolboxFeatures record of PointSizeControlClass ) follows.

 typedef WordFlags PSCToolboxFeatures;

#define PSCTF_9				0x0400
#define PSCTF_10				0x0200
#define PSCTF_12				0x0100
#define PSCTF_14				0x0080
#define PSCTF_18				0x0040
#define PSCTF_24				0x0020
#define PSCTF_36				0x0010
#define PSCTF_54				0x0008
#define PSCTF_72				0x0004
#define PSCTF_SMALLER				0x0002
#define PSCTF_LARGER				0x0001

After you have defined your controller class' feature and tool sets, you should define the controller's default feature and tool sets. The definitions for PointSizeControlClass are shown below:

#define PSC_DEFAULT_FEATURES					(PSCF_9 | PSCF_10 |
		PSCF_12 | PSCF_14 | PSCF_18 | PSCF_24 |
		PSCF_36 | PSCF_72 | PSCF_CUSTOM_SIZE |
		PSCF_SMALLER | PSCF_LARGER)

#define PSC_DEFAULT_TOOLBOX_FEATURES (PSCTF_9 |
		PSCTF_10 | PSCTF_12 | PSCTF_14 |
		PSCTF_18 | PSCTF_24 | PSCTF_36 |
		PSCTF_72 | PSCTF_SMALLER | PSCTF_LARGER)

These values and flags will be used in your handler for the controller message MSG_GEN_CONTROL_GET_INFO .

Defining the Default UI and Tool Configurations

After you have determined which features and tools your controller class will support, you must create the UI objects that correspond to them. To do this, declare two separate resource segments--one to contain the feature objects and the other to contain the tool objects. Then declare a third that contains just chunks with text strings in it.

Both resources should be defined notDetachable , meaning that the feature and tool objects will not be saved to a state file. In the global parameters file for your controller, each resource must be declared with the ui-object , read-only , and shared flags as below:

resource SIZECTRLUI ui-object read-only shared
resource SIZECTRLTOOLUI ui-object read-only shared
resource CONTROLSTRINGS lmem read-only shared

The UI resources typically contain list objects and their corresponding items. As an alternative, they can contain triggers and dialogs. These objects are declared as a standard object resource with generic objects, as shown in Controller UI Resources . All these objects must be set not usable (~GS_USABLE).

Code Display 12-7 Controller UI Resources

/* This display contains only code that appears in the psCtrl.goc file. The first
 * elements of the file are other included files, followed by a class declaration
 * statement. The two UI resources are shown after that, simplified somewhat;
 * Only redundant objects are left out of the display. */

/* Include the controller class definition and declare the class structure. */
@include <psCtrl.goh>
@classdecl PointSizeControlClass;

@start	SizeCtrlUI, notDetachable;

/* Define the features UI resource. This resource can contain any objects that may
 * typically appear in a menu (e.g. GenInteractions, GenTriggers, and list
 * objects). This example shows a single list object and a few of its entries. */

@object GenItemGroupClass SizesList = {
    GI_states = @default & ~GS_USABLE;					/* Set the list not usable */
	/* The children of the list are defined below. Each entry in the
	 * list will appear as a single menu item. */
    GI_comp =		@Size10Entry, @Size12Entry, @Size14Entry, @Size18Entry,
		@Size24Entry, @Size36Entry, @Size54Entry, @Size72Entry;
	/* The "apply" message will be sent to the destination specified
	 * in the GIGI_destination field. */
    GIGI_applyMsg = MSG_PSC_SET_POINT_SIZE_FROM_LIST;
	/* The destination is defined as the TravelOption TO_OBJ_BLOCK_OUTPUT.
	 * This will send the apply message to the controller's output object. */
    GIGI_destination = (TO_OBJ_BLOCK_OUTPUT);
}

/* An example of a GenItem for the above list. all the other children are similar
 * with different monikers and identifiers. The identifiers in this case are
 * equivalent to the point size setting for the feature. */
@object GenItemClass Size10Entry = {
    GI_visMoniker = `1', "1. 10 point";
    GII_identifier = 10;
}

/* A GenTrigger. Shown below is the "Smaller" menu entry of the Point Size
 * controller. Another trigger ("Larger") and a GenInteraction (the "Custom
 * Size" entry) are also declared. These objects do not have to be declared
 * as children of any object; they will automatically, like the list above,
 * be designated as children of the controller when it is initialized.
 * Note that all of these objects must also be set not usable. */
@object GenTriggerClass SmallerTrigger = {
    GI_states = @default & ~GS_USABLE;
    GI_visMoniker = `S', "Smaller";
    GI_kbdAccelerator = control `9';
    GTI_actionMsg = MSG_PSC_SMALLER_POINT_SIZE;
    GTI_destination = (TO_OBJ_BLOCK_OUTPUT);
}

@end	SizeCtrlUI

/* Define the Tools UI resource. This follows exactly the same rules as the
 * Features UI resource above, but it represents the UI gadgetry that will appear
 * in the controller's tool boxes rather than its default menus. */

@start	SizeCtrlToolUI, notDetachable;

@object GenItemGroupClass SizesToolList = {
    /* Same as SizesList above, but with the following hints applied: */
    HINT_ITEM_GROUP_MINIMIZE_SIZE;
    HINT_ITEM_GROUP_DISPLAY_CURRENT_SELECTION;
}

/* The list entry items have the exact configuration as above but different
 * names that reflect their tool usage.
 * The only objects allowed as tools for the Point Size controller are the
 * point size list entries, the larger trigger, and the smaller trigger. The
 * "Custom Size" entry is not allowed in the tool box as a matter of style. */

@object GenTriggerClass SmallerToolTrigger = {
    GI_states = @default & ~GS_USABLE;
    GI_visMoniker = "S";
	/* The moniker of a tool is typically a graphic. The moniker
	 * specified here is text for simplicity. */
    GTI_actionMsg = MSG_PSC_SMALLER_POINT_SIZE;
    GTI_destination = TO_OBJ_BLOCK_OUTPUT;
}

@end	SizeCtrlToolUI

@start	ControlStrings;

/* In addition to the above two resources, you must also create a third that
 * contains name strings for the various tools and features. These name strings
 * will be used by the GenToolControl to identify the feature type in its
 * dialog box. */
@chunk char		PSCName[] = "Point Size";
@chunk char		Size10Name[] = "10 Point";
@chunk char		Size12Name[] = "12 Point";
    /* The rest of the point sizes are similar */
@chunk char		SmallerName[] = "Smaller Point Size";
@chunk char		LargerName[] = "Larger Point Size";
@chunk char		CustomSizeName[] = "Custom Point Size";

@end	ControlStrings

Mandatory Message Handling

 MSG_GEN_CONTROL_GET_INFO, GenControlBuildInfo

Every controller must handle MSG_GEN_CONTROL_GET_INFO . This message is sent to the controller in several circumstances, and it must return critical information about the controller's state and configuration. It takes a pointer to an empty GenControlBuildInfo structure and must fill in all the structure's fields before returning. This structure is shown in MSG_GEN_CONTROL_GET_INFO Handler with a description of each of its fields following.

Code Display 12-8 The GenControlBuildInfo Structure

 /* This structure must be filled and returned by the controller class. It details
 * general information as well as specific information about the controller, the
 * controller's features, and the controller's tools. */

typedef struct {
    GenControlBuildFlags				GCBI_flags;
    const char				*GCBI_initFileKey;
    const GCNListType				*GCBI_gcnList;
    word				GCBI_gcnCount;
    const NotificationType				*GCBI_notificationList;
    word				GCBI_notificationCount;
    optr				GCBI_controllerName;

    MemHandle				GCBI_dupBlock;
    const GenControlChildInfo				*GCBI_childList;
    word				GCBI_childCount;
    const GenControlFeaturesInfo				*GCBI_featuresList;
    word				GCBI_featuresCount;
    WordFlags				GCBI_features;

    MemHandle				GCBI_toolBlock;
    const GenControlChildInfo				*GCBI_toolList;
    word				GCBI_toolCount;
    const GenControlFeaturesInfo				*GCBI_toolFeaturesList;
    word				GCBI_toolFeaturesCount;
    WordFlags				GCBI_toolFeatures;

    char				*GCBI_helpContext;
    byte				GCBI_reserved[8];
} GenControlBuildInfo;

The following fields define general information about the controller.

GCBI_flags: A record of GenControlBuildFlags . These flags affect several UI-related and object storage related functions, and they are detailed on GenControlBuildFlags .
GCBI_initFileKey: A pointer to a text string indicating the controller's key in the GEOS.INI file. Controller options will be saved under this key.
GCBI_gcnList: A pointer to a list of GCN list types. Objects of this controller class will be added to these GCN lists and will receive notification from them. GCN lists are detailed in the GCN chapter.
GCBI_gcnCount The length of the list pointed to by GCBI_gcnList above. This length should be the number of lists specified.
GCBI_notificationList A pointer to a list of notification types supported by the controller.
GCBI_notificationCount: The size of the list pointed to by GCBI_notificationList above.
GCBI_controllerName: The optr of a chunk containing the text string that serves as the controller's name. This name string is displayed by the GenToolControl in its dialog box to identify the controller.

The following fields define information about the controller's features. These fields will be filled dependent on the features set in the object's instance data and the UI level of the controller.

GCBI_dupBlock: The handle of the resource block containing the controller's feature generic objects. In the example, this would contain the handle of the SizeCtrlUI resource.
GCBI_childList: A pointer to a list of GenControlChildInfo structures; each of these structures details which features are set and which should always be set for each of the controller's children. This structure is shown below:
: Each structure contains the chunk handle of the given child in t he resource block, a feature mask indicating which features are possibly supported by the child, and a record indicating whether the child is a feature or not and whether the child is always added to the controller's UI. More specific information is shown on GenControlChildInfo .
GCBI_childCount: The number of children specified in GCBI_childList above.
GCBI_featuresList: A pointer to a list of GenControlFeaturesInfo structures, one for each child. These structures define the following:
: The three fields are the chunk handle of the child; the optr of the child's name string, as defined in the name string resource; and a record of GenControlFeatureFlags . This structure and its fields are described more fully on GenControlFeaturesInfo .
GCBI_featuresCount: The number of GenControlFeaturesInfo structures listed in GCBI_featuresList above.
GCBI_features: A features mask describing the features supported by the current UI level as specified in the GenApplication's GAI_appFeatures field.

The following fields describe information about the controller's tools and their configuration.

GCBI_toolBlock: The handle of the resource block containing the controller's tool generic objects. In the example, this would contain the handle of the SizeCtrlToolUI resource.
GCBI_toolList: A pointer to a list of GenControlChildInfo structures; each of these structures details which tools are set and which should always be set for each of the controller's children. This structure is shown below:
: Each structure contains the chunk handle of the given child in t he resource block, a feature mask indicating which tools are possibly supported by the child, and a record indicating whether the child is a tool or not (e.g. a list) and whether the child is always added to the controller's tool box UI. More specific information is shown on GenControlChildInfo .
GCBI_toolCount: The number of children specified in GCBI_toolList above.
GCBI_toolFeaturesList: A pointer to a list of GenControlFeaturesInfo structures, one for each child. These structures define the following:
: The three fields are the chunk handle of the child; the optr of the child's name string, as defined in the name string resource; and a record of GenControlFeatureFlags . This structure and its fields are described more fully on GenControlFeaturesInfo .
GCBI_toolFeaturesCount: The number of GenControlFeaturesInfo structures in the list pointed to by GCBI_toolFeaturesList above.
GCBI_toolFeatures: A tools mask describing the tools supported for the UI level specified in the GenApplication's GAI_appFeatures field.

The following field is used by controllers that offer their own help files and help text.

GCBI_helpContext: A pointer to a character string giving the name of the controller's help context. If this is a non-null pointer, then the controller will automatically add ATTR_GEN_HELP_CONTEXT to itself with the specified string.

The structure also has eight bytes that are reserved for the use of GenControlClass, in the GCBI_reserved field.

GenControlBuildFlags

This flags record defines several UI-related things about the controller object. Set them appropriate to your controller. The flags are

GCBF_SUSPEND_ON_APPLY: Causes MSG_META_SUSPEND to be sent on feature activation and MSG_META_UNSUSPEND afterward. This is often set by controllers.
GCBF_USE_GEN_DESTROY: Ensures that unused objects can not be freed with LMemFree() . Not often set by controllers.
GCBF_SPECIFIC_UI: Indicates that the controller may be implemented in the specific UI and therefore some special action must be taken. Very rarely set by controllers.
GCBF_CUSTOM_ENABLE_DISABLE: Indicates that the controller uses a custom enable/disable mechanism rather than responding to GCN notifications.
GCBF_ALWAYS_UPDATE: Indicates that the controller should always undergo visual updates even if it appears unnecessary. Not often set by controllers.
GCBF_EXPAND_TOOL_WIDTH_TO_FIT_PARENT: Indicates that the tool width should be expanded to take full advantage of all the space available in the parent composite.
GCBF_ALWAYS_INTERACTABLE: Indicates that the controller should always be on its appropriate GCN lists, even if no part of it is visible. This flag requires GCBF_IS_ON_ACTIVE_LIST.
GCBF_ALWAYS_ON_GCN_LIST: Indicates that the controller should constantly be on the GCN lists rather than periodically adding and removing itself as is done in some optimization code. Not often set by controllers. This flag requires GCBF_IS_ON_ACTIVE_LIST.
GCBF_MANUALLY_REMOVE_FROM_ACTIVE_LIST: Indicates that the controller should not remove itself from the active list in its default detach handler.
GCBF_IS_ON_ACTIVE_LIST: Indicates that the controller is on the active list in its .goh file definition.
GCBF_IS_ON_START_LOAD_OPTIONS_LIST: Indicates this controller must be on the startup load options list.
GCBF_NOT_REQUIRED_TO_BE_ON_SELF_LOAD_OPTIONS_LIST: Indicates this controller is not required to be on any options-load list.

GenControlChildInfo

The GenControlChildInfo structure defines the features or tools appropriate to each object in a controller's UI resources. It has the following structure, and its fields are described below:

typedef struct {
	ChunkHandle				GCCI_object;
	WordFlags				GCCI_featureMask;
	GenControlChildFlags				GCCI_flags;
}  GenControlChildInfo;

GCCI_object: The chunk handle of the object in the appropriate resource.
GCCI_featureMask: The feature mask representing the feature set represented by the object.
GCCI_flags: A record of GenControlChildFlags , the flags of which are described below.

The GenControlChildFlags flags are

GCCF_NOTIFY_WHEN_ADDING: This flag indicates that the child will be notified before the feature is added and set usable with MSG_GEN_CONTROL_NOTIFY_ADDING_FEATURE .
GCCF_ALWAYS_ADD: This flag indicates that the child object should always be added to the controller's UI, even if it is not specified.
GCCF_IS_DIRECTLY_A_FEATURE: This flag indicates that the child is a feature in itself and thus on the feature list. This is typically set for most objects. (It is not set, for example, for list objects, whose children are the actual features.)

GenControlFeaturesInfo

The GenControlFeaturesInfo structure describes each UI feature's name and certain flags. The structure is defined below, and its fields are described following:

typedef struct {
	ChunkHandle				GCFI_object;
	optr				GCFI_name;
	GenControlFeatureFlags				GCFI_flags;
}  GenControlFeaturesInfo;

GCFI_object: The chunk handle of the child in the appropriate resource block.
GCFI_name: The optr of the chunk containing the object's name. This name is used by the GenToolControl to represent the particular feature or tool in its dialog box.
GCFI_flags: A record of GenControlFeatureFlags , reserved.

MSG_GEN_CONTROL_GET_INFO

void	MSG_GEN_CONTROL_GET_INFO(
        GenControlBuildInfo *info);

This message must be handled by all controllers. It takes an empty GenControlBuildInfo structure and fills it; this message is called in several circumstances by different objects and controller methods.

Source: Unrestricted--typically generated in GenControlClass methods.

Destination: Any controller object.

Parameters: info A pointer to an empty GenControlBuildInfo structure.

Return: The GenControlBuildInfo structure filled with the appropriate controller information.

Interception: Every controller class must intercept this message. There is no need to call the superclass anywhere in the handler.

Code Display 12-9 MSG_GEN_CONTROL_GET_INFO Handler

/* This method is a sample of how to handle MSG_GEN_CONTROL_GET_INFO. It is
 * specific to UICTextStyleControlClass. To handle this message, it is easiest to
 * set up a number of static local variables with the base information and set
 * the structure to these variables. */

/* Handler for MSG_GEN_CONTROL_GET_INFO
 * void (GenControlBuildInfo *info);					*/

@method UICTextStyleControlClass, MSG_GEN_CONTROL_GET_INFO {

	/* General information constants */

 static const char TSC_IniFileKey[] = "textStyleControl";

 static const GCNListType TSC_gcnList[] = {
 	{MANUFACTURER_ID_GEOWORKS, GAGCNLT_APP_TARGET_NOTIFY_TEXT_CHAR_ATTR_CHANGE}
 };

 static const NotificationType TSC_notifyTypeList[] = {
 	{MANUFACTURER_ID_GEOWORKS, GWNT_TEXT_CHAR_ATTR_CHANGE}
 };

	/* Features information constants */

    static const  GenControlChildInfo TSC_childList[] = {
	{@PlainTextList, TSCF_PLAIN, GCCF_IS_DIRECTLY_A_FEATURE},
	{@TextStyleList, TSCF_BOLD|TSCF_ITALIC|TSCF_UNDERLINE|TSCF_STRIKE_THRU| 
	 TSCF_SUBSCRIPT|TSCF_SUPERSCRIPT, 0}

};

	/* The order of this list is actually backwards from the
	 * record it reflects. */
    static const  GenControlFeaturesInfo TSC_featuresList[] = {
	 {@SuperscriptEntry, @SuperscriptName, 0},
 	{@SubscriptEntry, @SubscriptName, 0},
 	{@StrikeThruEntry, @StrikeThruName, 0},
 	{@UnderlineEntry, @UnderlineName, 0},
 	{@ItalicEntry, @ItalicName, 0},
 	{@BoldEntry, @BoldName, 0},
 	{@PlainTextList, @PlainTextName, 0}
    };

	/* Tools information constants */

    static const GenControlChildInfo TSC_toolList[] = {
 	{@PlainTextToolList, TSCTF_PLAIN, GCCF_IS_DIRECTLY_A_FEATURE},
 	{@TextStyleToolList, TSCTF_BOLD|TSCTF_ITALIC|TSCTF_UNDERLINE|
	 TSCTF_STRIKE_THRU|TSCTF_SUBSCRIPT|TSCTF_SUPERSCRIPT, 0} };
    };

    static const GenControlFeaturesInfo TSC_toolFeaturesList[] = {
 	{@SuperscriptToolEntry, @SuperscriptName, 0},
 	{@SubscriptToolEntry, @SubscriptName, 0},
 	{@StrikeThruToolEntry, @StrikeThruName, 0},
 	{@UnderlineToolEntry, @UnderlineName, 0},
 	{@ItalicToolEntry, @ItalicName, 0},
 	{@BoldToolEntry, @BoldName, 0},
 	{@PlainTextToolList, @PlainTextName, 0}
    };

	/* Our constant for the GenControlBuildInfo structure.
	 * Fields with a marker to the left of their names are
	 * filled in dynamically by the handler following the
	 * constant definition. */
    static const  GenControlBuildInfo TSC_dupInfo = {
	GCBF_SUSPEND_ON_APPLY, 					/* GCBI_flags */
 	TSC_IniFileKey, 					/* GCBI_initFileKey */
 	TSC_gcnList, 					/* GCBI_gcnList */
 	ARRAY_LEN(TSC_gcnList,GCNListType), 					/* GCBI_gcnCount */
 	TSC_notifyTypeList, 					/* GCBI_notificationList */
 	ARRAY_LEN(TSC_notifyTypeList, NotificationType), 
						/* GCBI_notificationCount */
 	@TSCName, 					/* GCBI_controllerName */ 

 	/* ## */ NullHandle, 					/* GCBI_dupBlock */
 	TSC_childList, 					/* GCBI_childList */
 	ARRAY_LEN(TSC_childList, GenControlChildInfo),
 						/* GCBI_childCount */
 	TSC_featuresList, 					/* GCBI_featuresList */
 	ARRAY_LEN(TSC_featuresList, GenControlFeaturesInfo),
 						/* GCBI_featuresCount */
 	TSC_DEFAULT_FEATURES, 					/* GCBI_features */
 	/* ## */ NullHandle, 					/* GCBI_toolBlock */
 	TSC_toolList, 					/* GCBI_toolList */
 	ARRAY_LEN(TSC_toolList, GenControlChildInfo),
 						/* GCBI_toolCount */
 	TSC_toolFeaturesList, 					/* GCBI_toolFeaturesList */
 	ARRAY_LEN(TSC_toolFeaturesList, GenControlFeaturesInfo),
 						/* GCBI_toolFeaturesCount */
 	TSC_DEFAULT_TOOLBOX_FEATURES 					/* GCBI_toolFeatures */
    };

	/* Here is the code that fills in the above missing fields and
	 * returns the proper structure. */

    /* Copy the structure containing most of the correct information. */
    memcpy(info, MemLockFixedOrMovable(&TSC_dupInfo), sizeof(GenControlBuildInfo));
    MemUnlockFixedOrMovable(&TSC_dupInfo);

    /* Fill the remaining fields in manually. */
    info->GCBI_dupBlock = HandleOf(@PlainTextList);
    info->GCBI_toolBlock = HandleOf(@PlainTextToolList); 
}

GEOS SDK TechDocs |

4.1 GenControlClass Instance Data | Next:

4.3 Advanced GenControlClass Usage