Name
StringRequest -- open a string requester (V6.0, optional)
Synopsis
int error = StringRequest(APTR handle, STRPTR title, STRPTR body,
               ULONG flags, STRPTR *result, struct hwTagList *tags);
Function
This function must open a string requester, i.e. a dialog box that prompts the user to enter a string. The function must then return this string to Hollywood by setting parameter 5 to a string pointer that your function has allocated. Hollywood will then call FreeRequest() on this string when it is done with it. If the user cancels the string requester, you have to write NULL to the result string pointer.

The flags and tags parameters are used to control further parameters of the string requester. The following flags are currently defined:

HWSTRINGREQTYPE_ALPHANUMERICAL:
If this flag is set, only alphabetical and numerical characters should be accepted by the requester.

HWSTRINGREQTYPE_ALPHABETICAL:
If this flag is set, only alphabetical characters should be accepted by the requester.

HWSTRINGREQTYPE_NUMERICAL:
If this flag is set, only numerical characters should be accepted by the requester.

HWSTRINGREQTYPE_HEXANUMERICAL:
If this flag is set, only hexadecimal numerical characters should be accepted by the requester, i.e. the letters A to F and the number 0 to 9.

HWSTRINGREQFLAGS_PASSWORD:
If this flag is set, the requester should open in password mode, i.e. it should not show the letters that are being entered.

Please note that all the HWSTRINGREQTYPE_XXX flags are mutually exclusive. Only one from this group will be set.

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

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

HWSTRINGREQTAG_DEFTEXT:
If this tag is in the list, Hollywood wants you to initialize the requester's string widget with the text provided in the string pointer in this tag item's pData member.

HWSTRINGREQTAG_MAXCHARS:
If this tag is set, your string requester should limit the text that can be entered to the number of characters provided in the iData member of this tag.

StringRequest() is an optional API and must only be implemented if HWSRAFLAGS_STRINGREQUEST 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
flags
flags controlling the requester's appearance (see above)
result
STRPTR pointer for storing the user's selection
tags
taglist for additional options (see above)
Results
error
error code or 0 for success
Show TOC