![]() |
AEInteractWithUser |
||||
Header: | AEInteraction.h | Carbon status: | Supported | |
Initiates interaction with the user when your application is a server application responding to an Apple event.
OSErr AEInteractWithUser ( SInt32 timeOutInTicks, NMRecPtr nmReqPtr, AEIdleUPP idleProc );
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 constants defined in
A pointer to a Notification Manager record provided by your application. You can specify NULL for this parameter to get the default notification handling provided by the Apple Event Manager.
A universal procedure pointer to your applications idle function, which handles events while waiting for the Apple Event Manager to return control.
A result code. The AEInteractWithUser function returns the errAENoUserInteraction result code if the user interaction preferences dont allow user interaction. If AEInteractWithUser returns the noErr result code, then your application is in the foreground and is free to interact with the user.
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. The AEInteractWithUser function checks whether the client application set the kAENeverInteract flag for the current Apple event, if any, and if so, returns an error. If not, then AEInteractWithUser checks the server applications preference set by the AESetInteractionAllowed function and compares it against the source of the Apple eventthat is, whether it came from the same application, another process on the same computer, or a process running on another computer.
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 NULL for default notification handling. If you specify NULL, the Apple Event Manager looks for an application icon with the ID specified by the applications bundle ('BNDL') resource and the applications file reference ('FREF') resource. The Apple Event Manager first looks for an 'SICN' resource with the specified ID; if it cant find an 'SICN' resource, it looks for the 'ICN#' resource and compresses the icon to fit in the menu bar. The Apple Event Manager wont look for any members of an icon family other than the icon specified in the 'ICN#' resource.
If the application doesnt have 'SICN' or 'ICN#' resources, or if it doesnt have a file reference resource, the Apple Event Manager passes no icon 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.
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.
For additional information on interaction level, see
See also AESetInteractionAllowed and AEGetInteractionAllowed.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)