Mac Developer Library

Developer

Scripting Bridge 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.

Although SBApplication includes methods that manually send and process Apple events, you should never have to call these methods directly. Instead, subclasses of SBApplication implement application-specific methods that handle the sending of Apple events automatically.

For example, if you wanted to get the current iTunes track, you can simply use the currentTrack method of the dynamically defined subclass for the iTunes application—which handles the details of sending the Apple event for you—rather than figuring out the more complicated, low-level alternative:

[iTunes propertyWithCode:'pTrk'];

If you do need to send Apple events manually, consider using the NSAppleEventDescriptor class.

Subclassing Notes

You rarely instantiate SBApplication objects directly. Instead, you get the shared instance of a application-specific subclass typically by calling one of the applicationWith... class methods, using a bundle identifier, process identifier, or URL to identify the application.

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

    Declaration

    Objective-C

    + (__kindof SBApplication *)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.

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    + (__kindof SBApplication *)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.

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    + (__kindof SBApplication *)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.

    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

    - (__kindof SBApplication *)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.

    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

    - (__kindof SBApplication *)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.

    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

    - (__kindof SBApplication *)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.

    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.

    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.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean that indicates whether the target application represented by the receiver is running (read-only)

    Declaration

    Swift

    var running: Bool { get }

    Objective-C

    @property(readonly, getter=isRunning) BOOL running

    Discussion

    YEStrue if the application is running, NOfalse otherwise.

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    var launchFlags: LSLaunchFlags

    Objective-C

    @property LSLaunchFlags launchFlags

    Discussion

    For more information, see Launch Services Reference.

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var sendMode: AESendMode

    Objective-C

    @property AESendMode sendMode

    Discussion

    For more information, see Apple Event Manager Reference.

    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.

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var timeout: Int

    Objective-C

    @property long timeout

    Discussion

    For more information, see Apple Event Manager Reference.

    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.

    Availability

    Available in OS X v10.5 and later.

  • - 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.

    Availability

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

  • - 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.

    Availability

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