SBApplication Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/ScriptingBridge.framework
Availability
Available in OS X v10.5 and later
Declared in
SBApplication.h
Related sample code

Overview

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.

Tasks

Getting a Scriptable Application Instance

Initializing a Scriptable Application Object

Creating a Scripting Class

Controlling the Application

Getting Class Names and Codes

Managing the Delegate

Class Methods

applicationWithBundleIdentifier:

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

+ (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.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
SBApplication.h

applicationWithProcessIdentifier:

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

+ (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.

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

applicationWithURL:

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

+ (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.

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

Instance Methods

activate

Moves the target application to the foreground immediately.

- (void)activate
Discussion

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

classForScriptingClass:

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

- (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.
Declared In
SBApplication.h

delegate

Returns the error-handling delegate of the receiver.

- (id)delegate
Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

initWithBundleIdentifier:

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

initWithProcessIdentifier:

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

initWithURL:

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

isRunning

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

- (BOOL)isRunning
Return Value

YES if the application is running, NO otherwise.

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

launchFlags

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

sendMode

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

setDelegate:

Returns the error-handling delegate of the receiver.

- (void)setDelegate:(id)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.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
SBApplication.h

setLaunchFlags:

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

- (void)setLaunchFlags:(LSLaunchFlags)flags
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).

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h

setSendMode:

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

- (void)setSendMode:(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.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
SBApplication.h

setTimeout:

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

- (void)setTimeout:(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.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
SBApplication.h

timeout

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

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

Availability
  • Available in OS X v10.5 and later.
Declared In
SBApplication.h