Important: The information in this document is obsolete and should not be used for new development.
AEInteractWithUser
You can use theAEInteractWithUser
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 theAEInteractWithUser
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 specifyingNIL
for default notification handling. If you specifyNIL
, 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 foran
'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 passesNIL
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 theAEInteractWithUser
function.
The
- 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.AEInteractWithUser
function checks whether the client application set thekAENeverInteract
flag for the Apple event and, if so, returns an error. If not, then theAEInteractWithUser
function checks the server application's preference set by theAESetInteractionAllowed
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. TheAEInteractWithUser
function returns theerrAENoUserInteraction
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. IfAEInteractWithUser
returns thenoErr
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.