Synopsis

APTR rtAllocRequest(
   ULONG type,
   Tag tag1,
   ...)

Function

Allocate and initialize a ReqTools requester structure.

Inputs

type - Requester type (RT_REQINFO, RT_FILEREQ, RT_FONTREQ,
       or RT_SCREENMODEREQ).
tag1 - First tag; terminate the tag/value sequence with TAG_DONE.

Result

Initialized requester structure, or NULL if allocation fails.

Notes

No allocation tags are currently defined. Release the structure
with rtFreeRequest().

See also

`rtAllocRequestA()`_ `rtFreeRequest()`_

Synopsis

LONG rtChangeReqAttr(
   APTR req,
   Tag tag1,
   ...)

Function

Change the attributes of an existing requester.

Inputs

req  - Requester whose attributes are to be changed.
tag1 - First attribute tag; terminate the sequence with TAG_DONE.

Result

Return value from rtChangeReqAttrA(). It is meaningful for tags
that explicitly define a result, including RTFI_AddEntry.

Notes

Attribute applicability, ordering constraints, and tag-specific
results are defined by rtChangeReqAttrA().

See also

`rtChangeReqAttrA()`_

Synopsis

ULONG rtEZRequest(
   const char *bodyfmt,
   const char *gadfmt,
   struct rtReqInfo *reqinfo,
   struct TagItem *taglist,
   ...)

Function

Display a formatted requester and obtain a user response.

Inputs

bodyfmt - Message format string.
gadfmt  - Gadget-label format string; separate choices with '|'.
reqinfo - Optional requester information.
taglist - Optional TagItem array controlling the requester.
...     - Formatting arguments for bodyfmt followed by gadfmt.

Result

Response code from rtEZRequestA(); the rightmost choice returns
zero. Other choices return their assigned positive values, or
an IDCMP value may be returned.

Notes

Formatting uses RawDoFmt conventions. This wrapper counts percent
conversions in both format strings to collect formatting arguments;
'%%' is treated as a literal percent sign.

Bugs

If allocation of the temporary argument array fails, the wrapper
writes through the NULL pointer when formatting arguments exist.

See also

`rtEZRequestA()`_ rtEZRequestTags()

Synopsis

ULONG rtEZRequestTags(
   const char *bodyfmt,
   const char *gadfmt,
   struct rtReqInfo *reqinfo,
   APTR argarray,
   Tag tag1,
   ...)

Function

Display a formatted requester using a variadic tag list.

Inputs

bodyfmt - Message format string.
gadfmt  - Gadget-label format string.
reqinfo - Optional requester information.
argarray - Formatting arguments for bodyfmt and gadfmt.
tag1    - First requester tag; terminate with TAG_DONE.

Result

Response code from rtEZRequestA().

Notes

This is the tag-varargs form of rtEZRequestA(). Formatting
arguments are supplied separately through argarray.

See also

`rtEZRequestA()`_ rtEZRequest()

Synopsis

APTR rtFileRequest(
   struct rtFileRequester * filereq,
   char *file,
   const char *title,
   Tag tag1,
   ...)

Function

Request a filename, directory, or multiple file selections.

Inputs

filereq - File requester allocated with rtAllocRequest().
file    - Initial filename and destination for the selected name;
          provide a buffer of at least 108 bytes.
title   - Requester window title.
tag1    - First requester tag; terminate with TAG_DONE.

Result

Result from rtFileRequestA(): nonzero for an accepted single
selection, zero on cancellation, or an rtFileList pointer when
multiple selection is enabled.

Notes

The file list returned for multiple selection is released with
rtFreeFileList(). The requester requires a process with DOS access.

See also

`rtFileRequestA()`_ rtAllocRequest() `rtFreeFileList()`_

Synopsis

ULONG rtFontRequest(
   struct rtFontRequester *fontreq,
   const char *title,
   Tag tag1,
   ...)

Function

Request a font and optional font style.

Inputs

fontreq - Font requester allocated with rtAllocRequest().
title   - Requester window title.
tag1    - First requester tag; terminate with TAG_DONE.

Result

Nonzero when a font is selected; zero on cancellation.

Notes

The selected font attributes are stored in the requester.
This requester may use DOS and must be called from a process.

See also

`rtFontRequestA()`_ rtAllocRequest()

Synopsis

ULONG rtGetLong(
   ULONG *longptr,
   char *title,
   struct rtReqInfo *reqinfo,
   Tag tag1,
   ...)

Function

Request a signed 32-bit integer.

Inputs

longptr - Address of the value to edit.
title   - Requester window title.
reqinfo - Optional requester information.
tag1    - First requester tag; terminate with TAG_DONE.

Result

Response code from rtGetLongA().

Notes

An empty numeric field can cause the leftmost gadget to return
zero without changing *longptr. See rtGetLongA() for the
complete response and validation contract.

See also

`rtGetLongA()`_

Synopsis

ULONG rtGetString(
   UBYTE *buffer,
   ULONG maxchars,
   const char *title,
   struct rtReqInfo *reqinfo,
   Tag tag1,
   ...)

Function

Request a line of text.

Inputs

buffer   - Input text and destination for the edited string.
maxchars - Maximum character count, excluding the terminator.
title    - Requester window title.
reqinfo  - Optional requester information.
tag1     - First requester tag; terminate with TAG_DONE.

Result

Response code from rtGetStringA().

Notes

The destination must accommodate maxchars characters and the
terminating NUL. Empty-input behavior depends on RTGS_AllowEmpty;
see rtGetStringA().

See also

`rtGetStringA()`_

Synopsis

LONG rtPaletteRequest(
   const char *title,
   struct rtReqInfo *reqinfo,
   Tag tag1,
   ...)

Function

Display a requester for editing or choosing a screen color.

Inputs

title   - Requester window title.
reqinfo - Optional requester information.
tag1    - First requester tag; terminate with TAG_DONE.

Result

Selected palette index, or -1 on cancellation.

Notes

The requester changes colors in the selected screen's viewport.

See also

`rtPaletteRequestA()`_

Synopsis

IPTR rtReqHandler(
   struct rtHandlerInfo *handlerinfo,
   ULONG sigs,
   Tag tag1,
   ...)

Function

Continue processing a requester started with RT_ReqHandler.

Inputs

handlerinfo - Handler state returned by the requester.
sigs        - Signals received since the previous call.
tag1        - First handler tag; terminate with TAG_DONE.

Result

CALL_HANDLER while additional handling is required; otherwise
the requester's normal completion result.

Notes

Check handlerinfo->DoNotWait and handlerinfo->WaitMask before
waiting for signals. Continue calling this function while it
returns CALL_HANDLER.

See also

`rtReqHandlerA()`_ `rtEZRequestA()`_

Synopsis

ULONG rtScreenModeRequest(
   struct rtScreenModeRequester *screenmodereq,
   char *title,
   Tag tag1,
   ...)

Function

Request a screen mode and its display parameters.

Inputs

screenmodereq - Screen-mode requester allocated with
                rtAllocRequest().
title         - Requester window title.
tag1          - First requester tag; terminate with TAG_DONE.

Result

Nonzero when the user accepts the selection; zero on cancellation.

Notes

The chosen display mode, dimensions, and depth are stored in
the requester structure.

See also

`rtScreenModeRequestA()`_ rtAllocRequest()