Generic UI Controllers: 4.3 Creating Your Own Controllers: Advanced GenControlClass Usage

Everything you need to create a basic custom controller class is detailed in the previous sections. GenControlClass , however, has a number of messages and structures that will be used by some subclasses, though this will be relatively rare. This section details these messages and structures.

Adding and Removing UI Gadgetry

MSG_GEN_CONTROL_GENERATE_UI, MSG_GEN_CONTROL_DESTROY_UI, MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI, MSG_GEN_CONTROL_DESTROY_TOOLBOX_UI, MSG_GEN_CONTROL_UPDATE_UI, MSG_GEN_CONTROL_ENABLE_DISABLE, MSG_GEN_CONTROL_ADD_APP_UI, MSG_GEN_CONTROL_ADD_APP_TOOLBOX_UI, MSG_GEN_CONTROL_REBUILD_NORMAL_UI, MSG_GEN_CONTROL_REBUILD_TOOLBOX_UI

GenControlClass has several messages that add, remove, and manipulate the controller UI gadgetry. Keep in mind also that, as a subclass of GenInteractionClass and thereby of GenClass , the GenControl also can use any of the generic UI messages for object tree manipulation. These messages are detailed in the following list.

MSG_GEN_CONTROL_GENERATE_UI

void	MSG_GEN_CONTROL_GENERATE_UI();

This message generates the UI gadgetry for the controller.

Source: Unrestricted--sent by self as part of specific UI build.

Destination: Any GenControl object

Interception: If subclassed to add functionality, the subclass must call the superclass at the beginning of the handler.

Warnings: If you intercept this message, you should also intercept MSG_GEN_CONTROL_DESTROY_UI , below.

MSG_GEN_CONTROL_DESTROY_UI

void	MSG_GEN_CONTROL_DESTROY_UI();

This message destroys the UI gadgetry for the controller.

Source: Unrestricted--sent by self when being taken off the screen.

Destination: Any GenControl object

Interception: Any subclass that intercepts MSG_GEN_CONTROL_GENERATE_UI must intercept this. The subclass must call the superclass at the end of the handler.

MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI

void	MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI(
        optr	parent);

This message generates the UI gadgetry for the controller's tool box.

Source: Sent by tool box object via the active list as part of its specific UI build mechanism.

Destination: The GenControl object that owns the tool box.

Parameters: parent The optr of GenInteraction that will be the parent of the controller's tools.

Return: Nothing.

Interception: A subclass may intercept this to add UI gadgetry to the toolbox when the toolbox is built. The subclass must call the superclass at the beginning of the handler.

Warnings: Any controller that subclasses this message must also subclass MSG_GEN_CONTROL_DESTROY_TOOLBOX_UI as well.

MSG_GEN_CONTROL_DESTROY_TOOLBOX_UI

void	MSG_GEN_CONTROL_DESTROY_TOOLBOX_UI();

This message destroys all toolbox UI associated with the controller.

Source: Sent by the tool box being destroyed as part of its specific UI destruction mechanism.

Destination: The GenControl object that owns the tool box.

Interception: Any controller class that subclasses the message MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI must also subclass this message. The subclass must call its superclass at the end of its handler.

MSG_GEN_CONTROL_UPDATE_UI

void	MSG_GEN_CONTROL_UPDATE_UI(@stack
        MemHandle		toolBlock,
        MemHandle		childBlock,
        WordFlags		toolboxFeatures,
        WordFlags		features,
        MemHandle		data,
        word		changeID,
        ManufacturerID		manufID);

This message updates all UI components for the recipient controller.

Source: Sent by GenControlClass in its default handler for MSG_META_NOTIFY_WITH_DATA_BLOCK.

Destination: The GenControl object being updated.

Parameters: toolBlock Handle of the object resource block containing the controller's tool UI gadgetry.

childBlock: Handle of the object resource block containing the controller's default UI gadgetry. This may be taken from the TEMP_GEN_CONTROL_INSTANCE vardata field.
toolboxFeatures: A record of flags indicating which tools are currently on for the controller. This may be taken from the TEMP_GEN_CONTROL_INSTANCE vardata field. If the toolbox UI is not interactible, then this field will be zero.
features: A record of flags indicating which features are currently on for the controller. This may be taken from the TEMP_GEN_CONTROL_INSTANCE vardata field. If the UI is not interactible, then this field will be zero.
data: The data block handle passed with the notification message.
changeID: The type of update to undergo, as passed with the notification message.
manufID: The manufacturer ID of the notification type passed with the notification message.

Interception: Controllers should intercept this message in order to properly update their UI gadgetry. There is no default handler for this message.

Structures: The TEMP_GEN_CONTROL_INSTANCE vardata field is of type TempGenControlInstance , which has the following structure:

  typedef struct {
	GenControlInteractableFlags
				TGCI_interactableFlags;
	MemHandle			TGCI_childBlock;
	MemHandle			TGCI_toolBlock;
	optr			TGCI_toolParent;
	WordFlags			TGCI_features;
	WordFlags			TGCI_toolboxFeatures;
	GCNListType			TGCI_activeNotificationList;
	GenControlInteractableFlags TGCI_upToDate;
} TempGenControlInstance;

TGCI_interactableFlags: This record describes which, if any, of a controller's UI parts is interactable (visible and usable). Its flags are listed below.
TGCI_childBlock: The handle of the resource block containing the controller's default UI objects.
TGCI_toolBlock: The handle of the resource block containing the tool objects.
TGCI_toolParent: The optr of the object passed with MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI , if any (tools will be added to this object).
TGCI_features: A record of flags indicating which controller features are currently active.
TGCI_toolboxFeatures: A record of flags indicating which controller tools are currently active.
TGCI_activeNotificationList: The notification type currently active.
TGCI_upToDate: The status of GenControlInteractableFlags at the time of the last notification; that is, which portions of the controller's UI were up to date. This is used by the specific UI for drawing optimizations.

The flags for the GenControlInteractableFlags record are listed below:

GCIF_CONTROLLER: This flag indicates the controller object is interactable.
GCIF_TOOLBOX_UI: This flag indicates that some or all of the controller's tool gadgetry is interactable.
GCIF_NORMAL_UI: This flag indicates that some or all of the controller's normal feature gadgetry is interactable.

MSG_GEN_CONTROL_ENABLE_DISABLE

void	MSG_GEN_CONTROL_ENABLE_DISABLE(
        Message		msg;
        VisUpdateMode		updateMode);

This message enables or disables the controller object as well as its default and tool box UI gadgetry.

Source: Sent by GenControlClass to the controller object when it receives MSG_META_NOTIFY_WITH_DATA_BLOCK .

Destination: Sent by controller to itself.

Parameters: msg Either MSG_GEN_SET_ENABLED or MSG_GEN_SET_NOT_ENABLED as appropriate.

updateMode: A VisUpdateMode indicating when the visual update should occur.

Interception: Unlikely--typically should not be intercepted.

MSG_GEN_CONTROL_ADD_APP_UI

void	MSG_GEN_CONTROL_ADD_APP_UI(
        optr	appUI);

This message adds the passed UI object to the controller's generic tree as if it had been originally defined in the default child block. By default, the new object is added as the last child of the controller.

Source: Unrestricted--generated as part of the default functionality of MSG_GEN_CONTROL_GENERATE_UI if the controller has ATTR_GEN_CONTROL_APP_UI set.

Destination: Any GenControl object.

Parameters: appUI The optr of the object to be added.

Interception: Should be intercepted by controllers that wish to add the new object somewhere other than as the last child.

MSG_GEN_CONTROL_ADD_APP_TOOLBOX_UI

void	MSG_GEN_CONTROL_ADD_APP_TOOLBOX_UI(
        optr	appUI);

This message adds the passed UI object to the controller's tool UI gadgetry as if it had been defined as a tool in the tool resource block. By default, the new object is added as the last child of the controller.

Source: Unrestricted--generated as part of the default functionality of MSG_GEN_CONTROL_GENERATE_TOOLBOX_UI if the controller has ATTR_GEN_CONTROL_APP_TOOLBOX_UI set.

Destination: Any GenControl object.

Parameters: appUI The optr of the object to be added.

Interception: Should be intercepted by controllers that wish to add the new object somewhere other than as the last child.

MSG_GEN_CONTROL_REBUILD_NORMAL_UI

void	MSG_GEN_CONTROL_REBUILD_NORMAL_UI();

This message forces the normal UI of the controller to be rebuilt; each component will be visually destroyed and rebuilt.

Source: Unrestricted.

Destination: Any GenControl object.

Interception: Should not be intercepted.

MSG_GEN_CONTROL_REBUILD_TOOLBOX_UI

void	MSG_GEN_CONTROL_REBUILD_TOOLBOX_UI();

This message forces the toolbox UI of the controller to be rebuilt; each component will be visually destroyed and rebuilt.

Source: Unrestricted.

Destination: Any GenControl object.

Interception: Should not be intercepted.

Adding and Removing Features and Tools

MSG_GEN_CONTROL_SCAN_FEATURE_HINTS, MSG_GEN_CONTROL_ADD_FEATURE, MSG_GEN_CONTROL_REMOVE_FEATURE, MSG_GEN_CONTROL_ADD_TOOLBOX_FEATURE, MSG_GEN_CONTROL_REMOVE_TOOLBOX_FEATURE, MSG_GEN_CONTROL_GET_NORMAL_FEATURES, MSG_GEN_CONTROL_GET_TOOLBOX_FEATURES

Besides being able to set and clear features of a given controller, both the controller class and outside agents can dynamically alter the features of a given controller object. GenControlClass has several messages that you can use for this purpose; these messages are detailed below.

MSG_GEN_CONTROL_SCAN_FEATURE_HINTS

void	MSG_GEN_CONTROL_SCAN_FEATURE_HINTS(
        GenControlUIType		type,
        GenControlScanInfo		*info);

This message scans the feature hints set for the controller object to set the required and prohibited features.

Source: Unrestricted--Sent by GenControlClass to itself in numerous circumstances.

Destination: The GenControl object to be scanned.

Parameters: type An indicator whether the normal or tool box UI hints are to be scanned. This should be GCUIT_NORMAL for the normal hints, GCUIT_TOOLBOX for the tool box hints.

info: A pointer to an empty GenControlScanInfo structure to be filled in by the handler. This structure is shown below.

Return: No value is returned directly.

info: The pointer to the GenControlScanInfo structure filled in by the method.

Interception: Should not be intercepted.

Structures: The GenControlScanInfo structure has the following fields:

typedef struct {
	WordFlags		GCSI_userAdded;
	WordFlags		GCSI_userRemoved;
	WordFlags		GCSI_appRequired;
	WordFlags		GCSI_appProhibited;
} GenControlScanInfo;

GCSI_userAdded: A record of features added by the user through the use of the GenToolControl object. This record also reflects the use of MSG_GEN_CONTROL_ADD_FEATURE .
GCSI_userRemoved: A record of features removed by the user through the use of the GenToolControl object.
GCSI_appRequired: A record of features required; this is set for the controller with ATTR_GEN_CONTROL_REQUIRE_TOOLBOX_UI or ATTR_GEN_CONTROL_REQUIRE_UI .
GCSI_appProhibited: A record of features prohibited; this is set for the controller with ATTR_GEN_CONTROL_PROHIBIT_TOOLBOX_UI or ATTR_GEN_CONTROL_PROHIBIT_UI .

MSG_GEN_CONTROL_ADD_FEATURE

void	MSG_GEN_CONTROL_ADD_FEATURE(
        WordFlags featureToAdd);

This message adds a feature to those currently supported by the controller. This is used for the default settings only, not for tool box UI. The controller is destroyed and then rebuilt with the new feature, causing it to be marked for saving to the state file in the new configuration.

Source: Unrestricted.

Destination: Any GenControl object.

Parameters: featureToAdd A feature record with the flag of the feature to be added set.

Interception: Should not be intercepted.

MSG_GEN_CONTROL_REMOVE_FEATURE

void	MSG_GEN_CONTROL_REMOVE_FEATURE
        WordFlags featureToRemove);

This message removes a feature from those currently supported by the controller. It does not affect the active tools. The controller will be marked for saving to the state file in the new configuration; it is destroyed and rebuilt with feature removed.

Source: Unrestricted.

Destination: Any GenControl object.

Parameters: featureToRemove A feature record with the flag of the feature to be removed set.

Interception: Should not be intercepted.

MSG_GEN_CONTROL_ADD_TOOLBOX_FEATURE

void	MSG_GEN_CONTROL_ADD_TOOLBOX_FEATURE(
        WordFlags featureToAdd);

This message adds a tool to those currently supported by the controller. This is used for the tool box settings only, not for the default UI features. The controller is destroyed and then rebuilt with the new tool, causing it to be marked for saving to the state file in the new configuration.

Source: Unrestricted.

Destination: Any GenControl object.

Parameters: featureToAdd A feature record with the flag of the to be added set.

Interception: Should not be intercepted.

MSG_GEN_CONTROL_REMOVE_TOOLBOX_FEATURE

void	MSG_GEN_CONTROL_REMOVE_TOOLBOX_FEATURE(
        WordFlags featureToRemove);

This message removes a tool from those currently supported by the controller. It does not affect the default active feature list. The controller will be marked for saving to the state file in the new configuration; it is destroyed and rebuilt with the tool removed.

Source: Unrestricted.

Destination: Any GenControl object.

Parameters: featureToRemove A feature record with the flag of the tool to be removed set.

Interception: Should not be intercepted.

MSG_GEN_CONTROL_GET_NORMAL_FEATURES

void MSG_GEN_CONTROL_GET_NORMAL_FEATURES(
        GenControlGetFeaturesReturn *return);

This message returns a structure indicating which of the default features of the controller are currently active, which are required, and which are prohibited.

Source: Unrestricted--typically GenToolControl.

Destination: Any GenControl object.

Parameters: return A pointer to an empty structure to be returned.

Return: The return parameter, upon return, points to a filled GenControlGetFeaturesReturn structure.

Structures: The GenControlGetFeaturesReturn structure is shown below:

typedef struct {
	WordFlags		GCSR_features;
	WordFlags		GCSR_required;
	WordFlags		GCSR_prohibited;
	WordFlags		GCSR_supported;
} GenControlGetFeaturesReturn;

GCSR_features: A record of flags indicating which features are currently active.
GCSR_required: A record of flags indicating which features, at the least, are required for the controller.
GCSR_prohibited: A record of flags indicating which features are prohibited to the controller.
GCSR_supported: A record of flags indicating the full range of supported features.

MSG_GEN_CONTROL_GET_TOOLBOX_FEATURES

void MSG_GEN_CONTROL_GET_TOOLBOX_FEATURES(
        GenControlGetFeaturesReturn *return);

This message returns a structure indicating which of the controller's tools are currently active, which are required, and which are prohibited.

Source: Unrestricted--typically GenToolControl.

Destination: Any GenControl object.

Parameters: return A pointer to an empty structure to be returned.

Return: The return parameter, upon return, points to a filled GenControlGetFeaturesReturn structure.

Structures: The GenControlGetFeaturesReturn structure is shown in MSG_GEN_CONTROL_GET_NORMAL_FEATURES , above.

Working with GCN Lists

MSG_GEN_CONTROL_ADD_TO_GCN_LISTS, MSG_GEN_CONTROL_REMOVE_FROM_GCN_LISTS

Because GenControlClass uses GCN lists, it has two messages that add itself to and remove itself from the lists. You can intercept or send these if you need to; applications generally will not, however. These two messages are detailed below.

MSG_GEN_CONTROL_ADD_TO_GCN_LISTS

void	MSG_GEN_CONTROL_ADD_TO_GCN_LISTS();

This message adds the controller object to the GCN lists specified by its return value of MSG_GEN_CONTROL_GET_INFO . It will force a status update to ensure that the controller updates itself.

Source: Generated internally on startup and at other times.

Destination: Sent to self.

Interception: Generally not intercepted. Subclasses should use this only to see when the controller is being added to its lists; it should call the superclass to do the actual addition.

MSG_GEN_CONTROL_REMOVE_FROM_GCN_LISTS

void	MSG_GEN_CONTROL_REMOVE_FROM_GCN_LISTS();

This message removes the controller from all its GCN lists.

Source: Generated internally on shutdown and at other times.

Destination: Sent to self.

Interception: Generally not intercepted. Subclasses should use this only to see when the controller is being removed from its lists; it should call the superclass to do the actual removal.

Working with Controller Visibility

MSG_GEN_CONTROL_NOTIFY_INTERACTABLE, MSG_GEN_CONTROL_NOTIFY_NOT_INTERACTABLE, MSG_GEN_CONTROL_UNBUILD_NORMAL_UI_IF_POSSIBLE

Because controllers are generic objects which may or may not be interactable, GenControlClass has two messages to handle the interactable state. It has an additional message to close the normal UI tools, if possible. These three messages are detailed below.

MSG_GEN_CONTROL_NOTIFY_INTERACTABLE

void	MSG_GEN_CONTROL_NOTIFY_INTERACTABLE(
        GenControlInteractableFlags flags);

This message instructs the controller to take any actions necessary before being put on the screen and made interactable. It causes the controller to add itself to its GCN lists (if it wasn't already) and take any final steps to get ready to go on the screen.

Source: Generated Internally--do not generate externally.

Destination: Sent to self.

Parameters: flags A single record of flags indicating which portions of the controller will be made interactable.

Interception: May be intercepted to circumvent default behavior.

MSG_GEN_CONTROL_NOTIFY_NOT_INTERACTABLE

void	MSG_GEN_CONTROL_NOTIFY_NOT_INTERACTABLE(
        GenControlInteractableFlags flags);

This message indicates that the UI has determined that the controller can no longer be seen or interacted with by the user. The default behavior of the controller is to remove itself from its GCN lists for optimization.

Source: Generated Internally--do not generate externally.

Destination: Sent to self.

Parameters: flags A single record of flags indicating which portions of the controller are no longer interactable.

Interception: May be intercepted to circumvent default behavior.

MSG_GEN_CONTROL_UNBUILD_NORMAL_UI_IF_POSSIBLE

void	MSG_GEN_CONTROL_UNBUILD_NORMAL_UI_IF_POSSIBLE();

This internal message requests that the normal default controller UI gadgetry be removed and destroyed if they are not in use. This is an optimization intended to save swap space and perhaps memory space; it causes the objects to be loaded back in again when needed, however. Thus, the optimization is only suited to machines with limited swap space (it originated due to these conditions on palmtop machines).

Source: Generated internally. Do not generate externally.

Destination: Sent to self.

Interception: May be intercepted to avoid the optimization. May also need to be intercepted if a subclass creates its own UI gadgetry by intercepting MSG_GEN_CONTROL_GENERATE_UI .

GEOS SDK TechDocs |

4.2 Subclassing GenControlClass | Next:

5 GenToolControlClass