Home  /  Autodocs  /  intuition.library

NAME

SysReqHandler
Handle system requester input. (V36)

SYNOPSIS

num = SysReqHandler( Window, IDCMPFlagsPtr, WaitInput )
D0 A0 A1 D0

LONG SysReqHandler( struct Window *, ULONG *, BOOL );

FUNCTION

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().

EXAMPLE

Implementation of EasyRequest() input loop:

window = BuildEasyRequest( ... )
while ( (retval = SysReqHandler( window, idcmp_ptr, TRUE )) == -2 )
{
/* loop */;
}
FreeSysRequest( window );

EXAMPLE

Request a volume, but don't remove the requester when the
user inserts the wrong disk:

struct EasyStruct volumeES = {
sizeof (struct EasyStruct),
0,
"Volume Request",
"Please insert volume %s in any drive.",
"Cancel"
};

Volume *
getVolume( volname )
UBYTE *volname;
{
struct Window *window;
Volume *volume = NULL;
Volume *findVolume();
int retval;

window = BuildEasyRequest( NULL, &volumeES, IDCMP_DISKINSERTED,
volname );

while ( (retval = SysReqHandler( window, NULL, TRUE )) != 0 )
{
/* not cancelled yet */

/* when IDCMP_DISKINSERTED, check for volume */
if (( retval == -1 ) && (volume = findVolume( volname )))
break;
}
FreeSysRequest( window );
return ( volume );
}

INPUTS

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 ULONG where the IDCMP class received will be copied for your examination.

This pointer can be NULL 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.

RESULT

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.

A value of -1 means that one of the caller-supplied IDCMPFlags occurred. The IDCMPFlag value is in the longword pointed to by UDCMP_ptr.

A value of -2 means 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.

SEE ALSO

exec.library/WaitPort()