Name
ListRequest -- open a list requester (V6.0, optional)
Synopsis
int error = ListRequest(APTR handle, STRPTR title, STRPTR body, STRPTR
               choices, ULONG flags, int *result, struct hwTagList *tags);
Function
This function must open a list requester that prompts the user to select one item from a list of choices. The list of choices is passed in the fourth parameter as a list of an unlimited number of strings which are separated by NULL characters. The end of this list is marked by two NULL characters.

Your implementation has to write the index of the list item chosen by the user to the result parameter which is a pointer to an int. List items are counted from 0 which marks the first item. If the user has cancelled the requester, your ListRequest() implementation has to write -1 to the result pointer.

Hollywood also passes a taglist to this function. Your implementation has to handle the following tags:

HWLISTREQTAG_FROMSCRIPT:
The iData member of this tag item is set to True if Hollywood has called you while the script is running. This might be important to know because requesters should not block window refresh so you might want to setup a temporary modal event loop if this tag has been set to True to enable your display to stay responsive.

HWLISTREQTAG_ACTIVE:
If this tag is provided, Hollywood wants your list requester to preselect the list item at the index specified in this tag item's iData member. Item indices are counted from 0 so if iData is 0, you'd have to preselect the first list item.

Note that Hollywood won't call FreeRequest() for this requester type because ListRequest() shouldn't have to allocate any resources.

ListRequest() is an optional API and must only be implemented if HWSRAFLAGS_LISTREQUEST has been passed to hw_SetRequesterAdapter(). See hw_SetRequesterAdapter for details.

Inputs
handle
display handle or NULL if no display is open
title
title string for the requester's window
body
message string for the requester's body
choices
list of strings separated by NULL characters
flags
for future use (currently 0)
result
int pointer for storing the user's selection
tags
taglist for additional options (see above)
Results
error
error code or 0 for success

Show TOC