The List Objects: 3.4 GenItemGroups: Working with Items

| Up: GEOS SDK TechDocs | Up | Prev: 3.3 GenItemGroup Basics | Next: 3.5 Scrolling GenItemGroups

With several GenItem and GenItemGroup messages, you can work with individual items. The following sections detail these messages.

Altering the Identifiers

MSG_GEN_ITEM_GET_IDENTIFIER, MSG_GEN_ITEM_SET_IDENTIFIER, MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER

You may change the identifiers of GenItems dynamically. To retrieve a GenItem's identifier, send the GenItem MSG_GEN_ITEM_GET_IDENTIFIER . To set a GenItem's identifier, send it MSG_GEN_ITEM_SET_IDENTIFIER , passing the message the value you wish to set it to. Make sure that this value is unique and not duplicated by any other GenItem in the same GenItemGroup.

To generate a unique identifier for an item in a group, the GenItemGroup may use MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER .

MSG_GEN_ITEM_GET_IDENTIFIER

word	MSG_GEN_ITEM_GET_IDENTIFIER();

This message returns the identifier stored in the item's GII_ identifier instance field.

Source: Unrestricted.

Destination: Any GenItem object.

Return: The identifier of the GenItem object.

Interception: Generally not intercepted.

MSG_GEN_ITEM_SET_IDENTIFIER

void	MSG_GEN_ITEM_SET_IDENTIFIER(
        word	identifier);

This message sets a GenItem's GII_ identifier instance field to a new value. There is no effect on the list itself. The item whose identifier is changed must not be currently selected. It is therefore up to the application to make sure that the item is de-selected before changing its identifier.

Source: Unrestricted.

Destination: Any GenItem object.

Return: Nothing.

Interception: Generally not intercepted.

Warnings: The new enumerated value should be unique among all of the items in the list. Use MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER .

MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER

word	MSG_GEN_ITEM_GROUP_GET_UNIQUE_IDENTIFIER();

This message returns an identifier that is unique among the items in the GenItemGroup's group. It does not check across links, however.

Source: Unrestricted.

Destination: Any non-usable GenItemGroup object.

Parameters: None.

Return: The unique item identifier.

Interception: Generally not intercepted.

Altering the Item's State

MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR, MSG_GEN_ITEM_GROUP_SET_ITEM_STATE, MSG_GEN_ITEM_GROUP_IS_ITEM_SELECTED

You can retrieve the optr of a selection by sending the GenItemGroup a MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR , passing the identifier of the requested item. You may then use this item optr to send messages directly to the individual items or to set items enabled/disabled, usable/not usable, etc. If the item is not found, this message will return null.

You may also set an item selected without altering any other settings in the GenItemGroup. Send the list a MSG_GEN_ITEM_GROUP_SET_ITEM_STATE , passing it the identifier of the item to mark as selected. If the list is exclusive or exclusive-none, any other settings will be deselected; if the list is extended-selection or non-exclusive, the other settings will remain intact.

To check on whether an item is selected, send the GenItemGroup a MSG_GEN_ITEM_GROUP_IS_ITEM_SELECTED , passing it the identifier of the item in question. This message will return true if the item is currently selected, false if it is not.

Send MSG_GEN_ITEM_GROUP_MAKE_ITEM_VISIBILE to force a scrolling GenItemGroup to scroll to an item. Pass this message the identifier of the requested item. This message has no effect on non-scrolling lists.

MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR

optr	MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR(
        word	identifier);

This message returns the optr of a GenItem within a GenItemGroup. You may then use this optr for directly manipulating the GenItem. If an item with the requested identifier is not found as one of the GenItemGroup's children, this message will return a null optr.

Source: Unrestricted.

Destination: Any GenItemGroup object.

Parameters: identifier The identifier of the item to search for (stored in the GenItem's GII_ identifier instance field).

Return: The optr of the GenItem with the requested identifier (or a null optr if none is found).

Interception: Generally not intercepted.

MSG_GEN_ITEM_GROUP_SET_ITEM_STATE

void	MSG_GEN_ITEM_GROUP_SET_ITEM_STATE(
        word		identifier,
        Boolean		state);

This message sets the state (selected or unselected) of a particular GenItem within a GenItemGroup. Other items will be unaffected by the new state. This message also clears the GenItemGroup's modified state. If an identifier is passed which does not match an item within the GenItemGroup (or matches a not usable item), it will still be made the selection.

Source: Unrestricted.

Destination: Any GenItemGroup object.

Parameters: identifier The identifier of the item to change state.

state
TRUE to mark item selected, FALSE to mark item unselected.

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.)

MSG_GEN_ITEM_GROUP_IS_ITEM_SELECTED

Boolean	MSG_GEN_ITEM_GROUP_IS_ITEM_SELECTED(
        word	identifier);

This message checks whether an item within a GenItemGroup is selected, even if that item is not usable, not enabled, or not within the GenItemGroup. The message returns true if the item is selected, false if it is not selected.

Source: Unrestricted.

Destination: Any GenItemGroup object.

Parameters: identifier The identifier of the item to check for.

Return: Will return true if the item is selected, false if it is not.

Interception: Generally not intercepted.

| Up: GEOS SDK TechDocs | Up | Prev: 3.3 GenItemGroup Basics | Next: 3.5 Scrolling GenItemGroups