Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
AppleScript Studio Cookbook
This chapter provides step-by-step instructions for performing common AppleScript Studio tasks, in the following sections:
Performing User Interface Actions
AppleScript Studio provides the ability to perform user interface actions directly in scripts, using the perform action
command (defined in the Control View suite). For example, you can tell an interface object, such as a button, to perform its clicked
handler, thus providing a way to directly script the user interface (subject to limitations described in Scripting AppleScript Studio Applications). Note, however, that calling the clicked
handler will not provide the visual feedback a user would see if they actually clicked the button.
Listing 4-1 shows a script that tells the “Drawer” button in the Drawer application to perform its clicked
handler, which will either open or close the drawer, depending on its current state.
Listing 4-1 Manipulating a button in the Drawer application from an external script
tell application "Drawer" |
set theButton to button "Drawer" of window "Main" |
tell theButton to perform action |
end tell |
The perform action
command does nothing unless the specified object has an action handler—a handler such as a clicked
or double-clicked
handler in the Action group in the Interface Builder Info window for the object. For example, see the Info window in Figure 1-15.
To use the perform action
command with menus, you can use syntax like the following:
tell menu item 1 of menu 1 of main menu to perform action |
You can also call application methods directly, as described in Scripting AppleScript Studio Applications.
Specifying Minimum Requirements for an Application
To run AppleScript Studio applications, the target machine must include the AppleScript Studio runtime required for the application. The runtime is available if AppleScriptKit.framework
is present in /System/Library/Frameworks
.
For example, an application built with AppleScript Studio 1.2 that uses features added in version 1.2 requires the 1.2 runtime. However, a similar application that doesn’t use any features from AppleScript Studio 1.2 can run with the 1.1 runtime. Note that all 1.1 applications can run with the 1.0 runtime distributed with Mac OS X version 10.1.2. For more information on versions and runtimes, see AppleScript Studio System Requirements and Version Information.
You can install a will finish launching
handler for your application to check the version. Connect the Application Object shows how to add a will finish launching
handler.
Listing 4-2 shows a simple example of how the will finish launching
handler might check for the application’s required version of AppleScript Studio. In this case, the application quits if the required version isn’t available. Note that the handler doesn’t check AppleScript Studio’s version number directly. Instead, it checks for the corresponding AppleScript version, as shown in Table A-1.
Listing 4-2 will finish launching handler that checks for required version of AppleScript Studio
on will finish launching theObject |
considering numeric strings |
if AppleScript's version as string is less than "1.10.1" then |
display dialog "This application requires AppleScript Studio 1.4 or later." |
quit |
end if |
end considering |
end will finish launching |
Adding AppleScript Studio Support to Your Cocoa Application
You can use the following steps to add AppleScript Studio support to your existing Cocoa application:
Add the AppleScriptKit framework to your project. You can do so by navigating to
/System/Library/Frameworks/AppleScriptKit.framework
and dragging the framework into the Frameworks group in the Xcode project for your application.In the dialog that appears, do not select the checkbox to copy items, but do check the radio button to recursively create groups. If you have more than one target, you’ll have to select any targets the framework should be added to.
Add an AppleScript Studio build phase to the application. To do this, first click the Targets tab, then double-click the desired Target. You should see a pane showing the Files & Build Phases tab.
Click the section labeled Bundle Resources. You should be able to select the whole section.
Choose Project > New Build Phase > New AppleScript Build Phase (from the Projects menu).
If you’ve already added any
.applescript
files to your application, they’ll be in the Bundle Resources phase, and you’ll have to drag them to the new AppleScript phase you just created.If your application is not already scriptable, make the following modification to its
Info.plist
file to make it scriptable:In the Application Settings pane (after clicking the Expert button), add a new string entry to the property list that sets NSAppleScriptEnabled to “YES”. You can add an entry by clicking the New Sibling button. You can double-click any of the entries in the sibling to edit it.
If your application has a
.scriptsuite
file, for every class in that file whose superclass belongs to the core suite (NSCoreSuite), change the suite to ASKApplicationSuite. For example, change"Superclass" = "NSCoreSuite.NSApplication"
to
"Superclass" = "ASKApplicationSuite.NSApplication"
Setting the Keyboard Focus
To make a user interface object, such as a text field, have the keyboard focus, set its window’s first responder
property. For example, the following Tell statement causes a text field to become active and be first in line to respond to keyboard events:
tell window "user information" |
set first responder to text field "user name" |
end tell |
Note that without the Tell statement, you would have to specify the window twice:
set first responder of window "user information" |
to text field "user name" of window "user information" |
In many cases, you will not have to set keyboard focus, because it is set automatically as a user tabs between fields, clicks on a text field, and so on.
Obtaining the Path to the Current Application
To obtain the path to the current (running) AppleScript Studio application, you use the standard scripting addition command path to
. For example:
set myPath to (path to me) |
display dialog (myPath as string) |
-- result, if inserted in on opened handler in Drawer sample application: |
-- MacOSX:Developer:Examples:AppleScript Studio:Drawer:build:Drawer.app |
The Standard Additions are automatically installed with Mac OS X.
Copyright © 2001, 2011 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2011-01-07