6. Building and sending events
The Application#event
method
The Application#event
method is used to create new Apple events targetted at the specified application.
Application -- the target application
...
event(event_code, params={}, atts={}, return_id=KAE::KAutoGenerateReturnID,
codecs=DefaultCodecs) -- construct an Apple event
event_code : string -- 8-letter code indicating event's class and id,
e.g. 'coregetd'
params : hash -- a hash of form {AE_code=>anything,...} containing
zero or more event parameters
atts : hash -- a hash of form {AE_code=>anything,...} containing
zero or more event attributes
return_id : integer -- reply event's ID
codecs : Codecs -- codecs object to use when packing/unpacking
attributes and parameters for this event and its reply
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(timeout=KAE::KDefaultTimeout, flags=KAE::KAEWaitReply) -- send event
timeout : integer | KAE::KDefaultTimeout | KAE::KNoTimeOut -- number of
ticks to wait for application reply before raising timeout error
flags : integer -- bitwise flags determining how event should be
handled
Result : anything -- value returned by application, if any
The send
method may be called any number of times.
Constants
The following constants are defined in the KAE
module.
Common parameter keys
KAE::KeyDirectObject
KAE::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
):
KAE::KeyTransactionIDAttr
KAE::KeyReturnIDAttr
KAE::KeyEventClassAttr
KAE::KeyEventIDAttr
KAE::KeyAddressAttr
KAE::KeyOptionalKeywordAttr
KAE::KeyTimeoutAttr
KAE::KeyInteractLevelAttr
KAE::KeyEventSourceAttr
KAE::KeyOriginalAddressAttr
KAE::KeyAcceptTimeoutAttr
KAE::EnumConsiderations
KAE::EnumConsidsAndIgnores
KAE::KeySubjectAttr
The value of the EnumConsiderations
attribute should be a list containing zero or more AEEnum
instances with the following codes:
KAE::KAECase
KAE::KAEDiacritic
KAE::KAEWhiteSpace
KAE::KAEHyphens
KAE::KAEExpansion
KAE::KAEPunctuation
KAE::KASConsiderReplies
KAE::KASNumericStrings
See the Apple Event Manager API reference 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:
KAE::KAECaseConsiderMask
KAE::KAEDiacriticConsiderMask
KAE::KAEWhiteSpaceConsiderMask
KAE::KAEHyphensConsiderMask
KAE::KAEExpansionConsiderMask
KAE::KAEPunctuationConsiderMask
KAE::KASConsiderRepliesConsiderMask
KAE::KASNumericStringsConsiderMask
KAE::KAECaseIgnoreMask
KAE::KAEDiacriticIgnoreMask
KAE::KAEWhiteSpaceIgnoreMask
KAE::KAEHyphensIgnoreMask
KAE::KAEExpansionIgnoreMask
KAE::KAEPunctuationIgnoreMask
KAE::KASConsiderRepliesIgnoreMask
KAE::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:
KAE::KAENoReply
KAE::KAEQueueReply
KAE::KAEWaitReply
KAE::KAEDontReconnect
KAE::KAEWantReceipt
KAE::KAENeverInteract
KAE::KAECanInteract
KAE::KAEAlwaysInteract
KAE::KAECanSwitchLayer
See the Apple Event Manager API reference for details.
Other constants
KAE::KAutoGenerateReturnID
Exception classes
The EventError
class
The EventError
class is raised by Event#send
and represents an error raised by the target application or Apple Event Manager when sending an event.
EventError < RuntimeError
Methods:
number
Result: integer -- Mac OS error number
message
Result: string | nil -- application-supplied/generic
error description
offending_object
Result: anything | nil -- object that caused the error,
if given by application
expected_type
Result: anything | nil -- object that caused a coercion
error, if given by application
partial_result
Result: anything | nil -- part of return value constructed
before error occurred, if given by application
to_i -- Mac OS error number
to_s -- formatted description of error
AE::MacOSError
The AE::MacOSError
exception is raised by the low-level 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 < StandardError
Methods:
number
Result: integer -- the Mac OS error number
description
Result: string -- short generic error description