GEOS SDK TechDocs
|
| 
1.5 ApplicationStates
| 
1.7 IACP
GAI_appFeatures, GAI_appLevel, MSG_GEN_APPLICATION_GET_APP_FEATURES, MSG_GEN_APPLICATION_SET_APP_FEATURES, MSG_GEN_APPLICATION_SET_APP_LEVEL, MSG_GEN_APPLICATION_UPDATE_APP_FEATURES, MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE, GenAppUsabilityTupleFlags, GenAppUsabilityTuple, GenAppUsabilityCommands
A GenApplication may store a word of features (
GAI_appFeatures
); these features correspond to groups of UI objects. Depending on a certain feature being set or not set, certain groups of UI objects may or may not appear, allowing you to customize your application for different users or criteria. It is up to your application to define both the features and the objects that these features correspond to.
GAI_
appFeatures
is a word-length bitfield. Each bit corresponds to a certain group of features which you define. You may thus have up to 16 different feature groups for any application. (Note that each feature group may include several UI objects.) In general, you group these features together so that they correspond to a specific
UIInterfaceLevel
. If the application appears at a different User Interface level, the makeup of the UI will be different.
An application's user interface level is stored in the GenApplication's GAI_
appLevel
instance data entry. Each
UIInterfaceLevel
corresponds to a certain group of features. Changing the UI level changes the group of features that may be displayed.
The features represented in the bitfield may be represented in hints added to GenControl objects. Most often, the controllers and the application will adjust their menus, tools, and other UI gadgetry to conform to the features specified in this record.
Code Display 3-5 Setting Up Features
/* Features are stored in a word-length bitfield. */
typedef WordFlags MyFeatures;
@define MF_EDIT_FEATURES (0x8000) @define MF_PASTE_FEATURES (0x4000) @define MF_FORMAT_FEATURES (0x2000)
/* We might want to group certain features together based on the level of * expertise of the user. In this example, if the user level is "intermediate" * (which we will define later), we allow features for editing and pasting to the * UI. If the user level is "advanced" we allow the intermediate features and also * allow formatting features. */
@define INTRODUCTORY_FEATURES (0)
@define INTERMEDIATE_FEATURES (@MF_EDIT_FEATURES | @MF_PASTE_FEATURES)
@define ADVANCED_FEATURES (@INTERMEDIATE_FEATURES | @MF_FORMAT_FEATURES)
MSG_GEN_APPLICATION_GET_APP_FEATURES returns the current application features and
UIInterfaceLevel
in use by an application.
You may set the application's GAI_
appFeatures
by sending it MSG_GEN_APPLICATION_SET_APP_FEATURES. You may also change the application's user level by sending it MSG_GEN_APPLICATION_SET_APP_LEVEL. Each of these messages in turn generates a MSG_GEN_APPLICATION_UPDATE_APP_FEATURES.
This message is meant to be sub-classed so that you can alter the behavior for different features. In most cases, however, you will simply handle this message, fill in relevant parameters, and send the GenApplication MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE--the message which performs the actual work done in changing the UI. This message expects a number of arguments.
The most important argument is the table of
GenAppUsabilityTuple
entries that correspond to each feature. These entries define what sort of UI change is required, and what object is required to change.You must set up this table beforehand.
The types of usability commands available (in the bit positions set aside with GAUTF_COMMAND in the tuple's
GenAppUsabilityTupleFlags
) are:
Because each feature may have multiple objects affected, the
GenAppUsabilityTupleFlags
entry GAUTF_END_OF_LIST indicates that there are no more commands for that feature. The flag GAUTF_OFF_IF_BIT_IS_ON indicates that a given command should be reversed for the object. (I.e. if the feature is on, the object should be removed, not added.)
Code Display 3-6 Setting Up the GenAppUsabilityTuple Tables
/* Each GenAppUsabilityTuple will refer to a specific set of features. */
/* * Since GUAC_USABILITY is the default setting (and is zero) setting any other * flags either supersedes or complements this behavior. In this case, setting the * EditToolEntry as a GUAC_TOOLBAR command supersedes the GUAC_USABILITY command. * Setting the GUATF_END_OF_LIST flag for the EditTrigger does not alter the * GUAC_USABILITY command, which is still implicit. */
static const GenAppUsabilityTuple editFeaturesList [] =
{
{GUAC_TOOLBAR, @EditToolEntry },
{GUATF_END_OF_LIST @EditTrigger }
};
static const GenAppUsabilityTuple pasteFeaturesList [] =
{
{GUAC_END_OF_LIST, @PasteTrigger }
};
static const GenAppUsabilityTuple formatFeaturesList [] =
{
{
GAUTF_END_OF_LIST | GUAC_RECALC_CONTROLLER,
@FeatureController
}
};
/* After each feature's GenAppUsabilityTuple is set up, you should set up a table * of these structures to pass to relevant messages. */
static const GenAppUsabilityTuple * const usabilityTable [] =
{
editFeaturesList,
pasteFeaturesList,
formatFeaturesList
};
/* * Within your code, decide where you wish to set the application features * (usually within some sort of User level dialog box that passes a selection of * feature bits) and send either MSG_GEN_APPLICATION_SET_APP_FEATURES or * MSG_GEN_APPLICATION_SET_APP_LEVEL with the proper feature bits set. */
@method MyLevelApplicationClass, MSG_MY_APPLICATION_SET_USER_LEVEL
{
@call oself::MSG_GEN_APPLICATION_SET_APP_FEATURES(selection);
}
/* * Then intercept MSG_GEN_APPLICATION_UPDATE_APP_FEATURES and set up the correct * parameters for MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE. */
@method MyLevelApplicationClass, MSG_GEN_APPLICATION_UPDATE_APP_FEATURES
{
@call oself::MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE(
NullOptr,
@ObjectToReparent, /* if any */
levelTable, /* if any */
sizeof(usabilityTable) / sizeof(usabilityTable [0]),
usabilityTable,
appOpeningFlag,
oldLevel,
level,
featuresChanged,
featuresOn);
}
dword MSG_GEN_APPLICATION_GET_APP_FEATURES();
This message retrieves the set of features set for the application.
Source: Unrestricted--typically a GenControl object finding out the application's UI level.
Destination: The GenApplication running the controller.
Parameters: None.
Return: A dword containing the word of features stored in
GAI_appFeatures
and the
UIInterfaceLevel
for the application. The features are stored in the high word; the interface level is stored in the low word.
Interception: Generally not intercepted.
void MSG_GEN_APPLICATION_SET_APP_FEATURES(
word features);
This message sets a new set of features into the GenApplication's
GAI_appFeatures
record. This message in turn generates a MSG_GEN_APPLICATION_UPDATE_APP_FEATURES for your application object to intercept. (The message handler for that message must in turn send MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE to activate the UI changes specified in the features list.)
Source: Unrestricted--typically a system function.
Destination: The GenApplication having its features set.
Parameters:
features
The new word-sized record of application features to set.
Return: Nothing.
Interception: Generally not intercepted.
void MSG_GEN_APPLICATION_UPDATE_APP_FEATURES(@stack
optr unReparentObject,
optr reparentObject,
GenAppUsabilityTuple *levelTable,
word tableLength,
void *table,
word appOpeningFlag,
UIInterfaceLevel oldLevel,
UIInterfaceLevel level,
word featuresChanged,
word featuresOn);
This message is sent by the application to itself when it is told to change either its features or its
UIInterfacelevel
. This message is passed a number of parameters, most of which should simply be passed to MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE. If you have reparent objects (or un-reparent objects), you must set them up here.
Source: Sent by an application object to itself in response to a MSG_GEN_APPLICATION_SET_APP_FEATURES or MSG_GEN_APPLICATION_SET_APP_LEVEL.
Destination: The GenApplication object.
Parameters: unReparentObject The optr of the object to be unreparented. If a null optr is passed, the object will by default be moved up and added as the next sibling of its current parent.
GenAppUsabilityTuple
entry that contains a GAUC_REPARENT entry.
GenAppUsabilityTuple
entries that must be updated when the user level changes. This table is usually set up as global data and maps each user level feature to a
GenAppUsabilityTuple
.
UIInterfaceLevel
.
UIInterfaceLevel
.Interception: To set an application's features, you must intercept this message and send MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE; there is no default message handler. This message is provided as a convenient point to intercept and change features before executing the changes.
void MSG_GEN_APPLICATION_UPDATE_FEATURES_VIA_TABLE(
optr unReparentObject,
optr reparentObject,
GenAppUsabilityTuple *levelTable,
word tableLength,
void *table,
word appOpeningFlag,
UIInterfaceLevel oldLevel,
UIInterfaceLevel level,
word featuresChanged,
word featuresOn);
This message is called to update the application's features to reflect a new set of features to
Source: Typically, your message handler for MSG_GEN_APPLICATION_UPDATE_APP_FEATURES.
Destination: The GenApplication object.
Parameters: unReparentObject The optr of the object to be unreparented. If a null optr is passed, the object will by default be moved up and added as the next sibling of its current parent.
GenAppUsabilityTuple
entry that contains a GAUC_REPARENT entry.
GenAppUsabilityTuple
entries that must be updated when the user level changes. This table is usually set up as global data and maps each user level feature to a
GenAppUsabilityTuple
.
UIInterfaceLevel
.
UIInterfaceLevel
.Interception: Generally not intercepted. Intercept MSG_GEN_APPLICATION_UPDATE_APP_FEATURES instead.
GEOS SDK TechDocs
|
| 1.5 ApplicationStates
| 1.7 IACP