Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/ScriptingBridge.framework |
Availability | Available in Mac OS X v10.5 and later |
Declared in | SBApplication.h |
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.
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.
– activate
– isRunning
– launchFlags
– setLaunchFlags:
– sendMode
– setSendMode:
– timeout
– setTimeout:
– classNamesForCodes
Available in Mac OS X v10.5 through Mac OS X v10.5
– codesForPropertyNames
Available in Mac OS X v10.5 through Mac OS X v10.5
Returns the shared instance representing the target application specified by its bundle identifier.
+ (id)applicationWithBundleIdentifier:(NSString *)ident
A bundle identifier specifying an application that is OSA-compliant.
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.
For applications that declare themselves to have a dynamic scripting interface, this method will launch the application if it is not already running.
SBApplication.h
Returns the shared instance representing a target application specified by its process identifier.
+ (id)applicationWithProcessIdentifier:(pid_t)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
.
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.
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.
SBApplication.h
Returns the shared instance representing a target application specified by the given URL.
+ (id)applicationWithURL:(NSURL *)url
The Universal Resource Locator (URL) locating an OSA-compliant application.
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.
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.
SBApplication.h
Moves the target application to the foreground immediately.
- (void)activate
If the target application is not already running, this method launches it.
SBApplication.h
Returns a class object that represents a particular class in the target application.
- (Class)classForScriptingClass:(NSString *)className
The name of the scripting class.
A Class
object representing the scripting class.
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.
SBApplication.h
Returns the error-handling delegate of the receiver.
- (id)delegate
The object acting as error-handling delegate of the receiver.
SBApplication.h
Returns an instance of an SBApplication
subclass that represents the target application identified by the given bundle identifier.
- (id)initWithBundleIdentifier:(NSString *)ident
A bundle identifier specifying an application that is OSA-compliant.
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.
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.
SBApplication.h
Returns an instance of an SBApplication
subclass that represents the target application identified by the given process identifier.
- (id)initWithProcessIdentifier:(pid_t)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
.
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.
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.
SBApplication.h
Returns an instance of an SBApplication
subclass that represents the target application identified by the given URL.
- (id)initWithURL:(NSURL *)url
A Universal Resource Locator (URL) specifying an application that is OSA-compliant.
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.
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.
SBApplication.h
Returns whether the target application represented by the receiver is running.
- (BOOL)isRunning
YES
if the application is running, NO
otherwise.
SBApplication.h
Returns the launch flags for the application represented by the receiver.
- (LSLaunchFlags)launchFlags
A mask specifying the launch flags that are used when the target application is launched. For more information, see Launch Services Reference.
SBApplication.h
Returns the mode for sending Apple events to the target application.
- (AESendMode)sendMode
A mask specifying the mode for sending Apple events to the target application. For more information, see Apple Event Manager Reference.
SBApplication.h
Returns the error-handling delegate of the receiver.
- (void)setDelegate:(id)delegate
The object acting as delegate of the receiver.
The delegate should implement the eventDidFail:withError:
method of the SBApplicationDelegate
informal protocol.
SBApplication.h
Returns the launch flags for the application represented by the receiver.
- (void)setLaunchFlags:(LSLaunchFlags)flags
A mask specifying the launch flags that are used when the target application is launched. For more information, see Launch Services Reference.
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).
SBApplication.h
Sets the mode for sending Apple events to the target application.
- (void)setSendMode:(AESendMode)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.
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.
SBApplication.h
Sets the maximum time the application will wait to receive reply Apple events.
- (void)setTimeout:(long)timeout
The time in ticks that the receiver will wait to receive a reply Apple event from the target application before giving up.
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.
SBApplication.h
Returns the period the application will wait to receive reply Apple events.
- (long)timeout
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.
SBApplication.h
Last updated: 2007-05-29