Object

AppleEvent Class

AppleEvent objects can be used to communicate with other Macintosh applications and the Macintosh System software. If you are compiling your application for use on other operating systems, be sure to check the global Boolean constants TargetWin32, TargetMacOS, and TargetLinux.

Properties
BooleanParam | RecordParam | ReplyPtr
DescListParam | ReplyBoolean | ReplyRecord
DoubleParam | ReplyDescList | ReplySingle
EnumeratedParam | ReplyDouble | ReplyString
FolderItemParam | ReplyEnumerated | SingleParam
IntegerParam | ReplyFolderItem | StringParam
MacTypeParam | ReplyInteger | TimeOut
ObjectSpecifierParam | ReplyMacType |
Ptr | ReplyObjectSpecifier |

Methods
LoadFromTemplate
Send
SetNullParam

# Notes

These constants return True if the application is running on the respective operating system.

AppleEvent objects are used to send and receive information between your application and other Macintosh applications or the Mac OS. To send an AppleEvent from your application to another application, create an AppleEvent with the NewAppleEvent function, fill in the AppleEvent's properties with any necessary data, then call the AppleEvent's Send function to send it.

AppleEvents can also be received by your application. When an AppleEvent is received, the Application object's HandleAppleEvent event is executed and the AppleEvent is passed to the event as a parameter. All intrinsic AppleEvents are first passed to the Application object's HandleAppleEvent event handler. If you return True from this event, the default behavior of the AppleEvent will not be executed. For more information on receiving AppleEvents, see the Application class.

## Replying To An AppleEvent

When an AppleEvent is received (via an AppleEvent handler) the ReplyBoolean, ReplyInteger, and ReplyString properties can be used to automatically send a reply back to the application that sent the AppleEvent. When sending an AppleEvent (via the Send method) the ReplyBoolean, ReplyInteger, and ReplyString properties can be used to get any reply the target application has sent back once it receives the AppleEvent.

For example, the line:

e.ReplyBoolean= True

indicates that the application successfully handled the AppleEvent message.

To determine whether the other application successfully handled a message, use code such as:

Dim ae as AppleEvent
Dim s as String
.
.
If ae.Send then //AE successfully sent
If ae.replyBoolean then
s = "Yes (handled)"
else
s = "Yes (unhandled)"
end if
else
s = "No"
end if

For more information on AppleEvents, please refer to Apple's Developer section in the internet.

# Examples

This example uses an AppleEvent to tell the Finder to open the Appearance control panel:

Dim a as AppleEvent
a = NewAppleEvent("aevt", "odoc", "MACS")
a.FolderItemParam("----")= SpecialFolder.ControlPanels.Child("Appearance")
If Not a.Send Then
MsgBox "The Appearance control panel could not be opened."
End if

In this example, the SimpleText application (which must be running for this particular example to work) is instructed to open two documents ("My Document" and "My Other Document") that are located in the folder with the REALbasic project:

Dim a as AppleEvent
Dim list as AppleEventDescList
a = NewAppleEvent("aevt", "odoc", "ttxt")
list = New AppleEventDescList
list.AppendFolderItem GetFolderItem("My Document")
list.AppendFolderItem GetFolderItem("My Other Document")
a.DescListParam("----") = list
If Not a.Send Then
MsgBox "The AppleEvent could not be sent."
End If

This example displays the version of the Mac OS that is running on the user's computer:

Dim ae as AppleEvent
Dim obj as AppleEventObjectSpecifier
Dim version as String
If TargetMacOS then
ae = NewAppleEvent("core","getd","MACS")
obj= GetPropertyObjectDescriptor(nil, "ver2")
ae.ObjectSpecifierParam("----") = obj
If Not ae.send() then
MsgBox "The event could not be sent."
else
version = ae.ReplyString
If (version <> "") then
MsgBox "The system version is apparently """ + version + """."
else
MsgBox "This version of the system software does not support this event."
end if
end if
else
MsgBox "This is not a Macintosh!"
end if

# See Also

AppleEventDescList, AppleEventObjectSpecifier classes; Application object; NewAppleEvent function; #If…#Else…#Endif statement; TargetLinux, TargetMacOS, TargetMacOSClassic, TargetWin32 constants.