GEOS SDK TechDocs
|
| 
5.1 GenBooleanGroup Instance Data
| 
5.3 Altering Instance Data
The GenBooleanGroup manages up to 16 GenBoolean objects. You must define a new (or use a pre-existing) constant to represent each GenBoolean within the GenBooleanGroup. Each constant represents a bit within a word-length record.
The GenBooleanGroup uses 16-bit records to designate its list of items; each bit in the record corresponds to an item. The GenBooleanGroup keeps three such records: GBGI_
selectedBooleans
, GBGI_
indeterminateBooleans
, and GBGI_
modifiedBooleans
to represent the selected state, the indeterminate state, and the modified state of each GenBoolean.
GBI_identifier, GBGI_selectedBooleans
GBI_
identifier
stores the identifying keyword for a GenBoolean item. The BooleanGroup object will always use this identifier when referring to GenBooleans. These identifiers are set up as constants representing bits in a 16-bit record. (See Setting Up a GenBooleanGroup
.)
Code Display 11-9 Setting Up a GenBooleanGroup
/* The identifiers for any particular GenBooleanGroup are * constant bits within a word-length bitfield. */
typedef WordFlags USCities; #define USC_CHICAGO 0x0001 /* The first bit */ #define USC_NEW_YORK 0x0002 /* The second bit */ #define USC_SAN_FRANCISCO 0x0004 /* The third bit */
@object GenBooleanGroupClass CityList = {
GI_comp = @Chicago, @NewYork, @SanFrancisco;
/* The first and second bit in the selectedBooleans record are set to
* indicate that Chicago and New York are initially selected. */
GBGI_selectedBooleans = USC_CHICAGO | USC_NEW_YORK;
}
@object GenBooleanClass Chicago = {
GI_visMoniker = "Chicago";
GBI_identifier = USC_CHICAGO;
}
@object GenBooleanClass NewYork = {
GI_visMoniker = "New York";
GBI_identifier = USC_NEW_YORK;
}
@object GenBooleanClass SanFrancisco = {
GI_visMoniker = "San Francisco";
GBI_identifier = USC_SAN_FRANCISCO;
}
GBGI_
selectedBooleans
stores a 16-bit record corresponding to the selection state of a GenBooleanGroup's children. Selecting or deselecting the Booleans will alter the bit representing that GenBoolean child in this instance field. By setting selections in this field, you can specify initial selections for the GenBooleanGroup to initially appear set.
GBGI_indeterminateBooleans, GBGI_modifiedBooleans
GBGI_
indeterminateBooleans
stores a 16-bit record corresponding to the indeterminate state of a GenBooleanGroup's children. Your BooleanGroup may appear initially with GenBooleans in an indeterminate state. As opposed to a GenItemGroup, where either the entire list is indeterminate or not, individual Booleans may be indeterminate on their own accord.
A GenBoolean may be indeterminate while it is either selected or unselected. Making an item indeterminate will not change its selected state, though the item's visual representation might change. (In OSF/Motif, an indeterminate selection appears "off" whether or not it is also selected.)
GBGI_
modifiedBooleans
stores a 16-bit record corresponding to the modified state of a GenBooleanGroup's children. Any GenBooleans that have been modified since the occurrence of the last apply action will be marked modified. In general, you should not need to set any GenBooleans initially modified.
Whenever the GenBooleanGroup receives notice to "apply" any changes, it will check whether any Booleans have been modified. If any have, the GenBooleanGroup will send its apply action to its destination.
In immediate mode, any change to the GenBoolean's state automatically sets the corresponding bit in the BooleanGroup's GBGI_
modifiedBooleans
instance data and also sends out
MSG_GEN_APPLY
. Therefore, in immediate mode, any user changes will cause the apply action to be sent out immediately. In delayed mode, the corresponding bits in the GBGI_
modifiedBooleans
are set, but
MSG_GEN_APPLY
will be sent out at a later time. The apply action will only occur when the user forces it (such as clicking on an "apply" trigger) or when the application forces it (with
MSG_GEN_APPLY
).
GBGI_applyMsg, GBGI_destination, GEN_BOOLEAN_GROUP_APPLY_MSG, ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
When the GenBooleanGroup receives notice to apply any changes made in the list, it will first determine whether the group has been modified (by checking GBGI_
modifiedBooleans
). If any GenBoolean has been modified, the BooleanGroup will send the apply message stored in GBGI_
applyMsg
to the destination stored in GBGI_
destination
.
GBGI_
applyMsg
should contain the message you wish the GenBooleanGroup to send out whenever changes should be applied. This message should be based on the prototype GEN_BOOLEAN_GROUP_APPLY_MSG so the proper arguments are passed to its handler. GBGI_
destination
should contain the object or process that will handle the message sent out by this group.
You can force an apply to occur by marking GenBooleans modified with
MSG_GEN_BOOLEAN_GROUP_SET_MODIFIED_STATE
and sending
MSG_GEN_APPLY
to the GenBooleanGroup. You can also override the default behavior, forcing the object to send out its apply action on all applies, with
ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
in the object's instance data.
void GEN_BOOLEAN_GROUP_APPLY_MSG(
word selectedBooleans,
word indeterminateBooleans,
word modifiedBooleans);
Use this prototype to define the apply message for your GenBooleanGroup (stored in GBGI_
applyMsg
). This prototype ensures that the message passes the correct parameters to your message handler.
Source: Your GenBooleanGroup object.
Destination: The destination of your GenBooleanGroup.
Parameters:
selectedBooleans
The currently selected GenBooleans (the contents of the GBGI_
selectedBooleans
instance field).
indeterminateBooleans
instance field).
modifiedBooleans
instance field).Return: Nothing.
GEN_BOOLEAN_GROUP_STATUS_MSG, ATTR_GEN_BOOLEAN_GROUP_STATUS_MSG, MSG_GEN_BOOLEAN_GROUP_SEND_STATUS_MSG
In delayed mode, GenBooleanGroups will only send out their apply action if an apply occurs. If you wish your application to receive notice whenever any user changes take place in the list's state, even if those changes should not be "applied," you may set up a status message in the object's instance data.
Set a message based on the prototype GEN_BOOLEAN_GROUP_STATUS_MSG. Set ATTR_GEN_BOOLEAN_GROUP_STATUS_MSG to this message in your object declaration, and provide a handler for this message in the class.
void GEN_BOOLEAN_GROUP_STATUS_MSG(
word selectedBooleans,
word indeterminateBooleans,
word changedBooleans);
Use this prototype to define a status message for your GenBooleanGroup (stored in the ATTR_GEN_BOOLEAN_GROUP_STATUS_MSG vardata). This prototype ensures that the message passes the correct parameters to your message handler.
Source: Your GenBooleanGroup object.
Destination: The destination of your GenBooleanGroup object.
Parameters:
selectedBooleans
The currently selected GenBooleans (the contents of the GBGI_
selectedBooleans
instance field).
indeterminateBooleans
instance field).
modifiedBooleans
instance field).Return: Nothing.
void MSG_GEN_BOOLEAN_GROUP_SEND_STATUS_MSG(
word changedBooleans);
This message causes the GenBooleanGroup to send out its status message stored in
ATTR_GEN_ITEM_GROUP_STATUS_MSG
. The message should include the current state of the GenBooleanGroup. (Base the status message on the prototype
GEN_BOOLEAN_GROUP_STATUS_MSG
to ensure this.) To mark individual GenBooleans as changed since the last apply action, pass this message a record of the changed GenBooleans.
Source: Unrestricted.
Destination: Any GenBooleanGroup object with a status message.
Parameters: changedBooleans A record representing the GenBooleans that have changed to cause this GenBooleanGroup to send out its status message.
Return: Nothing.
Interception: Generally not intercepted.
ATTR_GEN_BOOLEAN_GROUP_LINK
Just as you may create links between GenItemGroups, you may also create links between BooleanGroups. For more complete information on the purpose and effects of linked groups, see GenItemGroup Links .
To enable linked BooleanGroups, you may set up small sub-sets of GenBooleans as separate GenBooleanGroups. Within each BooleanGroup, include a link to the next BooleanGroup with
ATTR_GEN_BOOLEAN_GROUP_LINK
. Links should be circular; i.e., if three BooleanGroups should be linked, the first group should point to the second, the second to the third, and the third to the first. The three linked BooleanGroups will act as one entity.
HINT_BOOLEAN_GROUP_SCROLLABLE, MSG_GEN_BOOLEAN_GROUP_MAKE_BOOLEAN_VISIBLE
Boolean group lists, like item group lists, can be scrollable. To make a Boolean list scrollable, set
HINT_BOOLEAN_GROUP_SCROLLABLE
. To make a particular item in a scrollable Boolean list visible, use the message
MSG_GEN_BOOLEAN_GROUP_MAKE_BOOLEAN_VISIBLE
.
void MSG_GEN_BOOLEAN_GROUP_MAKE_BOOLEAN_VISIBLE(
word identifier);
This message, when sent to a scrollable BooleanGroup object, will make the specified GenBoolean visible in the list. If the passed identifier is unknown or is not usable, the BooleanGroup will do nothing.
Source: Unrestricted.
Destination: Any scrollable, usable GenBooleanGroup.
Parameters:
identifier
The item number of the GenBoolean to be made visible.
Return: Nothing.
Interception: Generally not intercepted.
GEOS SDK TechDocs
|
| 5.1 GenBooleanGroup Instance Data
| 5.3 Altering Instance Data