The List Objects: 4.2 GenDynamicListClass: DynamicList Basics

MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER, MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER_OPTR, MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT

You will need to perform several preparatory steps in order to use a GenDynamicList object, even in its most basic form. The following steps are required for all dynamic lists.

Create a GenDynamicList object. You must include the number of items to appear in your list (or set them dynamically when this number is known) and a query message to handle the extraction and display of monikers from a list of data.
Create a list of data to use as entries in the list. For simplicity, this can be a chunk of data containing a list of visual monikers, although the data may come from any source--as long as you provide the means to convert the data into monikers.
Create a query message handler to search through the list of data. This handler should convert any data into a proper format (if necessary) and send the moniker to the dynamic list to display the item. You can convert the data into a proper format by using one of several messages provided with GenDynamicListClass . These messages may take text strings, visual monikers, or other forms of data to set the monikers for the dynamic list.

Code Display 11-6 Creating a GenDynamicList object

/* In the definition of your destination object's class, define a message based
 * on the prototype GEN_DYNAMIC_LIST_QUERY. This prototype passes two arguments:
 * list (the optr of the list sending info) and item (the selection enum). */

@message (GEN_DYNAMIC_LIST_QUERY_MSG) MSG_QUERY_COLOR_MONIKER;

/* Set up the selections, just as you would in a normal GenItemGroup. */

typedef enum {
    MC_RED, MC_YELLOW, MC_BLUE, MC_GREEN
} MyColors;
#define NUM_COLORS MC_GREEN+1

/* In the object declaration, include normal instance data for a GenItemGroup,
 * making sure to also fill in GDLI_numItems and GDLI_queryMsg with the proper
 * information. Note that there are no generic children provided for this object.
 * The list will retrieve and display monikers automatically through the query
 * message as they are needed. */

@object GenDynamicListClass MyList = {
    /* Set the initial selection MC_BLUE (and the number of items selected to 1).*/

    GIGI_selection = MC_BLUE;
    GIGI_applyMsg = MSG_NOTIFY_COLOR_CHANGE;
    GIGI_destination = process;

    /* Set numItems to the total number of items to appear in this list. If you
     * will not know this initially, make sure to set this instance data when you
     * do know (with MSG_GEN_DYNAMIC_LIST_INITIALIZE). */

    GDLI_numItems = NUM_COLORS;
    GDLI_queryMsg = MSG_QUERY_COLOR_MONIKER;
    HINT_ITEM_GROUP_SCROLLABLE;
}

When a dynamic list is first built, the specific UI will decide how many items within the scrolling list should be initially displayed. For each of these items, the dynamic list will send out a query message, passing the number (position) of the item to search for. The querying message will search through a list of data (either custom or pre-existing), extracting and converting the data into text, graphics strings, or visual monikers, etc.

Finally, your query message handler should set each moniker in the list using one of the MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER messages. There are three messages to set the moniker of a dynamic list entry:

MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER This is a general purpose moniker replacement message. It can take a variety of source types (optrs, fptrs, hptrs), data types (visMonikers, text strings, graphics strings, or even geode tokens), and (in the case of graphics strings) the height and width of the moniker. This message also provides a flag allowing a moniker entry to appear visually disabled (grayed out in OSF/Motif).
MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER_OPTR This is a simplified version of the above message which takes a visual moniker and displays it within the dynamic list. The message's only arguments are the item in the list to update and the optr of the moniker for that item.
MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT This is another simplified version of the first message which takes a text string and displays it within the dynamic list. The message's only arguments are the item in the list to update and a pointer to the text string to use.

The simpler messages are useful if your data is a list of complete visual moniker structures or is a list of text strings. If you need to retrieve special data (such as GStrings or geode tokens), or if you need to perform special operations on the moniker (such as bringing it up disabled), then you must use MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER .

The data itself may be placed in several areas of your code. If the data is simple text strings, set up within an array, it may appear within the dynamic list's object block, its own resource block, or within the handler for the query message. If the data is visual monikers, the data must appear within a resource block.

If the data is within a different block from the dynamic list, that block must be locked before its data can be accessed. Make sure to unlock the block after using the data.

Code Display 11-7 Creating the List of Data

/* Create the list of data (in this case within its own data block). This list of
 * data will be in form of text strings. */

@start ItemText, data;

@chunk char *listMonikers[NUM_COLORS] = {
    "Red", "Yellow", "Blue", "Green"
};

@end ItemText

/* Create the query message handler. Each time the GenDynamicList needs to display
 * an item, it will call this querying message with the number (position) of the
 * item it needs to display. In this case, since the monikers are already in the
 * form of text strings, you can use MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT
 * to set the moniker of the list item using the text string.
 * DEFINITION: void MSG_QUERY_COLOR_MONIKER(optr list, word item) */

@method MyProcessClass, MSG_QUERY_COLOR_MONIKER {
char *listString;
    /* The method will retrieve the entry's text moniker from the array of
     * text monikers in listMonikers. It locks itemText, extracts the
     * text string, and uses the REPLACE_ITEM message to set the dynamic list
     * entry. */

    MemLock(HandleOf(@listMonikers));
    listString = listMonikers[item];

	/* Then send off the item string to the dynamic list
	 * and unlock the data block. */
    @call listObject::MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT(item, listString);
    MemUnlock(HandleOf(@listMonikers));
}

MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER

void	MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER(@stack
        word			item,
        word			flags,
        word			height,
        word			width,
        word			length,
        VisMonikerDataType			dataType,
        VisMonikerSourceType			sourceType,
        dword			source);

This message sends a moniker to use for a particular list item and is usually sent in response to a moniker query by a dynamic list object. Within your query message handler (GDLI_queryMsg ), you should access the data for the moniker to use and send off this message with the proper parameters. You may also use this message to change an item's moniker, guaranteeing that it is updated if currently visible.

If you pass this message the flag RIMF_NOT_ENABLED, the moniker for the item will be disabled (usually grayed out).

On the Nokia 9000i Communicator devices, you can use the routine CreateVisMonikerLine() to to arrange the line's contents so that they will form columns when displayed with similarly arranged lines.

This is an all-purpose message that allows many different source types and many ways to reference the data in these sources. If you are using lists of visual monikers or simple text strings and you do not to perform any fancy operations on this data, you may use MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER_OPTR or MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT .

Source: The object handling a dynamic list's query message.

Destination: The GenDynamicList specified in the query message.

Parameters: item The position of the item needing a moniker.

flags: RIMF_NOT_ENABLED if the item's moniker should be shown disabled.
height: If the item is a GString, the height in points.
width: If the item is a GString, the width in points.
length: Size of moniker data, in bytes. This value is ignored for VMST_OPTR. If the dataType is VMDT_TEXT and length is zero, the text moniker is assumed to be null-terminated. If the dataType is VMDT_GSTRING and the length is zero, the GString is assumed to end with a GR_END_GSTRING element.
dataType: The VisMonikerDataType of the actual moniker.
sourceType: The type of pointer referencing the moniker.
source: A pointer to the moniker data.

Structures: The VisMonikerDataType and VisMonikerSourcetype are defined by VisClass . Their values are shown here for easy reference.

  typedef ByteEnum VisMonikerDataType;
/*	VMDT_NULL
 *	VMDT_VIS_MONIKER
 *	VMDT_TEXT
 *	VMDT_GSTRING
 *	VMDT_TOKEN */

  typedef ByteEnum VisMonikerSourceType;
/*	VMST_FPTR
 *	VMST_OPTR
 *	VMST_HPTR */

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER_OPTR

void	MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER_OPTR(
        word	item,
        optr	moniker);

This message is a simplified version of MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER . The moniker must be of type VisMoniker and referenced by an optr. No special operations (such as marking the item disabled) are possible with this message. In those cases, use MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER .

Source: The object handling a dynamic list's query message.

Destination: The GenDynamicList object specified by the query message.

Parameters: item The position of the item to display.

optr: The optr of the VisMoniker to use.

Return: Nothing.

Interception: Generally not intercepted.

MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT

void	MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_TEXT(
        word	item,
        char	*text);

This message is a simplified version of MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER . The moniker passed must be a null-terminated text string. No special operations (such as marking the item disabled) are possible with this message. In those cases, use MSG_GEN_DYNAMIC_LIST_REPLACE_ITEM_MONIKER .

Source: The object handling a dynamic list's query message.

Destination: The GenDynamicList object specified by the query message.

Parameters: item The position of the item to display.

text: A pointer to the null-terminated text string.

Return: Nothing.

Interception: Generally not intercepted.

GEOS SDK TechDocs |

4.1 DynamicList Instance Data | Next:

4.3 Altering Instance Data