EasyRequestArgs

Easy alternative to AutoRequest(). (V36)

EasyRequest

Varargs stub for EasyRequestArgs(). (V36)

This function provides a simpler method of using a 'System Requester' than provided by AutoRequest(). It performs layout and size calculations sensitive to the current font and screen resolution.

It provides for the descriptive 'body' text and the gadget text to be constructed from 'printf' style format strings.

It also provides a general way for the requester to be sensitive to particular IDCMP messages.

The first function listed is the actual Intuition library function. It is passed the arguments for the formatting operations as a pointer to the first argument.

The second function uses a C-style variable number of argument (varargs) calling convention. It should be implemented as a call to the first function, and might be supplied by your compiler vendor, in amiga.lib, or using the first example below, for most C compilers.

NOTE:

The formatting is done by exec.library/RawDoFmt(), so

be aware that to display a 32-bit integer argument, for example, you must say "%ld", not "%d", since RawDoFmt() is "word-oriented."

NOTE:

This function switches the processor stack to ensure

sufficient stack space for the function to complete.

Window

Reference window pointer, determines the screen and title of the requester window. This can be NULL, which means the requester is to appear on the Workbench screen, or default public screen, if defined.

IDCMP_ptr

Pointer to IDCMP flags that you want to terminate the requester. This pointer may be NULL.

easyStruct

Pointer to EasyStruct structure with fields interpreted as follows:

es_StructSize

sizeof (struct EasyStruct), for future extension.

es_Flags

0 for now, in the future may specify other options.

es_Title

Title of system requester window. If this is NULL, the title will be taken to be the same as the title of 'Window', if provided, or else "System Request."

es_TextFormat

Format string, a la RawDoFmt(), for message in requester body. Lines are separated by the newline character. This character is represented in C by '\n', in the Amiga Shell by "*N", etc. Formatting '%' functions are supported exactly as in RawDoFmt().

es_GadgetFormat

Format string for gadgets. Text for separate gadgets is separated by '|'. Format functions are supported. You MUST specify at least one gadget.

ArgList

Arguments for format commands. Arguments for GadFmt follow arguments for TextFmt.

result

0, 1, ..., N Successive GadgetID values, for the gadgets you specify for the requester. NOTE: The numbering from left to right is actually: 1, 2, ..., N, 0. This is for compatibility with AutoRequest(), which has FALSE for the rightmost gadget.

The value -1 means that one of the caller-supplied IDCMPFlags occurred. The IDCMPFlag value is in the longword pointed to by IDCMP_ptr.

When DOS brings up EasyRequests() on your process (eg. "Please insert volume XXX in any drive", they normally come up on the default public screen, which is usually the Workbench screen. If you set your Process pr_WindowPtr field to point to one of your windows, then DOS will bring its requesters up on the same screen as that window. A pr_WindowPtr of -1 prevents requesters from coming up at all. (Some FileSystem requesters cannot be redirected or supressed).

Does not fall back to a recoverable alert if the requester cannot be created.

Does not handle case when gadgets don't fit or window title is too long, although it does trim trailing spaces from the title for calculating dimensions.

Possible enhancements include: centering of text, size-sensitive layout, window-relative requester, vertical gadget layout, window placement, more keyboard shortcuts.

We also reserve the use of the newline character ('\n') in gadget format strings for future use as a line separator.

exec.library/RawDoFmt(), BuildEasyRequestArgs(), SysReqHandler(), AutoRequest(), BuildSysRequest()