Name
SystemRequest -- open a system requester (V6.0, optional)
Synopsis
int error = SystemRequest(APTR handle, STRPTR title, STRPTR body,
                ULONG flags, int *result, struct hwTagList *tags);
Function
This function must open a system requester (also known as a message box) that presents the string passed in the body parameter to the user. The user then has to acknowledge the requester by pressing a button. The flags parameter specifies which button(s) should be shown and it also tells you whether or not there should be an icon the requester. The following flags are currently defined:

HWSYSREQTYPE_OK:
Requester should contain an "OK" button.

HWSYSREQTYPE_OKCANCEL:
Requester should contain "OK" and "Cancel" buttons.

HWSYSREQTYPE_YESNO:
Requester should contain "Yes" and "No" buttons.

HWSYSREQTYPE_YESNOCANCEL:
Requester should contain "Yes", "No", and "Cancel" buttons.

HWSYSREQTYPE_CUSTOM:
Requester should contain custom buttons. If this flag is set, Hollywood will pass a string in HWSYSREQTAG_CHOICES which contains the names for the custom buttons.

HWSYSREQICON_NONE:
There should be no icon in the requester.

HWSYSREQICON_INFORMATION:
There should be an information icon in the requester.

HWSYSREQICON_ERROR:
There should be an error icon in the requester.

HWSYSREQICON_WARNING:
There should be a warning icon in the requester.

HWSYSREQICON_QUESTION:
There should be a question icon in the requester.

Please note that all HWSYSREQTYPE_XXX and all HWSYSREQICON_XXX flags are mutually exclusive. There will only be one flag from each group set.

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

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

HWSYSREQTAG_CHOICES:
If the HWSYSREQTYPE_CUSTOM flag has been set, the pData member of this tag item contains a pointer to a string that contains the name(s) of one or more buttons. If there is more than one button, the individual button names will be separated by the vertical bar character (|). If this tag is provided, your implementation must setup a custom requester that contains the buttons specified here.

Your SystemRequest() implementation has to write the id of the button that has been pressed to the int pointer passed as the fifth parameter. The right-most button always has the id 0. If there is only one button, it will also have the id 0. The ids of the other buttons are counted from left to right starting at 1. This arrangement has been chosen so that in case there are two buttons like "OK|Cancel" or "Yes|No", the affirmative button's id will correspond to True whereas the negative response button's id will correspond to False.

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

SystemRequest() is an optional API and must only be implemented if HWSRAFLAGS_SYSTEMREQUEST 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
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