objc-appscript manual | 7. Application Objects

7. Application Objects

Creating application objects

Before you can communicate with a scriptable application you must create an application object by calling one of the following methods on the glue's Application class:

-initWithName:(NSString *)name; // name of local application
 // including .app suffix, if any
-initWithBundleID:(NSString *)bundleID; // bundle ID of local application
-initWithURL:(NSURL *)url; // file URL for a local application, or
 // eppc URL for a remote process
-initWithPID:(pid_t)pid; // Unix process id for a local process
-initWithDescriptor:(NSAppleEventDescriptor *)desc; // AEAddressDesc
-init; // the host process

Examples:

#import "ICalGlue.h"
ICalApplication *ical = [[ICalApplication alloc] initWithName: @"iCal.app"];
#import "TEGlue.h"
TEApplication *textedit = [[TEApplication alloc]
 initWithBundleID: @"com.apple.textedit"];
#import "ITunesGlue.h"
NSURL *url = [NSURL URLWithString: @"eppc://Jan%20Smith@G4.local/iTunes"];
ITunesApplication *itunes = [[ITunesApplication alloc] initWithURL: url];

Note that local applications will be launched if not already running when -initWithName:, -initWithBundleID or -initWithURL is invoked, and events will be sent to the running application according to its process ID. If the process is later terminated, that process ID is no longer valid and events sent subsequently using this application object will fail as application objects currently don't provide a 'reconnect' facility.

If -initWithURL: is invoked with an eppc:// URL, or if -initWithPID: or -initWithDescriptor: are used, the caller is responsible for ensuring the target application is running before sending any events to it.

Basic commands

All applications should respond to the following commands:

-run; -- Run an application.
 Most applications will open an empty, untitled window.
-activate; -- Bring the application to the front.
-reopen; -- Reactivate a running application.
 Some applications will open a new untitled window if no window is open.
-open: directarg; -- Open the specified object(s).
 directarg = anything -- list of objects to open, typically an NSArray
 of AEMAlias
-print: directarg; -- Print the specified object(s).
 directarg = anything -- list of objects to print, typically an NSArray
 of AEMAlias
-quit; -- Quit an application.
 -saving: yes | ask | no -- optional parameter takes an ASConstant specifying
 if currently open documents should be saved

Some applications may provide their own definitions of some or all of these commands, so check their terminology before use.

Appscript also defines get and set commands for any scriptable application that doesn't supply its own definitions:

-get: reference; -- Get the data for an object.
 reference -- the object for the command
 Result = anything -- the reply for the command
-set: reference; -- Set an object's data.
 reference -- the object for the command
 -to: value;
 value = anything -- The new value.

Note that these commands are only useful in applications that define an Apple Event Object Model as part of their Apple event interface.

Transaction support

Application objects implement four additional methods, -startTransactionWithSession:, -startTransaction, -endTransaction and -abortTransaction that allow a sequence of related commands to be handled as a single operation by applications that support transactions, e.g. FileMaker Pro.

Once the application object's -startTransaction or -startTransactionWithSession: method is called, all subsequent commands to that application will be sent as part of the same transaction until -endTransaction or -abortTransaction is called.

The -startTransactionWithSession: method takes an argument that indicates the specific transaction session to open (in applications that support this).

Remember to call -endTransaction or -abortTransaction at the end of every transaction. (This includes transactions interrupted by a raised exception.) If a transaction is accidentally left open, appscript will try to end it automatically when the application object is disposed of, but this is not guaranteed to succeed.

Local application launching notes

Note: the following information only applies to local applications as appscript cannot directly launch applications on a remote Mac. To control a remote application, the application must be running beforehand or else launched indirectly (e.g. by using the remote Mac's Finder to open it).

How applications are identified

When you create an Application object by application name, bundle id or creator type, appscript uses LaunchServices to locate an application matching that description. If you have more than one copy of the same application installed, you can identify the one you want by providing its full path, otherwise LaunchServices will identify the newest copy for you.

Appscript identifies locally run applications by their process ids so it's possible to control multiple versions of an application running at the same time if their Application objects are created using process ids or eppc:// URLs.

Checking if an application is running

You can check if the application specified by an Application object is currently running by calling its -isRunning method:

- (BOOL)isRunning;

This is useful if you don't want to perform commands on an application that isn't already running. For example:

TEApplication *textedit = [[TEApplication alloc] initWithName: @"TextEdit'];
// Only perform TextEdit-related commands if it's already running:
if ([textedit isRunning]) {
 // all TextEdit-related commands go here...
}
[te release];

Remember that objc-appscript automatically launches a non-running application the first time your script makes reference to any of its commands. To avoid accidental launches, all commands relating to that application must be included in a conditional block that only executes if -isRunning returns YES.

Launching applications via `-launchApplicationWithError:`

When appscript launches a non-running application, it normally sends it a run command as part of the launching process. If you wish to avoid this, you should start the application by sending it a launch command before doing anything else:

- (BOOL)launchApplicationWithError:(NSError **)error;
- (BOOL)launchApplication; // convenience shortcut for above

The result is a Boolean value indicating if the application was successfully launched (or was already running).

This is useful when you want to start an application without it going through its normal startup procedure, and is equivalent to the using AppleScript's launch command. For example:

TEApplication *textedit = [[TEApplication alloc] initWithName: @"TextEdit'];
[textedit launch];
// other TextEdit-related code goes here...

tell application "TextEdit"
 launch
 -- other TextEdit-related code goes here...
end tell

Both of the above examples will launch TextEdit without causing it to display a new, empty document (its usual behaviour).

The lower level AEMApplication class also provides several class methods that allow finer-grained control over application launches.

objc-appscript