Introduction to Cocoa Scripting Guide

This document describes how to create scriptable applications using the support provided by the Cocoa application framework. That support, which is referred to as Cocoa scripting, includes classes, categories, and scriptability information.

A scriptable application is one that can be controlled by AppleScript scripts. Users write scripts to automate tasks and combine the use of multiple applications. As a developer, you can also use scripts to speed up prototyping or testing of your scriptable applications.

When a script that targets an application is executed, commands are sent to the application in the form of Apple events, a kind of interprocess message. Cocoa scripting helps you create scriptable applications by doing much of the work of receiving these Apple events, extracting information from them, and invoking methods in your scriptable classes.

This document provides conceptual information and examples that are based primarily on the scripting support available in OS X versions 10.4 and 10.3.

Although some information may be accurate for versions of the Mac OS prior to v10.3, this document has not been reviewed for accuracy on those versions, nor does it attempt to provide details for working with those versions.

Who Should Read This Document

This document is intended for developers who want to make their Cocoa applications scriptable or who need to know more about how Cocoa applications interact with AppleScript and Apple events. It assumes you have some familiarity with Cocoa, Objective-C, and AppleScript. However, if you are unfamiliar with AppleScript, you should start by reading Getting Started with AppleScript and AppleScript Overview. Many of the terms scripters use are defined in AppleScript Language Guide.

Organization of This Document

The following chapters describe how to design, implement, and debug a scriptable Cocoa application:

• Overview of Cocoa Support for Scriptable Applications provides a brief overview of AppleScript and scriptable applications, and describes the scripting support provided by the Cocoa application framework. This chapter is a prerequisite for the chapters that follow.

• Designing for Scriptability provides high-level checklists for designing a new scriptable Cocoa application and making an existing application scriptable.

• Implementing a Scriptable Application lists the key steps for implementing a scriptable Cocoa application, with links to more detailed information where necessary.

• Preparing a Scripting Definition File describes the structure of scripting definition, or sdef, files. It also shows how to create an sdef for a scriptable Cocoa application and how to add scriptability information to it.

• Getting and Setting Properties and Elements describes how to work with Cocoa scripting to get and set the values of properties and elements in your scriptable application. It also provides examples of basic, KVC-compliant accessor methods.

• Object Specifiers explains the mechanism for locating a scriptable object in the context of its container and provides sample object specifier methods.

• Script Commands provides additional detail about the script command mechanism Cocoa uses to respond to Apple events and describes how to implement script commands.

• Testing, Debugging, and Performance provides tips for building up your test plan debugging the scriptability in your Cocoa application, and spotting possible performance issues.

The following chapters provide additional information about Cocoa scripting support:

• How Cocoa Applications Handle Apple Events describes the default support for handling Apple events in Cocoa applications and how your application interacts with it.

• Cocoa Scripting Classes and Categories provides brief descriptions of the main classes that make up Cocoa scripting support, including those that you use in creating scriptable applications.

• Evolution of Cocoa Scriptability Information describes changes to Cocoa scriptability information over time. It includes information about when to use various types of scriptability information and how to convert between them.

The following chapter describes how to specify scriptability information using an earlier format:

• Script Suite and Script Terminology Files describes another way to provide terminology information and describes the structure of script suite and script terminology files.