Mac Developer Library

Developer

ScriptingBridge Framework Reference SBApplication Class Reference

Options
Deployment Target:

On This Page
Language:

SBApplication

The SBApplication class provides a mechanism enabling an Objective-C program to send Apple events to a scriptable application and receive Apple events in response. It thereby makes it possible for that program to control the application and exchange data with it. Scripting Bridge works by bridging data types between Apple event descriptors and Cocoa objects. More...

Inheritance


Conforms To


Import Statement


import ScriptingBridge @import ScriptingBridge;

Availability


Available in OS X v10.5 and later
  • Returns the shared instance representing the target application specified by its bundle identifier.

    Declaration

    Swift

    class func applicationWithBundleIdentifier(_ ident: String!) -> AnyObject!

    Objective-C

    + (id)applicationWithBundleIdentifier:(NSString *)ident

    Parameters

    ident

    A bundle identifier specifying an application that is OSA-compliant.

    Return Value

    An instance of a SBApplication subclass that represents the target application whose bundle identifier is ident. Returns nil if no such application can be found or if the application does not have a scripting interface.

    Discussion

    For applications that declare themselves to have a dynamic scripting interface, this method will launch the application if it is not already running.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns the shared instance representing a target application specified by its process identifier.

    Declaration

    Swift

    class func applicationWithProcessIdentifier(_ pid: pid_t) -> AnyObject!

    Objective-C

    + (id)applicationWithProcessIdentifier:(pid_t)pid

    Parameters

    pid

    The BSD process ID of a OSA-compliant application. Often you can get the process ID of a process using the processIdentifier method of NSTask.

    Return Value

    An instance of an SBApplication subclass that represents the target application whose process identifier is pid. Returns nil if no such application can be found or if the application does not have a scripting interface.

    Discussion

    You should avoid using this method unless you know nothing about a target application but its process ID. In most cases, it is better to use classForApplicationWithBundleIdentifier:, which will dynamically locate the application's path at runtime, or classForApplicationWithURL:, which is not dependent on the target application being open at the time the method is called.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns the shared instance representing a target application specified by the given URL.

    Declaration

    Swift

    class func applicationWithURL(_ url: NSURL!) -> AnyObject!

    Objective-C

    + (id)applicationWithURL:(NSURL *)url

    Parameters

    url

    The Universal Resource Locator (URL) locating an OSA-compliant application.

    Return Value

    An SBApplication subclass from which to generate a shared instance of the target application whose URL is url. Returns nil if no such application can be found or if the application does not have a scripting interface.

    Discussion

    For applications that declare themselves to have a dynamic scripting interface, this method will launch the application if it is not already running. This approach to initializing SBApplication objects should be used only if you know for certain the URL of the target application. In most cases, it is better to use classForApplicationWithBundleIdentifier: which dynamically locates the target application at runtime.

    This method currently supports file URLs (file:) and remote application URLs (eppc:). It checks whether a file exists at the specified path, but it does not check whether an application identified via eppc: exists.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns an instance of an SBApplication subclass that represents the target application identified by the given bundle identifier.

    Declaration

    Swift

    init!(bundleIdentifier ident: String!)

    Objective-C

    - (id)initWithBundleIdentifier:(NSString *)ident

    Parameters

    ident

    A bundle identifier specifying an application that is OSA-compliant.

    Return Value

    An initialized shared instance of an SBApplication subclass that represents a target application with the bundle identifier of ident. Returns nil if no such application can be found or if the application does not have a scripting interface.

    Discussion

    If you must initialize an SBApplication object explictly, you should use this initializer if possible; unlike initWithProcessIdentifier: and initWithURL:, this method is not dependent on changeable factors such as the target application's path or process ID. Even so, you should rarely have to initialize an SBApplication object yourself; instead, you should initialize an application-specific subclass such as iTunesApplication.

    Note that this method does not check whether an application with the given bundle identifier actually exists.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns an instance of an SBApplication subclass that represents the target application identified by the given process identifier.

    Declaration

    Swift

    init!(processIdentifier pid: pid_t)

    Objective-C

    - (id)initWithProcessIdentifier:(pid_t)pid

    Parameters

    pid

    A BSD process ID specifying an application that is OSA-compliant. Often you can get the process ID of a process using the processIdentifier method of NSTask.

    Return Value

    An initialized SBApplication that you can use to communicate with the target application specified by the process ID. Returns nil if no such application can be found or if the application does not have a scripting interface.

    Discussion

    You should avoid using this method unless you know nothing about an external application but its PID. In most cases, it is better to use initWithBundleIdentifier:, which will dynamically locate the external application's path at runtime, or initWithURL:, which is not dependent on the external application being open at the time the method is called.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns an instance of an SBApplication subclass that represents the target application identified by the given URL.

    Declaration

    Swift

    init!(URL url: NSURL!)

    Objective-C

    - (id)initWithURL:(NSURL *)url

    Parameters

    url

    A Universal Resource Locator (URL) specifying an application that is OSA-compliant.

    Return Value

    An initialized SBApplication that you can use to communicate with the target application specified by the process ID. Returns nil if an application could not be found or if the application does not have a scripting interface.

    Discussion

    This approach to initializing SBApplication objects should be used only if you know for certain the URL of the target application. In most cases, it is better to use classForApplicationWithBundleIdentifier: which dynamically locates the target application at runtime. Even so, you should rarely have to initialize an SBApplication yourself.

    This method currently supports file URLs (file:) and remote application URLs (eppc:). It checks whether a file exists at the specified path, but it does not check whether an application identified via eppc: exists.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns a class object that represents a particular class in the target application.

    Declaration

    Swift

    func classForScriptingClass(_ className: String!) -> AnyClass!

    Objective-C

    - (Class)classForScriptingClass:(NSString *)className

    Parameters

    className

    The name of the scripting class.

    Return Value

    A Class object representing the scripting class.

    Discussion

    You invoke this method on an instance of a scriptable application. Once you have the class object, you may allocate an instance of the class and appropriately the raw instance. Or you may use it in a call to isKindOfClass: to determine the class type of an object.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Moves the target application to the foreground immediately.

    Declaration

    Swift

    func activate()

    Objective-C

    - (void)activate

    Discussion

    If the target application is not already running, this method launches it.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • isRunning isRunning Available in OS X v10.5 through OS X v10.9

    Returns whether the target application represented by the receiver is running.

    Declaration

    Objective-C

    - (BOOL)isRunning

    Return Value

    YEStrue if the application is running, NOfalse otherwise.

    Import Statement

    Availability

    Available in OS X v10.5 through OS X v10.9.

  • Returns the launch flags for the application represented by the receiver.

    Declaration

    Swift

    var launchFlags: LSLaunchFlags

    Objective-C

    @property LSLaunchFlags launchFlags

    Return Value

    A mask specifying the launch flags that are used when the target application is launched. For more information, see Launch Services Reference.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns the launch flags for the application represented by the receiver.

    Declaration

    Swift

    var launchFlags: LSLaunchFlags

    Objective-C

    @property LSLaunchFlags launchFlags

    Parameters

    flags

    A mask specifying the launch flags that are used when the target application is launched. For more information, see Launch Services Reference.

    Discussion

    The default SBApplication launch flags are kLSLaunchDontAddToRecents (so the target application is not added to the Recent Items menu), kLSLaunchDontSwitch (so the target application launches in the background), and kLSLaunchAndHide (so the target application is hidden as soon as it is launched).

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

    See Also

    – launchFlags

  • Returns the mode for sending Apple events to the target application.

    Declaration

    Swift

    var sendMode: AESendMode

    Objective-C

    @property AESendMode sendMode

    Return Value

    A mask specifying the mode for sending Apple events to the target application. For more information, see Apple Event Manager Reference.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Sets the mode for sending Apple events to the target application.

    Declaration

    Swift

    var sendMode: AESendMode

    Objective-C

    @property AESendMode sendMode

    Parameters

    sendMode

    A mask specifying the mode for sending Apple events to the target application. For a list of valid modes, see Apple Event Manager Reference.

    Discussion

    The default send mode is kAEWaitReply. If the send mode is something other than kAEWaitReply, the receiver might not correctly handle reply events from the target application.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

    See Also

    – sendMode

  • Returns the period the application will wait to receive reply Apple events.

    Declaration

    Swift

    var timeout: Int

    Objective-C

    @property long timeout

    Return Value

    The time in ticks that the receiver will wait to receive a reply Apple event from the target application before giving up. For more information, see Apple Event Manager Reference.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

    See Also

    – setTimeout:

  • Sets the maximum time the application will wait to receive reply Apple events.

    Declaration

    Swift

    var timeout: Int

    Objective-C

    @property long timeout

    Parameters

    timeout

    The time in ticks that the receiver will wait to receive a reply Apple event from the target application before giving up.

    Discussion

    The default timeout value is kAEDefaultTimeout, which is about a minute. If you want the receiver to wait indefinitely for reply Apple events, use kNoTimeOut. For more information, see Apple Event Manager Reference.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

    See Also

    – timeout

  • classNamesForCodes classNamesForCodes Available in OS X v10.5 through OS X v10.5

    Returns a dictionary mapping four-character class codes to the names of their corresponding Objective-C classes.

    Declaration

    Objective-C

    - (NSDictionary *)classNamesForCodes

    Return Value

    A dictionary whose keys are four-character class codes of the external application (as NSNumber objects), and whose values are the names of the corresponding SBObject subclasses.

    Discussion

    The default implementation returns an empty dictionary. Application-specific subclasses return dictionaries tailored to the types of objects they support.

    You should never call this method directly.

    Import Statement

    Availability

    Available in OS X v10.5 through OS X v10.5.

  • codesForPropertyNames codesForPropertyNames Available in OS X v10.5 through OS X v10.5

    Returns a dictionary mapping property keys to their corresponding four-character codes.

    Declaration

    Objective-C

    - (NSDictionary *)codesForPropertyNames

    Return Value

    A dictionary whose keys are the keys of properties of the external application, and whose values are the corresponding four-character codes (as NSNumber objects).

    Discussion

    The default implementation returns an empty dictionary. Application-specific subclasses return dictionaries tailored to the types of objects they support.

    You should never call this method directly.

    Import Statement

    Availability

    Available in OS X v10.5 through OS X v10.5.

  • Returns the error-handling delegate of the receiver.

    Declaration

    Swift

    var delegate: SBApplicationDelegate!

    Objective-C

    @property(strong) id<SBApplicationDelegate> delegate

    Return Value

    The object acting as error-handling delegate of the receiver.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

  • Returns the error-handling delegate of the receiver.

    Declaration

    Swift

    var delegate: SBApplicationDelegate!

    Objective-C

    @property(strong) id<SBApplicationDelegate> delegate

    Parameters

    delegate

    The object acting as delegate of the receiver.

    Discussion

    The delegate should implement the eventDidFail:withError: method of the SBApplicationDelegate informal protocol.

    Import Statement

    import ScriptingBridge

    Availability

    Available in OS X v10.5 and later.

    See Also

    – delegate