Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Reference to Responding to Apple Events

Routines for Responding to Apple Events / Requesting User Interaction

AEInteractWithUser

You can use the AEInteractWithUser function to initiate interaction with the user when your application is a server application responding to an Apple event.

FUNCTION AEInteractWithUser (timeOutInTicks: LongInt; 
                             nmReqPtr: NMRecPtr; 
                             idleProc: IdleProcPtr): OSErr;

timeOutInTicks

The amount of time (in ticks) that your handler is willing to wait for a response from the user. You can specify a number of ticks or use one of the following constants:

CONST kAEDefaultTimeout = -1; {value determined }
{ by AEM}
kNoTimeOut = -2; {wait until reply }
{ comes back}

nmReqPtr

A pointer to a Notification Manager record provided by your application. You can specify NIL for this parameter to get the default notification handling provided by the Apple Event Manager.

idleProc

A pointer to your application's idle function, which handles events while waiting for the Apple Event Manager to return control.

DESCRIPTION

Your application should call the AEInteractWithUser function before displaying a dialog box or alert box or otherwise interacting with the user in response to an Apple event. If the user interaction preference settings permit the application to come to the foreground, this function brings your application to the front, either directly or by posting a notification request.

Your application should normally pass a notification record in the nmReqPtr parameter rather than specifying NIL for default notification handling. If you specify NIL, the Apple Event Manager looks for an application icon with the ID specified by the application's bundle ('BNDL') resource and the application's file reference ('FREF') resource. The Apple Event Manager first looks for an 'SICN' resource with the specified ID; if it can't find an 'SICN' resource, it looks for the 'ICN#' resource and compresses the icon to fit in the menu bar. The Apple Event Manager won't look for any members of an icon family other than the icon specified in the 'ICN#' resource.

If the application doesn't have 'SICN' or 'ICN#' resources, or if it doesn't have a file reference resource, the Apple Event Manager passes NIL to the Notification Manager, and no icon appears in the upper-right corner of the screen. Therefore, if you want to display any icon other than those of type 'SICN' or 'ICN#', you must specify a notification record as the second parameter to the AEInteractWithUser function.

Note

If you want the Notification Manager to use a color icon when it posts a notification request, you should provide a Notification Manager record that specifies a 'cicn' resource.

The AEInteractWithUser function checks whether the client application set the kAENeverInteract flag for the Apple event and, if so, returns an error. If not, then the AEInteractWithUser function checks the server application's preference set by the AESetInteractionAllowed function and compares it against the source of the Apple event--that is, whether it came from the same application, another process on the same computer, or a process running on another computer. The AEInteractWithUser function returns the errAENoUserInteraction result code if the user interaction preferences don't allow user interaction. If user interaction is allowed, the Apple Event Manager brings your application to the front, either directly or by posting a notification request. If AEInteractWithUser returns the noErr result code, then your application is in the foreground and is free to interact with the user.

RESULT CODES

noErr	0	No error
errAETimeout	-1712	Apple event timed out
errAENoUserInteraction	-1713	No user interaction allowed

SEE ALSO

For information about idle functions, see "Writing an Idle Function" on page 5-22.

For examples of the use of the AEInteractWithUser function, see "Interacting With the User," which begins on page 4-47.