rb-appscript

Previous • Up • Next appscript / mactypes / osax / aem

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
Previous • Up • Next