BuildSysRequest

Build and display a system requester.

Declaration

Source position: intuition.pas line 3247

function BuildSysRequest(

Window: PWindow;

Body: PIntuiText;

PosText: PIntuiText;

NegText: PIntuiText;

Flags: LongWord;

Width: LongWord;

Height: LongWord

):PWindow;

Arguments

`Window`		A pointer to a Window structure
`Body`		A pointer to an IntuiText structure
`PosText`		A pointer to an IntuiText structure
`NegText`		A pointer to an IntuiText structure
`Flags`		The IDCMP flags you want used for the initialization of the IDCMP of the window containing this requester
`Width`		The width required to render your requester
`Height`		The height required to render your requester

Function result

If the requester was successfully created, the value returned by this procedure is a pointer to the window in which the requester is rendered. If the requester could not be created, this routine might have called DisplayAlert() before returning (it depends on the version) and will pass back True if the user pressed the left mouse button and False if the user pressed the right mouse button. If the version of Intuition doesn't call DisplayAlert(), or if it does, and there's not enough memory for the alert, the value of False is returned.

Description

This procedure builds a system requester based on the supplied information. If all goes well and the requester is constructed, this procedure returns a pointer to the window in which the requester appears. That window will have its IDCMP initialized to reflect the flags found in the IDCMPFlags argument. You may then wait on those ports to detect the user's response to your requester, which response may include either selecting one of the gadgets or causing some other event to be noticed by Intuition (like IDCMP_DISKINSERTED, for instance). After the requester is satisfied, you should call the FreeSysRequest() procedure to remove the requester and free up any allocated memory.

See the autodoc for SysReqHandler() for more information on the how to handle the IntuiMessages this window will receive.

The requester used by this function has the NOISYREQ flag bit set, which means that the set of IDCMPFlags that may be used here include IDCMP_RAWKEYIDCMP_RAWKEY, IDCMP_MOUSEBUTTONS, and others.

The function may return True (1) or False (nil) if it cannot post the requester.

If the window argument you supply is equal to NULL, a new window will be created for you in the Workbench screen. If you want the requester created by this routine to be bound to a particular window (i.e., to appear in the same screen as the window), you should not supply a window argument of nil.

If you pass a nil window pointer, the system requester will appear on the default public screen, which is not always the Workbench.

The text arguments are used to construct the display. Each is a pointer to an instance of the structure IntuiText.

The BodyText argument should be used to describe the nature of the requester. As usual with IntuiText data, you may link several lines of text together, and the text may be placed in various locations in the requester. This IntuiText pointer will be stored in the ReqText variable of the new requester.

The PosText argument describes the text that you want associated with the user choice of "Yes, True, Retry, Good." If the requester is successfully opened, this text will be rendered in a gadget in the lower-left of the requester, which gadget will have the GadgetID field set to True. If the requester cannot be opened and the DisplayAlert() mechanism is used, this text will be rendered in the lower-left corner of the alert display with additional text specifying that the left mouse button will select this choice. This pointer can be set to nil, which specifies that there is no True choice that can be made.

The NegText argument describes the text that you want associated with the user choice of "No, False, Cancel, Bad." If the requester is successfully opened, this text will be rendered in a gadget in the lower-right of the requester, which gadget will have the GadgetID field set to FALSE. If the requester cannot be opened and the DisplayAlert() mechanism is used, this text will be rendered in the lower-right corner of the alert display with additional text specifying that the right mouse button will select this choice. This pointer cannot be set to nil. There must always be a way for the user to cancel this requester.

The Positive and Negative Gadgets created by this routine have the following features:

When defining the text for your gadgets, you may find it convenient to use the special constants used by Intuition for the construction of the gadgets. These include defines like AUTODRAWMODE, AUTOLEFTEDGE, AUTOTOPEDGE and AUTOFRONTPEN.

These hard-coded constants are not very resolution or font sensitive.

The width and height values describe the size of the requester. All of your BodyText must fit within the width and height of your requester. The gadgets will be created to conform to your sizes.

Very important Note: for this release of this procedure, a new window is opened in the same screen as the one containing your window. Future alternatives may be provided as a function distinct from this one.

Note: This function will pop the screen the requester and its window appears in to the front of all screens. If the user doesn't perform any other screen arrangement before finishing with the requester, a popped screen will be pushed back behind.

FreeSysRequest		Free resources gotten by a call to BuildSysRequest().
DisplayAlert		Create the display of an alert message.
ModifyIDCMP		Modify the state of a window's IDCMPFlags.
Wait		Wait for one or more signals
Request		Activate a requester.
AutoRequest		Automatically build and get response from a requester.
EasyRequestArgs		Easy alternative to AutoRequest()
BuildEasyRequestArgs		Simple creation of system request.

BuildSysRequest

Declaration

Arguments

Function result

Description

See also