GenClass: 3.5 GenClass Basics: States

GI_states

The GI_states attribute is a record that holds the state of the generic object. These states affect the object's visual representation and its functionality. By default, all objects have both GS_USABLE and GS_ENABLED set when first built. There are two GI_states :

GS_USABLE: This state controls the usability of an object. Setting an object GS_USABLE will indicate that both the object and the entire generic branch below this object should be considered as an active part of the user interface and therefore should be visually represented. An object that is not set GS_USABLE cannot appear as part of the user interface. Before an object can be visually built and considered part of the user interface, however, it must satisfy two conditions: The object itself must be GS_USABLE, and all ancestors (parents) of the object must also be GS_USABLE.
: This means that a continuous path of GS_USABLE objects must exist from the top node of your application to the object for it to be usable. In this case, an object is considered to be fully usable. Conversely, if an object is not GS_USABLE, then no object in the branch below it can be visually displayed either (even if it is GS_USABLE). Therefore, an object may be set GS_USABLE without being fully usable. This allows you to set an entire branch fully usable by setting just one node object usable, provided that all other objects below that node had previously been set GS_USABLE. This attribute is set by default.
GS_ENABLED: This state sets the object enabled. This state controls whether the object is available to the user for activity. An object must be enabled for the user to interact with it. If an object is set GS_USABLE but not GS_ENABLED, it will be visually displayed but will not accept input from the user. The object will also be unable to perform its normal activities. This is usually represented by "graying out" the object's visual moniker. Before an object can be "enabled" for user input and activation, however, it must satisfy two conditions: The object must be GS_ENABLED; all ancestors (parents) of the object must also be GS_ENABLED. Therefore, a continuous path of GS_ENABLED objects must exist from the top node of your application to the object in question for it to be enabled. In this case, an object is considered to be fully enabled.
: Conversely, if an object is not GS_ENABLED, then no object in the branch below it can be interacted with either (even if it is GS_ENABLED). Therefore, an object may be GS_ENABLED without being fully enabled. This allows you to set an entire branch fully enabled by setting just one node object enabled, provided that all other objects below that node had previously been set GS_ENABLED.

These states not only affect the state of the current object but all of its descendants as well. When your user interface is first built (or rebuilt) it conducts a top-down search, building any objects that are declared GS_USABLE. If an object is not GS_USABLE, it will not be visually built. Furthermore, none of its descendants will be searched (or built). Therefore, if any single node is not GS_USABLE, no other object below that node will be fully usable.

In cases where you wish to alter any fundamental behavior of an object, you may have to set the object not usable, change its behavior, and then set the object GS_USABLE again. This ensures that the object is built out correctly (including visually) according to the new criteria.

Code Display 2-17 Setting GI_states

@object GenTriggerClass MyTrigger = {
		/* The default GI_states are GS_USABLE and GS_ENABLED.
		 * This object will only be GS_USABLE */
    GI_states = @default & ~GS_ENABLED;
}

The Usable State

MSG_GEN_GET_USABLE, MSG_GEN_SET_USABLE, MSG_GEN_SET_NOT_USABLE, MSG_GEN_CHECK_IF_FULLY_USABLE

Setting an object GS_USABLE will incorporate the object into the generic tree and regard the object as part of the user interface. (It will not by itself enable an object for user input; this requires an object to be set GS_ENABLED also.) If an object is not GS_USABLE, it cannot be used in any manner including any visual implementation by the user interface. The following messages manipulate an object's usable state.

MSG_GEN_GET_USABLE

Boolean	MSG_GEN_GET_USABLE();

This message checks the GS_USABLE bit of the GI_states field.

Source: Unrestricted.

Destination: Any generic object.

Parameters: None.

Return: Will return true if the object is GS_USABLE, false if it is not usable.

Interception: Generally not intercepted.

MSG_GEN_SET_USABLE

void	MSG_GEN_SET_USABLE(
        VisUpdateMode updateMode);

This message sets an object GS_USABLE. (This message has no effect on an object already GS_USABLE.) Objects may be set GS_USABLE only after they have been attached to a generic tree. Setting an object usable forces that object to be specifically built. If the object's associated window is realized, the object will be visually built and updated. Setting an object GS_USABLE that is not attached to the generic tree will cause an error.

Setting an object usable allows that object to become part of the user interface. Before the object can be used, though, it must be fully usable . An object becomes fully usable only if all of its ancestors are GS_USABLE. If any ancestor is not GS_USABLE, then the entire branch below it will not be fully usable. You can check if an object is fully usable with the message MSG_GEN_CHECK_IF_FULLY_USABLE .

Conversely, setting a node GS_USABLE, in which every branch object below it is already GS_USABLE will make that entire branch fully usable. This is useful for bringing up an entire section of a generic tree by setting a single object usable.

Source: Unrestricted.

Destination: Any generic object.

Parameters: updateMode VisUpdateMode to use when updating changes to the screen.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_SET_NOT_USABLE

void	MSG_GEN_SET_NOT_USABLE(
        VisUpdateMode updateMode);

This message sets an object not usable (clears the GS_USABLE bit). Because an object may be visually unbuilt by this message, the VisUpdateMode VUM_MANUAL is not allowed.

Source: Unrestricted.

Destination: Any generic object.

Parameters: updateMode VisUpdateMode to use when updating changes to the screen. May not be VUM_MANUAL.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_CHECK_IF_FULLY_USABLE

Boolean	MSG_GEN_CHECK_IF_FULLY_USABLE();

This message checks whether an object is fully usable. The object and all of its parents must be GS_USABLE for the object to be fully usable.

Source: Unrestricted.

Destination: Any generic object.

Return: Will return true if the object is fully usable, false if it is not.

Interception: Generally not intercepted.

The Enabled State

MSG_GEN_GET_ENABLED, MSG_GEN_SET_ENABLED, MSG_GEN_SET_NOT_ENABLED, MSG_GEN_CHECK_IF_FULLY_ENABLED

An object that is GS_ENABLED is ready for user interaction. As in the case with GS_USABLE, all parents of the object in question must be GS_ENABLED to fully enable the object. An object may be fully enabled without being fully usable, but the object will not be visually represented. You can check if an object is fully enabled with MSG_GEN_CHECK_IF_FULLY_ENABLED .

An object that is not enabled but is set usable will be represented in the user interface; it will not, however, allow the user to interact with it. In many cases, the specific UI implements this by "graying out" the object. Setting a disabled object will visually update it.

MSG_GEN_GET_ENABLED

Boolean	MSG_GEN_GET_ENABLED();

This message returns the enabled state of the object the message is sent to.

Source: Unrestricted.

Destination: Any generic object.

Return: Will return true if the object is enabled,false if it is not.

Interception: Generally not intercepted.

MSG_GEN_SET_ENABLED

void	MSG_GEN_SET_ENABLED(
        VisUpdateMode updateMode);

This message sets an object GS_ENABLED. (This message has no effect on an object already GS_ENABLED.) You must pass this message a VisUpdateMode . Sending this message allows the object to receive user input. Only send this message if your application will be ready to interact with the object after the period specified in the VisUpdateMode has passed.

Source: Unrestricted.

Destination: Any generic object.

Parameters: updateMode VisUpdateMode to use when updating changes to the screen.

Interception: Generally not intercepted.

MSG_GEN_SET_NOT_ENABLED

void	MSG_GEN_SET_NOT_ENABLED(
        VisUpdateMode updateMode);

This message sets the object not enabled (clears the object's GS_ENABLED bit.) You must pass the message a VisUpdateMode . In most specific UIs a disabled state is implemented by "graying out" the object. The user will be unable to interact with the object according to the VisUpdateMode passed.

Source: Unrestricted.

Destination: Any generic object.

Parameters: updateMode VisUpdateMode to use when updating changes to the screen. May not be VUM_MANUAL.

Interception: Generally not intercepted.

MSG_GEN_CHECK_IF_FULLY_ENABLED

Boolean	MSG_GEN_CHECK_IF_FULLY_ENABLED();

This message checks whether an object is fully enabled. An object is only fully enabled (ready for user interaction) when both it and all of its ancestors are enabled.

Source: Unrestricted.

Destination: Any generic object.

Return: Will return true if fully enabled, false if not.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

3.4 Attributes | Next:

4 Modifying GenClass Instance Data