[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

The text and setup of an easy requester is specified in an EasyStruct
structure, defined in <intuition/intuition.h>.

    struct EasyStruct
        {
        ULONG       es_StructSize;
        ULONG       es_Flags;
        UBYTE       *es_Title;
        UBYTE       *es_TextFormat;
        UBYTE       *es_GadgetFormat;
        };

es_StructSize
    Contains the size of the EasyStruct structure, sizeof(struct
    EasyStruct).

es_Flags
    Set to zero.

es_Title
    Title of easy requester window.  If this is NULL, the title will be
    taken to be the same as the title of the reference window, if one is
    specified in the EasyRequest() call, else the title will be "System
    Request".

es_TextFormat
    Format string for the text in the requester body, with printf()-style
    variable substitution as described in the Exec library function
    RawDoFmt().  Multiple lines are separated by the linefeed character
    (hex 0x0a or `\n' in C).  Formatting `%' functions are supported
    exactly as in RawDoFmt().  The variables that get substituted in the
    format string come from the last argument passed to EasyRequest()
    (see prototype above).

es_GadgetFormat
    Format string for gadgets, where the text for separate gadgets is
    separated by `|' (vertical bar).  As with the body text,
    printf()-style formatting with variable substitution is supported,
    but multi-line text in the gadgets is not supported.  At least one
    gadget must be specified.

Requesters generated with EasyRequest() and BuildEasyRequest() (including
system requesters, which use SysReqHandler() to handle input) can be
satisfied by the user via the keyboard.  The key strokes left Amiga V and
left Amiga B correspond to selecting the requester's leftmost or rightmost
gadgets with the mouse, respectively.

An easy request must have at least one choice.  Multiple choices are
specified through the "|" (vertical bar) separator character in the
es_GadgetFormat string.  The buttons are displayed evenly spaced, from
left-to-right in the order in which they appear in the string.

The requesters generated by EasyRequest() appear in the visible portion of
the specified screen.  They do not cause the screen to scroll.  Under the
current implementation, the window for an easy requester will appear in
the upper left corner of the display clip for the specified screen.

When a request is posted using EasyRequest() or BuildEasyRequest(), it
will move the screen it appears on to the front, if that screen is not
already the frontmost.  This brings the request to the attention of the
user.  The request also comes up as the active window and could
potentially steal the input focus from the current window.

When the request is satisfied the screen will be moved to back if the
request caused the screen to move to the front when it was displayed.
Note that the final screen position may not be the same as the original
screen position.

 Example Using EasyRequest()