Unit 'Intuition'	Package
[Overview][Constants][Types][Procedures and functions][Variables][Index]	[#aros]

SysReqHandler

Handle system requester input.

Declaration

Source position: intuition.pas line 3287

function SysReqHandler(

Window: PWindow;

IDCMPFlagsPtr: PLongWord;

WaitInput: LongBool

):LongInt;

Arguments

`Window`		Window pointer returned from BuildSysRequest() or BuildEasyRequest(). 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.
`IDCMPFlagsPtr`		If you passed application specific IDCMP flags to BuildSysRequest() or BuildEasyRequest(), SysReqHandler() will return -1 if that IDCMP message is received. If IDCMPFlagsPtr is non-null, it points to a LongWord where the IDCMP class received will be copied for your examination. This pointer can be nil if you have provided no application specific IDCMP flags or if you do not need to know which application specific IDCMP event occurred. If you provide more than on flag in the flags variable this pointer points to, you will have to refresh the variable whenever -1 is returned, since the variable will have been changed to show just the single IDCMP Class bit that caused the return.
`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() or BuildEasyRequest(). 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.