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