Integrating AppleScript and Cocoa
Pages: 1, 2, 3, 4

AppleScript Terminology

So far we have seen a listing of classes and commands that are scriptable in the NSCoreSuite.scriptSuite file. Now we need to look at the AppleScript terminology that is used by scripters. The connection is made by another file, called NSCoreSuite.scriptTerminology. This file is a localized resource found at

/System/Library/Frameworks/Foundation.framework/Resources/English.lproj/NSCoreSuite.scriptTerminology

This file is also a XML property list, so you can open it in the Property List Editor. Localization is intended so that different terms for different dialects can be used with the same classes defined in NSCoreSuite.scriptSuite, although it was pointed out to me by an employee at Apple that the only supported dialect right now is English. This file has the same Classes and Commands sections, but they are used to provide the terms used within the script and the description of the term found in the application's scripting dictionary.

If you look at the Create command in the Property List Editor, you'll see that the name used in a script to call this command is "make." Furthermore, if you look in the Arguments section of the Create command, you'll see the keys "ObjectClass," whose name is "new", the key "Location," whose name is "at", the key "KeyDictionary," whose name is "with properties", and the key "ObjectData," whose name is "with data".

So, in AppleScript, when you say "make new document at the beginning of every document with properties {name: "hello"}", these terms correspond to the items in NSCoreSuite.scriptTerminology.

Inheritance in Action

Related Reading Learning Cocoa By Apple Computer, Inc.

Our goal now is to create a Cocoa application that supports a little more of the Core Suite. First step: open the Project Builder application and create a new Cocoa Document-based Application. Name it "ScriptableDocApp" and build the project by choosing "Build" from the Build menu or clicking on the hammer icon in the upper left of the project window. Next, like in the last article, we want to enable Core Suite support by adding

<key>NSAppleScriptEnabled</key> 
<string>YES</string>

to the Info.plist found in the Contents folder of the ScriptableDocApp.app folder in the Products folder of our project window. Save our files and choose Build and Run from the Build menu.

You'll notice that we can create new documents in our application by choosing New from the File menu. Let us try and script this behavior. Open Script Editor and in a new script, place the following:

tell application "ScriptableDocApp" 
	activate 
	set w to make new document at the beginning of documents 
	--close every document 
	
end tell

If you run this and look at the results window, you'll see that we are getting back new documents, but no new windows are appearing with the ScriptableDocApp.

Looking at our project in Project Builder, you'll notice two files in the Classes folder - MyDocument.h and MyDocument.m. These files create a class, MyDocument, that is a subclass of NSDocument. The MyDocument class is instantiated each time New is selected from the File menu, and this is how a new document is created. In order to get this same behavior from the scripting support, we need to tell the scripting system about MyDocument. In order to do this, we will need to add a scriptSuite file and a scriptTerminology file to our project.

Select the Resources folder in the "Groups & Files" pane of the project window and then select "New File" from the File menu. On the dialog window that comes up, select "Empty File," and then name it "ScriptableDocApp.scriptSuite," without the quotes, and click Finish to create this new file.

Paste in the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
	<key>AppleEventCode</key>
	<string>ScDA</string>
	<key>Classes</key>
	<dict>
		<key>MyDocument</key>
		<dict>
			<key>AppleEventCode</key>
			<string>docu</string>
			<key>Superclass</key>
			<string>NSCoreSuite.NSDocument</string>
			<key>ToOneRelationships</key>
			<dict>
			</dict>
		</dict>
		<key>NSApplication</key>
		<dict>
			<key>AppleEventCode</key>
			<string>capp</string>
			<key>Superclass</key>
			<string>NSCoreSuite.NSApplication</string>
			<key>ToManyRelationships</key>
			<dict>
				<key>orderedDocuments</key>
				<dict>
					<key>AppleEventCode<</key>
					<string>docu</string>
					<key>Type</key>
					<string>MyDocument</string>
				</dict>
			</dict>
		</dict>
	</dict>
	<key>Name</key>
	<string>ScriptableDocApp</string>
</dict>>
</plist>

This is our script suite for our application; the most important aspects of it are that it establishes the AppleEventCode of our app to be ScDA and then lists MyDocument under the Classes section with the Superclass key set to NSCoreSuite.NSDocument. We also establish in this file that the NSApplication class has a ToManyRelationships of orderedDocuments that are of the type MyDocument.

Now we need to add a script terminology file to our project. Once again, make sure the Resources folder is selected, and choose New File from the File menu. Again, choose "Empty File," name it "ScriptableDocApp.scriptTerminology" and click Finish. In this file, paste the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>
	<key>Classes</key>
	<dict>
		<key>MyDocument</key>
		<dict>
			<key>Description</key>
			<string>A ScriptableDocApp document.</string>
			<key>Name</key>
			<string>document</string>
			<key>PluralName</key>
			<string>documents</string>
		</dict>
		<key>NSApplication</key>
		<dict>
			<key>Description</key>
			<string>ScriptableDocApp's top level scripting object.</string>
			<key>Name</key>
			<string>application</string>
			<key>PluralName</key>
			<string>applications</string>
		</dict>
	</dict>
	<key>Description</key>
	<string>ScriptableDocApp specific classes.</string>
	<key>Name</key>
	<string>ScriptableDocApp suite</string>
</dict>
</plist>

This establishes the terminology for working with MyDocument; it simply says that the MyDocument class is referred to by the term document. Close the ScriptableDocApp.scriptTerminology file and make sure you save your changes.

Pages: 1, 2, 3, 4

Next Page