The List Objects: 4.3 GenDynamicListClass: Altering Instance Data

| Up: GEOS SDK TechDocs | Up | Prev: 4.2 DynamicList Basics | Next: 5 GenBooleanGroups

You may alter the instance data of a GenDynamicList dynamically. Any of the appropriate GenItemGroup messages are valid for a GenDynamicList object except for MSG_GEN_ITEM_GROUP_GET_ITEM_OPTR .

Altering the Number of Items

MSG_GEN_DYNAMIC_LIST_INITIALIZE, MSG_GEN_DYNAMIC_LIST_GET_NUM_ITEMS

In order to ensure the proper display of monikers in a dynamic list, the list object must know the total number of items that may be displayed. In most cases, you will set this number in the initial instance data for the object. In some cases, however, you will not initially know how many entries may be displayed; the total number of items will only be known after the data block is accessed.

In these cases, you should use MSG_GEN_DYNAMIC_LIST_INITIALIZE , MSG_GEN_DYNAMIC_LIST_ADD_ITEMS or MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS to dynamically set the GDLI_ numItems instance field. You can retrieve the current number of items with MSG_GEN_DYNAMIC_LIST_GET_NUM_ITEMS .

MSG_GEN_DYNAMIC_LIST_INITIALIZE

void	MSG_GEN_DYNAMIC_LIST_INITIALIZE(
        word	numItems);

This message initializes a dynamic list, updating the display to reflect a new number of items or new data within the moniker list. If the list is already usable, this message invalidates all the current items and requests new monikers for all displayable items. The dynamic list will clear all previous selections; it will not scroll to any new selections. Use MSG_GEN_ITEM_GROUP_MAKE_ITEM_VISIBLE to scroll to a selected item.

This message is useful for cases when initially building a dynamic list without knowing the number of items; after you know the number of items, make sure to send the dynamic list this message.

Source: Unrestricted.

Destination: Any GenDynamicList object.

Parameters: numItems The new number of items for the dynamic list or GDLI_NO_CHANGE to keep the current number of selections.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_DYNAMIC_LIST_GET_NUM_ITEMS

word	MSG_GEN_DYNAMIC_LIST_GET_NUM_ITEMS();

This message returns the current number of items for a dynamic list. If no items are within the list, this message returns zero.

Source: Unrestricted.

Destination: Any GenDynamicList object.

Parameters: None.

Return: The number of items in the GenDynamicList (GDLI_ numItems ).

Adding and Removing Items Dynamically

MSG_GEN_DYNAMIC_LIST_ADD_ITEMS, MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS, MSG_GEN_DYNAMIC_LIST_REMOVE_ITEM_LIST

Part of the strength of a dynamic list is its ability to be easily updated with new data. MSG_GEN_DYNAMIC_LIST_ADD_ITEM S adds one or more new entries at any position in a dynamic list. The total number of items (GDLI_ numItems ) will be automatically incremented, and all entries after the added item will have their positions increased by one.

The constants GDLP_FIRST and GDLP_LAST indicate either the first or last item, respectively, and are available for use with these messages.

MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS removes one or more entries from any position within a dynamic list. The total number of items (GDLI_ numItems ) will be decremented, and all entries after the deleted item will have their positions decreased by one.

MSG_GEN_DYNAMIC_LIST_ADD_ITEMS

void	MSG_GEN_DYNAMIC_LIST_ADD_ITEMS(
        word	item,
        word	numItems);

This message adds an item after the position passed. All items that previously appeared at or after the position specified will have their positions incremented, and the total number of items will be incremented by numItems .

Usually, you will send this message after a change in the moniker data occurs. The moniker for the new item will be requested when it is made visible.

Source: Unrestricted.

Destination: Any GenDynamicList object.

Parameters: item The position of the first item to be added to the list. You may pass GDLP_FIRST to add the items at the beginning of the list or GDLP_LAST to add them at the end.

numItems
The number of items to add.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS

void	MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS(
        word	item,
        word	numItems);

This message removes the specified item(s) from a dynamic list at the position passed. All items that previously appeared after those deleted will have their positions decremented, and the total number of items will be decremented by the number of items removed.

Usually, you will send this message after a change in the moniker data. If the moniker for the deleted item is visible, a visual update will occur to reflect the list's new item positions. If the deleted item was selected, it will be deselected before being removed.

Source: Unrestricted.

Destination: Any GenDynamicList object.

Parameters: itemPosition The position of first item to be removed. GDLP_LAST or GDLP_FIRST specify the first or last position in the list.

numItems
The number of items to be removed.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_DYNAMIC_LIST_REMOVE_ITEM_LIST

void	MSG_GEN_DYNAMIC_LIST_REMOVE_ITEM_LIST(
        word	*deletionList,
        word	numItems);

This message removes a list of items from a dynamic list. Therefore, unlike MSG_GEN_DYNAMIC_LIST_REMOVE_ITEMS, this message can remove separate items that occur at different positions in the list. The message updates other item positions appropriately, causing a visual refresh, if necessary, and updates the total number of items.

Source: Unrestricted.

Destination: Any GenDynamic List.

Parameters: deletionList Pointer to buffer storing positions (word values) of the items to be removed.

numItems
Number of items being deleted.

Interception: Generally not intercepted.

| Up: GEOS SDK TechDocs | Up | Prev: 4.2 DynamicList Basics | Next: 5 GenBooleanGroups