Carbon


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
);
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 constants defined in “Timeout Constants”.

nmReqPtr

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.

idleProc

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

function result

A result code. The AEInteractWithUser function returns the errAENoUserInteraction result code if the user interaction preferences don’t 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.

DISCUSSION

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

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 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 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 “AESend” and “Preferences Constants for the AESend Function”.

See also AESetInteractionAllowed and AEGetInteractionAllowed.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.


© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)