Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Interacting With the User

Setting the Client Application's User Interaction Preferences

The client application sets its user interaction preferences by setting flags in the sendMode parameter to the AESend function. The Apple Event Manager automatically adds the specified flags to the keyInteractLevelAttr attribute of the Apple event. These flags are represented by the following constants:

Flag	Description
kAENeverInteract	The server application should never interact with the user in response to the Apple event. If this flag is set, AEInteractWithUser returns the errAENoUserInteraction result code. This flag is the default when an Apple event is sent to a remote application.
kAECanInteract	The server application can interact with the user in response to the Apple event--by convention, if the user needs to supply information to the server. If this flag is set and the server allows interaction, AEInteractWithUser either brings the server application to the foreground or posts a notification request. This flag is the default when an Apple event is sent to a local application.
kAEAlwaysInteract	The server application can interact with the user in response to the Apple event--by convention, whenever the server application normally asks a user to confirm a decision or interact in any other way, even if no additional information is needed from the user. If this flag is set and the server allows interaction, AEInteractWithUser either brings the server application to the foreground or posts a notification request.

For example, suppose a client application sends a Set Data event to a database application to change a customer's address. The database application is configured to request user confirmation of changes to a customer's record. In this case the client sets the kAECanInteract flag before sending the event. Thus, the database application attempts to interact with the user if interaction is allowed. If interaction is not allowed, the database makes the correction anyway without consulting the user. However, if the client application sends a Delete event to delete a customer's record entirely and sets the kAEAlwaysInteract flag, the database application deletes the specified record only if it can interact with the user first and receives confirmation of the decision to delete a record. If interaction with the user is not allowed, the database application returns an error. By setting the kAEAlwaysInteract flag, the client application ensures that the entire record won't be lost if the user sends the Delete event by mistake.

If the client application doesn't specify any of the three user interaction flags, the Apple Event Manager sets either the kAENeverInteract or the kAECanInteract flag in the keyInteractLevelAttr attribute of the Apple event, depending on the location of the server application. If the server application is on a remote computer, the Apple Event Manager sets the kAENeverInteract flag as the default. If the server application is on the local computer, the Apple Event Manager sets the kAECanInteract flag as the default.

In addition to the three user interaction flags, the client application can set another flag in the sendMode parameter to AESend to request that the Apple Event Manager immediately bring the server application directly to the foreground instead of posting a notification request:

Flag	Description
kAECanSwitchLayer	If both the client and server allow interaction, and if the client application is the active application on the local computer and is waiting for a reply (that is, it has set the kAEWaitReply flag), AEInteractWithUser brings the server directly to the foreground. Otherwise, AEInteractWithUser uses the Notification Manager to request that the user bring the server application to the foreground.

Note that although the kAECanSwitchLayer flag must be set for the Apple Event Manager to bring the server application directly to the foreground, setting it does not guarantee that the Apple Event Manager will bypass the notification request if user interaction is permitted. Another flag, the kAEWaitReply flag, must also be set in the sendMode parameter, and the client application must provide an idle function.

The kAEWaitReply flag is one of three flags in the sendMode parameter that a client application can set to specify whether and how the client should wait for a reply. (For a description of these flags, see "Sending an Apple Event and Handling the Reply" on page 3-25.) If the client application is not waiting for a reply, the user may have continued with other work. An application switch at this point might be unexpected and would thus violate the principle of user control as described in Macintosh Human Interface Guidelines.

If the client application sets the kAEWaitReply flag, it should also provide an idle function when it calls AESend so that it can handle events such as update events that it receives while waiting for the reply. Idle functions are described in "Writing an Idle Function," which begins on page 5-22.

When a server application calls AEInteractWithUser, the function first checks whether the kAENeverInteract flag in the keyInteractLevelAttr attribute of the Apple event is set. (The Apple Event Manager sets this attribute according to the flags specified in the sendMode parameter of AESend.) If the kAENeverInteract flag is set, AEInteractWithUser immediately returns the errAENoUserInteraction result code. If the client specified kAECanInteract or kAEAlwaysInteract, AEInteractWithUser checks the server's preferences for user interaction.