GEOS SDK TechDocs
|
| 
3.2 GenItem Instance Data
| 
3.4 Working with Items
The GenItemGroup manages a group of GenItems. In general, you must decide which behavior type you wish your GenItemGroup to exhibit, the message for the list to send out, and the object (or process) to handle messages sent out by this group. You may also set a number of initial conditions (items selected, whether the list is indeterminate or modified, etc.) for the list.
GIGI_behaviorType, MSG_GEN_ITEM_GROUP_SET_BEHAVIOR_TYPE, MSG_GEN_ITEM_GROUP_GET_BEHAVIOR_TYPE
There are several types of user selection behavior for a GenItemGroup. Items can be set up so that only one is selected at a time, one or none is selected at a time, multiple items can be selected, or multiple items can be selected only when extending the selection (e.g. dragging the mouse).
The GIGI_
behaviorType
instance field defines the selection behavior of the list. The instance data must be of the enumerated type
GenItemGroupBehaviorType
. The default type is GIGBT_EXCLUSIVE, which creates an exclusive list; one and only one selection in an exclusive list may be selected at any time. The available types are listed below.
selection
instance fields.Exclusive lists are designed for cases in which one and only item should be selected at any given time. For example, a graphics application may want to prompt the user to select a color for drawing lines. The application can display this list of colors within an exclusive list. Only one color may be selected. Once a color is selected, selecting any other color will deselect the first color.
Exclusive lists may (and by default do) appear without any item initially selected. This may lead to problems if the application tries to apply any changes before an item is selected (such as within a delayed-mode dialog box). If your application needs an item to be selected at all times in order to operate correctly, your list should appear with one of the items initially selected (or with the "apply" trigger disabled).
Exclusive-None lists are designed for cases in which either one item must be selected or no items should be selected. For example, a word processor may have a "Justifications" menu with several options such as left-justified, right-justified, or center-justified. Selecting any of these options will perform the justification operation on the current paragraph, but the user may also deselect any option, leaving no justification on the paragraph.
Exclusive-None lists by default appear without any items initially selected. Your application should, of course, be able to handle this case of nothing selected; if it cannot, the list should probably not be exclusive-none.
Extended-Selection lists are designed for cases in which the application usually needs an exclusive selection but also desires to let the user select multiple items for bulk operations. Multiple selections are stored as lists of items.
For example, a disk copy operation may have an extended-selection list to specify the drive to copy a file to. In most cases, the user will only want to copy to one drive, and the list normally operates in exclusive mode to accommodate this. By extending the selection, however, the user can request the list to copy the file to multiple drives.
It is up to the specific UI how the user may extend a selection. In OSF/Motif, the user may select another item in tandem with a special keystroke (the SHIFT key) to extend the selection from one item to several. Extending a selection to an already selected item will deselect that item, leaving any other items unchanged.
Non-exclusive lists are designed for cases in which any or all of the items may be selected at once. Multiple selections, as in the extended-selection GenItemGroup, are stored as lists of items. Selecting an already selected item will deselect that item. Therefore, there may be a state where nothing is selected within a non-exclusive list.
For example, an interactive tutorial may ask the user if he wants more information on certain topics, giving these topics in a non-exclusive list. The user can freely choose as many or as few items as he wishes, and then select "Print" to print out information on those items.
In most cases, however, you might rather use a GenBooleanGroup object in place of a non-exclusive GenItemGroup. A GenBooleanGroup acts similar to a non-exclusive list but is streamlined to operate efficiently for lists with 16 or fewer items. (GenBooleanGroups represent their children's state through a word-length bitfield; therefore they may only accommodate 16 children.) You may also need to use a GenBooleanGroup if you need to keep track of individual indeterminate and modified states.
MSG_GEN_ITEM_GROUP_GET_BEHAVIOR_TYPE
returns the behavior type stored in the list's GIGI_
behaviorType
instance field. To set a new behavior type, send the list a
MSG_GEN_ITEM_GROUP_SET_BEHAVIOR_TYPE
.
GenItemGroupBehaviorType MSG_GEN_ITEM_GROUP_GET_BEHAVIOR_TYPE();
This message returns the current behavior type of a GenItemGroup (stored in the GIGI_
behaviorType
instance field).
Source: Unrestricted.
Destination: Any GenItemGroup.
Parameters: Nothing.
Return: The
GenItemGroupBehaviorType
of the GenItemGroup.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_BEHAVIOR_TYPE(
GenItemGroupBehaviorType behaviorType);
This message sets a new behavior type for a GenItemGroup by changing the object's GIGI_
behaviorType
instance field. This message should only be sent while the object is not usable.
Source: Unrestricted.
Destination: Any non-usable GenItemGroup object.
Parameters:
behaviorType
The new
GenItemGroupBehaviorType
.
Return: Nothing.
Interception: Generally not intercepted.
GIGI_selection, GII_identifier, GIGI_numSelections, MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED, MSG_GEN_ITEM_GROUP_SET_SINGLE_SELECTION, MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS, MSG_GEN_ITEM_GROUP_GET_SELECTION, MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS, MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS
Within a GenItemGroup, each GenItem must contain an identifier, often an enumerated value, to uniquely identify that item. The GenItemGroup will use this identifying value whenever referencing the GenItem (or items), either through its instance data or through messages. This value is stored in the GenItem's GII_
identifier
instance data.
In most cases, your collection of GenItems within a particular GenItemGroup should be different enumerated values. Each item within a specific GenItemGroup must have a unique identifier to reference each item. To ensure this, it is usually convenient to use an enumerated type. Make sure that you don't use two different enumerated types because they may not contain unique values across types.
In an exclusive or exclusive-none list, the GenItemGroup will store the identifier of the current selection in the GIGI_
selection
instance field. If no item is selected, this instance field will instead store the value GIGS_NONE (-1). (For an exclusive list, this case could only arise before an item is initially selected.)
Note that -1 is still a legal identifier for a GenItem. If you do use this identifier you must be sure to check the GIGI_
numSelections
instance field to check whether the GIGI_
selection
value corresponds to an item or to the GIGS_NONE value.
GenItemGroups by default appear with no items initially set (GIGI_
selection
is set to GIGS_NONE). If you wish a GenItemGroup to initially appear with a selection set to one of the GenItems, set GIGI_
selection
to the identifier of that GenItem.
Code Display 11-3 Setting Enumerated Types As Identifiers
/* In most cases, each GenItemGroup should have a single set of enumerated types * to name its children. In this case, MyCityGroup will have settings all related * to the enumerated type USCities, and San Francisco will be the initial * selection. */
typedef ByteEnum USCitiesEnum; #define CITY_CHICAGO 1 #define CITY_NEW_YORK 2 #define CITY_SAN_FRANCISCO 3 #define CITY_LOS_ANGELES 4
@object GenItemGroupClass MyCityGroup = {
GI_comp = @Chicago, @NewYork, @SanFrancisco, @LosAngeles;
GIGI_selection = CITY_SAN_FRANCISCO;
}
@object GenItemClass Chicago = {
GI_visMoniker = `C', "Chicago";
GII_identifier = CITY_CHICAGO;
}
@object GenItemClass NewYork = {
GI_visMoniker = `N', "New York";
GII_identifier = CITY_NEW_YORK;
}
@object GenItemClass SanFrancisco = {
GI_visMoniker = `S', "San Francisco";
GII_identifier = CITY_SAN_FRANCISCO;
}
@object GenItemClass LosAngeles = {
GI_visMoniker = `L', "Los Angeles";
GII_identifier = CITY_LOS_ANGELES;
}
In an extended-selection or non-exclusive list, more than one item may be selected at a time. In this case, the GIGI_
selection
instance field will not store a single identifier but instead will store a ChunkHandle to a list of identifiers. This functionality is internal to the operation of the list.
You may set up a list (if it is extended-selection or non-exclusive) to initially appear with multiple selections. The list of identifiers may be of arbitrary size but must be manually set up in its own chunk. Set GIGI_
selection
to the ChunkHandle of the chunk containing this list. In this case, you must also set GIGI_
numSelections
to the proper number of selections. (See Setting Multiple Initial Selections
.)
For multiple selection lists (GIGBT_EXTENDED_SELECTION or GIGBT_NON_EXCLUSIVE) GIGI_
numSelections
may be set greater than 1 if more than one item is selected. In this case, GIGI_
selection
will contain a ChunkHandle to a list of identifiers instead of a single identifier.
Code Display 11-4 Setting Multiple Initial Selections
/* To set a GenItemGroup to appear initially with multiple selections, set up a * chunk containing the identifiers and a ChunkHandle in the GIGI_selection * instance field. Only the new list chunk and the GenItemGroup are shown; other * information is in the previous code display. */
@object GenItemGroupClass MyCityGroup = {
GI_comp = @Chicago, @NewYork, @SanFrancisco, @LosAngeles;
GIGI_behaviorType = GIGBT_NON_EXCLUSIVE;
GIGI_numSelections = 2;
GIGI_selection = (ChunkHandle) ChunkOf(@SelectionList);
}
@chunk word SelectionList[2] = {
CITY_CHICAGO, CITY_SAN_FRANCISCO
};
In most cases, the user will change the selections of the GenItemGroup by clicking on items. Your application may also retrieve or alter the items selected with the following messages. In many of these messages, you may have to pass an indeterminate state; if you are unsure about what indeterminate state a list object should be in, pass FALSE. Most GenItemGroups do not need to worry about their indeterminate state.
None of the messages which alter the state or number of selections cause an apply or status message to be sent out by the GenItemGroup. If you wish to send out an apply or a status message in these cases, mark the GenItemGroup modified and send the object
MSG_GEN_APPLY
or
MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG
.
MSG_GEN_ITEM_GROUP_GET_SELECTION
returns the currently selected item for the GenItemGroup. If there are no items currently selected, this message will return GIGS_NONE. If there is more than one item selected, this message will only return the first item selected in that GenItemGroup. (You should use
MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS
in this case.)
MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS
returns the current list of selections for non-exclusive and extended-selection lists. You must pass this message a pointer to a buffer to hold the list of selections, along with the number of items the buffer can hold. Make sure to allocate enough space in this buffer, or the buffer will not be filled in. Also make sure to send this message with
@call
and not
@send
, as it passes a pointer. You can check for the number of items currently selected with
MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS
.
MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED
deselects any settings currently on so that the list will appear with no items selected. It takes a flag indicating whether the list should be in its indeterminate state. This message will also clear the object's modified flag. If you wish to set this flag, send the GenItemGroup a
MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE
after sending this message.
MSG_GEN_ITEM_GROUP_SET_SINGLE_SELECTION
sets a single selection for a GenItemGroup. Any old selections will be deselected automatically, regardless of the behavior type of the list. It takes a flag indicating whether the list should be in its indeterminate state. If the GenItemGroup is scrollable and exclusive, this message will usually ensure that the list will automatically scroll to the selected item. This message also clears the object's modified flag.
MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS
sets a a group of selections for a GenItemGroup. Any previously selected items will be deselected. The message must pass the number of selections and a pointer to the list of identifiers to set. This message will clear the GenItemGroup's modified flag.
word MSG_GEN_ITEM_GROUP_GET_SELECTION();
This message returns the current selection identifier for the GenItemGroup. If there is no selection, this message returns GIGS_NONE. If there are multiple selections, this message only returns the first selection. Use
MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS
for multiple selections. A selection may be returned even if the item is not usable, not enabled, or not in the GenItemGroup.
If you are using a GenItemGroup which may contain a selection of -1, you will want to call
MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS
to differentiate between the item with -1 being selected and GIGS_NONE.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Return: The current selection stored in the GenItemGroup's GIGI_
selection
instance field (or GIGS_NONE if there are no selections).
Interception: Generally not intercepted.
word MSG_GEN_ITEM_GROUP_GET_MULTIPLE_SELECTIONS(
word *selectionList,
word maxSelections);
This message returns the current list of selections for non-exclusive and extended-selection GenItemGroups. The caller must allocate a buffer for the entries and pass the size of that buffer. If there is insufficient space in the passed buffer, no entries will be filled in. You should call
MSG_GEN_ITEM_GET_NUM_SELECTIONS
beforehand in order to allocate the correct maximum size for the buffer.
This message returns the number of selections filled into the buffer. The buffer is filled in with the proper identifiers. The list of identifiers within the buffer will not be null-terminated.
If you are using an exclusive or exclusive-none list, use
MSG_GEN_ITEM_GROUP_GET_SELECTION
instead.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: selectionList A pointer to the buffer to store the selection entries.
Return: The total number of selections returned in the buffer.
Interception: Generally not intercepted.
word MSG_GEN_ITEM_GROUP_GET_NUM_SELECTIONS();
This message returns the GenItemGroup's current number of selections (stored in GIGI_
numSelections
), or zero if there is no selection.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Return: The number of selections in the GenItemGroup.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED(
Boolean indeterminate);
This message sets a GenItemGroup to show no selections; it should not be sent to an exclusive GenItemGroup. This message will also clear the GenItemGroup's modified flag. If you wish to set the modified flag, send the list a
MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE
.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: indeterminate Pass TRUE if the GenItemGroup should be marked indeterminate, FALSE otherwise.
Return: Nothing.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_SINGLE_SELECTION(
word identifier,
Boolean indeterminate);
This message sets exactly one selection for a GenItemGroup. Any previously-selected items will be deselected, regardless of the GenItemGroup's behavior type. To set items without disturbing other settings, use
MSG_GEN_ITEM_GROUP_SET_ITEM_STATE
. If the list is on-screen, this message will cause a visual update. If the GenItemGroup is scrollable, this message will usually ensure that the item selected will appear on-screen.
This message clears the list's modified state. If you wish to set the group modified, send it a
MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE
. You may set a selection that is not usable, not enabled, or even not in the GenItemGroup. (This is useful for linked GenItemGroups.)
Source: Unrestricted.
Destination: Any GenItemGroup.
Parameters: identifier The identifier (enumerated value) of the item to select.
Return: Nothing.
Interception: Generally not intercepted.
Tips: An item with a matching identifier need not be present to become the GenItemGroup's "selection." Using this knowledge, you can set up several "linked" GenItemGroups, each with only one selection. (See GenItemGroup Links for information and examples.)
void MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS(
word *selectionList,
word numSelections);
This message sets multiple selections for a GenItemGroup. The caller must pass a pointer to a list of identifiers that should be selected, along with the number of selections to set. This message will clear the GenItemGroup's modified flag. If you wish to set the group modified send it a
MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE
.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: selectionList A pointer to the buffer containing a list of item identifiers.
Return: Nothing.
Interception: Generally not intercepted.
GIGI_stateFlags, ATTR_GEN_ITEM_GROUP_SET_MODIFIED_ON_REDUNDANT_SELECTION, MSG_GEN_ITEM_GROUP_SET_INDETERMINATE_STATE, MSG_GEN_ITEM_GROUP_IS_INDETERMINATE, MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE, MSG_GEN_ITEM_GROUP_IS_MODIFIED
The GIGI_
stateFlags
contains flags relating to the state of the entire GenItemGroup. The two flags possible are
A GenItemGroup is in the indeterminate state if its GIGI_
stateFlags
contains the GIGSF_INDETERMINATE flag. GenItems cannot be in an indeterminate state by themselves; either the entire list is indeterminate or it is not. If you want individual items to be indeterminate, you may want to use a GenBooleanGroup object instead.
A GenItemGroup is in the modified state if its GIGI_
stateFlags
contains the GIGSF_MODIFIED flag. GenItems may not be in a modified state by themselves; either the entire list is modified or it is not. If you want to mark individual items as modified, you may want to use a GenBooleanGroup object instead.
In immediate mode, any user change to the GenItemGroup's state automatically sets the GIGSF_MODIFIED flag and also forces an "apply." Therefore, in immediate mode, any user changes will, by default, cause the apply action to be sent out immediately. In delayed mode, the GIGSF_MODIFIED flag is set, but an apply action will not automatically occur. The apply action will only occur when the user forces it (such as clicking on an "apply" trigger) or when the application forces it (by sending out a
MSG_GEN_APPLY
).
You can force an apply by sending the GenItemGroup
MSG_GEN_APPLY
. You can also override the default behavior, forcing the object to send out its notification message on all applies, by including
ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
in the object's instance data. Any time the object receives an "apply," the GenItemGroup will send out the notification message even if the object does not contain any modified GenItem children.
In general, if the user makes redundant changes (such as repeatedly selecting the same item) the group will not be marked modified--the group has not changed state since the last apply, so there is no need to send out a notification message. If, however, you wish for the group to be set modified on redundant changes, add the vardata attribute ATTR_GEN_ITEM_GROUP_SET_MODIFIED_ON_REDUNDANT_SELECTION to the object's instance data. Whenever the user makes any selection, the group will be marked modified.
To check whether a GenItemGroup is indeterminate, send it a
MSG_GEN_ITEM_GROUP_IS_INDETERMINATE
. The message will return
true
if the list is indeterminate,
false
if it is not.
To set a GenItemGroup indeterminate, send it
MSG_GEN_ITEM_GROUP_SET_INDETERMINATE_STATE
. Note that the messages to set a GenItemGroup's selections already provide an argument to set the GenItemGroup indeterminate.
To check whether a GenItemGroup has been modified, send it
MSG_GEN_ITEM_GROUP_IS_MODIFIED
. This will return
true
if the list has been modified,
false
if it has not. To set a GenItemGroup modified, send it a
MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE
.
void MSG_GEN_ITEM_GROUP_SET_INDETERMINATE_STATE(
Boolean indeterminateState);
This message sets the GenItemGroup's GIGSF_INDETERMINATE flag in its GIGI_
stateFlags
instance field. Usually this message is used in conjunction with
MSG_GEN_ITEM_GROUP_SET_MULTIPLE_SELECTIONS
. (
MSG_GEN_ITEM_GROUP_SET_NONE_SELECTED
and
MSG_GEN_ITEM_GROUP_SET_SINGLE_SELECTION
set the indeterminate state themselves.)
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: indeterminate Pass TRUE to mark the group indeterminate, FALSE to set the group not indeterminate.
Return: Nothing.
Interception: Generally not intercepted.
Boolean MSG_GEN_ITEM_GROUP_IS_INDETERMINATE();
This message checks whether a GenItemGroup is in the indeterminate state; it checks the GIGSF_INDETERMINATE flag in the GenItemGroup's GIGI_
stateFlags
.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Return: TRUE if the GenItemGroup is indeterminate, FALSE otherwise.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_MODIFIED_STATE(
Boolean modifiedState);
This message marks a GenItemGroup modified by setting the GIGSF_MODIFIED flag in its GIGI_
stateFlags
instance field.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: modifiedState TRUE to mark the list modified, FALSE otherwise.
Return: Nothing.
Interception: Generally not intercepted.
Boolean MSG_GEN_ITEM_GROUP_IS_MODIFIED();
This message checks whether a GenItemGroup has been modified by checking the GIGSF_MODIFIED flag in the GenItemGroup's GIGI_
stateFlags
.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: None.
Return: TRUE if GenItemGroup is marked modified, FALSE otherwise.
Interception: Generally not intercepted.
GIGI_applyMsg, GIGI_destination, GEN_ITEM_GROUP_APPLY_MSG, ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED, MSG_GEN_ITEM_GROUP_GET_DESTINATION, MSG_GEN_ITEM_GROUP_SET_DESTINATION, MSG_GEN_ITEM_GROUP_GET_APPLY_MSG, MSG_GEN_ITEM_GROUP_SET_APPLY_MSG
When the GenItemGroup receives notice to apply any changes to its state, it will first check its GIGSF_MODIFIED flag. If the list has been modified, the GenItemGroup will send the apply action stored in its GIGI_
applyMsg
field to the destination stored in its GIGI_
destination
field.
GIGI_
applyMsg
stores the apply action you wish the GenItemGroup to send out whenever you make a selection choice within the group. This message should be based on the prototype GEN_ITEM_GROUP_APPLY_MSG so that the proper arguments (
selection
,
numSelections
, and
stateFlags
) are automatically passed. GIGI_
destination
should store the object or process you wish to handle the message sent out by this group. This object should have a handler for the GIGI_
applyMsg
.
You can force a GenItemGroup to apply its changes with
MSG_GEN_APPLY
. You can also override the default behavior, forcing the object to send out its apply action on all applies, whether modified or not, by including
ATTR_GEN_SEND_APPLY_MSG_ON_APPLY_EVEN_IF_NOT_MODIFIED
in the object's instance data. Any time the object needs to apply its changes, the GenItemGroup will send out the notification message even if the object is not marked GIGSF_MODIFIED.
To retrieve the object or process stored in the GenItemGroup's GIGI_
destination
instance field or the message stored in its GIGI_
applyMsg
instance field, send the list
MSG_GEN_ITEM_GROUP_GET_DESTINATION
or
MSG_GEN_ITEM_GROUP_GET_APPLY_MSG
.
To set the GenItemGroup's destination, send the list
MSG_GEN_ITEM_GROUP_SET_DESTINATION
, passing the optr of the new destination. To set the GenItemGroup's notification message, send the list
MSG_GEN_ITEM_GROUP_SET_APPLY_MSG
, passing it the message to use.
void GEN_ITEM_GROUP_APPLY_MSG(
word selection,
word numSelections
byte stateFlags);
Use this prototype to define the apply message for your GenItemGroup (stored in the GIGI_
applyMsg
instance field). This prototype ensures that the message passes the correct parameters to your message handler.
Source: Your GenItemGroup object.
Destination: Destination of your GenItemGroup.
Parameters: selection The current selection of the GenItemGroup.
Return: Nothing.
optr MSG_GEN_ITEM_GROUP_GET_DESTINATION();
This message returns the optr of the current destination object as specified in the GIGI_
destination
instance field.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: Nothing.
Return: The optr of the current destination object.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_DESTINATION(
optr dest);
This message sets a new destination object for the list, stored in the list's GIGI_
destination
field. The apply and status messages of this GenItemGroup will be sent to this new destination.
Source: Unrestricted.
Destination: Any GenItemGroup.
Parameters:
dest
The optr of the new destination object to be put in GIGI_
destination
.
Return: Nothing.
Interception: Generally not intercepted.
Message MSG_GEN_ITEM_GROUP_GET_APPLY_MSG();
This message returns the current apply message in the GenItemGroup's GIGI_
applyMsg
instance field.
Source: Unrestricted.
Destination: Any GenItemGroup.
Parameters: Nothing.
Return: The current apply message.
Interception: Generally not intercepted.
void MSG_GEN_ITEM_GROUP_SET_APPLY_MSG(
Message message);
This message sets a new apply message in the GenItemGroup's GIGI_
applyMsg
instance field.
Source: Unrestricted.
Destination: Any GenItemGroup object.
Parameters: message The new notification message.
Return: Nothing.
Interception: Generally not intercepted.
GEN_ITEM_GROUP_STATUS_MSG, ATTR_GEN_ITEM_GROUP_STATUS_MSG, MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG
If you wish your application to receive notice whenever the list's state changes, even if those changes will not be immediately applied, you may set a status message in the object's instance data.
For example, a color selection dialog box provides two means to set the RGB value of a color: one in a GenItemGroup listing the total possible states and another in a GenBooleanGroup with separate toggle states for Red, Green, and Blue. In delayed mode, setting the values in one group should change the display of the other group simultaneously but should not result in an apply action until the user activates the apply trigger.
One list can notify its partner of state changes with a status message. The other list can respond to state changes (and therefore change its corresponding state) without actually applying those changes.
To set up a status message, add a message based on the prototype GEN_ITEM_GROUP_STATUS_MSG. This message will be sent to the list's destination object. Set ATTR_GEN_ITEM_GROUP_STATUS_MSG to the status message.
Code Display 11-5 Status Message in GenItemGroup
/* Use the prototype GEN_ITEM_GROUP_STATUS_MSG to set up a status message. The * prototype takes three arguments: selection (the contents of GIGI_selection), * numSelections (the contents of GIGI_numSelections), and stateFlags (the contents * of GIGI_stateFlags). */
/* In the destination's class definition: */ @message (GEN_ITEM_GROUP_STATUS_MSG) MSG_COLOR_STATUS_CHANGE;
/* In the GenItemGroup's object declaration, set
* ATTR_GEN_ITEM_GROUP_STATUS_MSG to the message you declared. */
@object GenItemGroupClass MyColorGroup = {
GIGI_applyMsg = MSG_COLOR_CHANGE;
GIGI_destination = process;
ATTR_GEN_ITEM_GROUP_STATUS_MSG = MSG_COLOR_STATUS_CHANGE;
}
/* Finally, in your handler for this status message, do required work. */
@method MyProcessClass, MSG_COLOR_STATUS_CHANGE {
switch (selection) {
case C_BLACK:
/* ...(code)... */
case C_WHITE:
/* ...(code)... */
}
}
void GEN_ITEM_GROUP_STATUS_MSG(
word selection,
word numSelections,
byte stateFlags);
Use this prototype to define a status message for your GenItemGroup (stored in the ATTR_GEN_ITEM_GROUP_STATUS_MSG vardata). This prototype ensures that your status message passes the correct parameters.
Source: Your GenItemGroup object.
Destination: The destination of your GenItemGroup.
Parameters:
selection
The current selection (enumerated type stored in GIGI_
selection
) of the GenItemGroup.
numSelections
) of the GenItemGroup.
stateFlags
) of the GenItemGroup.Return: Nothing.
Tips: It is usually convenient to set up a switch statement based on the enumerated value of the selection passed in this message handler.
void MSG_GEN_ITEM_GROUP_SEND_STATUS_MSG(
Boolean modifiedState);
This message causes the GenItemGroup to send out the status message to the destination object. This status message is stored in
ATTR_GEN_ITEM_GROUP_STATUS_MSG
.
Source: Unrestricted.
Destination: Any GenItemGroup object that contains a status message.
Parameters: modifiedState Pass TRUE if the GenItemGroup should be marked modified.
Return: Nothing.
Interception: Generally not intercepted.
MSG_GEN_ITEM_GROUP_GET_FOCUS_ITEM, MSG_GEN_ITEM_GROUP_SET_FOCUS_ITEM
A GenItem in a GenItemGroup which has the cursor over it is said to have the focus. Your application may get or set the current focus of any exclusive GenItemGroup.
word MSG_GEN_ITEM_GROUP_GET_FOCUS_ITEM();
Gets the focus item of a GenItemGroup.
Source: Anywhere.
Destination: Any GenItemGroup.
Return: The identifier of the item which currently has the focus. If the GenItemGroup is not an exclusive list or if no item has focus, this message will return GIGS_NONE.
Tips: This message differs from MSG_META_GET_FOCUS_EXCL because it works on lists that don't have the focus and it does not suffer from possible synchronization problems.
void MSG_GEN_ITEM_GROUP_SET_FOCUS_ITEM(word identifier);
This message scrolls the GenItemGroup list so that the specified item will be the visible focus. While this message can be sent to a GenItemGroup at any time, it will only affect item groups which have already been visually built.
Source: Anywhere.
Destination: Any GenItemGroup.
Parameters:
Return: Nothing.
GEOS SDK TechDocs
|
| 3.2 GenItem Instance Data
| 3.4 Working with Items