Unit 'intuition' Package
[Overview][Constants][Types][Procedures and functions][Variables][Index] [#os4units]

SysReqHandler

Handle system requester input.

Declaration

Source position: intuition.pas line 3904

function SysReqHandler(

  Window: PWindow;

  IDCMPPtr: PLongWord;

  WaitInput: LongInt

):LongInt;

Arguments

Window

  

Window pointer returned from BuildSysRequest(). Those functions can also return values 0 or 1, and these values may also be passed to SysReqHandler(), which will immediately return the same value.

WaitInput

  

Specifies that you want SysReqHandler() to to wait for IDCMP input if there is none pending.

Function 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 AutoRequests which has FALSE for the rightmost gadget.

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

-2 = input processed did not satisfy the requester. One example is a keystroke that does not satisfy the requester. Another example is if there is no input pending and you specified False for WaitInput.

Description

Handles input for a window returned by either BuildSysRequest(). These functions with SysReqHandler() you can perform an "asynchronous" EasyRequest() or AutoRequest(). That is to say, you can perform other processing while you wait for the requester to be satisfied.

Each time this function is called, it will process all IDCMPMessages that the window has received. If the parameter WaitInput is non-zero, SysReqHandler() will wait for input (by calling WaitPort()) if there are no IDCMP messages.

SysReqHandler() returns the same values as EasyRequest(): A gadget ID greater than equal to 0, and -1 if one of the other IDCMP events were received.

An additional value of -2 is returned if the input processed does not satisfy the requester. In this case, you might perform some processing and call SysReqHandler() again.

Note: this function does not terminate the system request. Not only must you call FreeSysRequest() to eliminate the request, but you may also continue processing after an event which would normally terminate a normal call to EasyRequest().

Snippet

Implementation of EasyRequest input loop:

Window := BuildEasyRequest(...);
while SysReqHandler(Window, IDCMP_Ptr, True) = -2 do
begin
 // loop
end;
FreeSysRequest(Window);

Errors

Gadget placing is still untidy. Does not support BuildSysRequest() requesters, yet.

See also

WaitPort

  

Wait for a given port to be non-empty

BuildSysRequest

  

Build and display a system requester.


Documentation generated on: 2021-07-30