6. Building and sending events
The Application class's event method
The Application class's event method is used to create new Apple events targetted at the specified application.
event(self, event, params={}, atts={}, returnid=kae.kAEAutoGenerateReturnID,
codecs=None) -- construct an Apple event
event : bytes -- 8-letter code indicating event's class and id,
e.g. b'coregetd'
params : dict -- a dict of form {AE_code:anything,...} containing zero
or more event parameters (message arguments)
atts : dict -- a dict of form {AE_code:anything,...} containing zero
or more event attributes (event info)
returnid : int -- reply event's ID
codecs : Codecs | None -- custom codecs to use when packing/unpacking
this event; if None, codecs supplied in Application.__init__
are used
Result : Event -- a ready-to-send Apple event
The Event class
The Event class represents an Apple event that has been packed and is ready to send.
Event
Methods:
send(self, timeout=kae.kAEDefaultTimeout, flags=kae.kAEWaitReply) -- send event
timeout : int | kae.kAEDefaultTimeout | kae.kAENoTimeout -- no. of ticks
to wait for application reply before raising timeout error
flags : int -- bitwise flags determining how event should be handled
Result : anything -- value returned by application, if any
Constants
The following constants are defined in aem.kae.
Common parameter keys
keyDirectObject
keyAERequestedType
(The value for a keyAERequestedType parameter should be an AEType instance.)
Other parameter keys are defined by individual applications.
Attribute keys
Most of the following attributes are already supplied by other means (e.g. keyEventClassAttr, keyEventIDAttr are supplied separately when creating an Apple event; keyTimeoutAttr when sending it) and are only of interest if unpacking AppleEvent descriptors manually. A few may be used when passing an attributes dict to Application.event (enumConsiderations, enumConsidsAndIgnores, keySubjectAttr):
keyTransactionIDAttr
keyReturnIDAttr
keyEventClassAttr
keyEventIDAttr
keyAddressAttr
keyOptionalKeywordAttr
keyTimeoutAttr
keyInteractLevelAttr
keyEventSourceAttr
keyOriginalAddressAttr
keyAcceptTimeoutAttr
enumConsiderations
enumConsidsAndIgnores
keySubjectAttr
The value of the enumConsiderations attribute should be a list containing zero or more AEEnum instances with the following codes:
kAECase
kAEDiacritic
kAEWhiteSpace
kAEHyphens
kAEExpansion
kAEPunctuation
kASConsiderReplies
kASNumericStrings
See the Mac OS X Apple Event Manager documentation for more info. Note that the enumConsiderations attribute is deprecated in favour of the enumConsidsAndIgnores attribute.
The value of the enumConsidsAndIgnores attribute should be an integer composed from the sum of zero or more of the following bit masks:
kAECaseConsiderMask
kAEDiacriticConsiderMask
kAEWhiteSpaceConsiderMask
kAEHyphensConsiderMask
kAEExpansionConsiderMask
kAEPunctuationConsiderMask
kASConsiderRepliesConsiderMask
kASNumericStringsConsiderMask
kAECaseIgnoreMask
kAEDiacriticIgnoreMask
kAEWhiteSpaceIgnoreMask
kAEHyphensIgnoreMask
kAEExpansionIgnoreMask
kAEPunctuationIgnoreMask
kASConsiderRepliesIgnoreMask
kASNumericStringsIgnoreMask
Send flag constants
The value of the send method's flags argument should be an integer composed from the sum of zero or more of the following bit masks:
kAENoReply
kAEQueueReply
kAEWaitReply
kAEDontReconnect
kAEWantReceipt
kAENeverInteract
kAECanInteract
kAEAlwaysInteract
kAECanSwitchLayer
See the Mac OS X Apple Event Manager documentation for details.
Other constants
kAutoGenerateReturnID
Exception classes
aem.EventError
The aem.EventError exception is raised by Event.send and represents an error raised by the target application or Apple Event Manager when sending an event.
EventError(aem.ae.MacOSError)
Properties:
errornumber : int -- Mac OS error number
errormessage : str -- application-supplied/generic error description
offendingobject : anything | None -- object that caused the error,
if given by application
expectedtype : anything | None -- object that caused a coercion error,
if given by application
partialresult : anything | None -- part of return value constructed
before error occurred, if given
by application
Methods:
__int__(self) -- Mac OS error number
__str__(self) -- formatted description of error
aem.ae.MacOSError
The aem.ae.MacOSError exception is raised by the low-level aem.ae extension and represents an error raised by the Apple Event Manager. The aem API usually traps these low-level errors and throws more descriptive errors in their place (e.g. aem.EventError).
MacOSError(Exception)
Attributes:
args : list -- contains a single integer, the Mac OS error number
