Applescript Studio Programming Guide
Total Page:16
File Type:pdf, Size:1020Kb
AppleScript Studio Programming Guide 2006-04-04 Microsystems, Inc. in the U.S. and other Apple Inc. countries. © 2001, 2006 Apple Computer, Inc. SPEC is a registered trademark of the All rights reserved. Standard Performance Evaluation Corporation (SPEC). No part of this publication may be reproduced, stored in a retrieval system, or Simultaneously published in the United transmitted, in any form or by any means, States and Canada. mechanical, electronic, photocopying, Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR recording, or otherwise, without prior REPRESENTATION, EITHER EXPRESS OR written permission of Apple Inc., with the IMPLIED, WITH RESPECT TO THIS following exceptions: Any person is hereby DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A authorized to store documentation on a PARTICULAR PURPOSE. AS A RESULT, THIS single computer for personal use only and DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE to print copies of documentation for ENTIRE RISK AS TO ITS QUALITY AND personal use provided that the ACCURACY. documentation contains Apple’s copyright IN NO EVENT WILL APPLE BE LIABLE FOR notice. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES The Apple logo is a trademark of Apple Inc. RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if Use of the “keyboard” Apple logo advised of the possibility of such damages. (Option-Shift-K) for commercial purposes THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN without the prior written consent of Apple LIEU OF ALL OTHERS, ORAL OR WRITTEN, may constitute trademark infringement and EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any unfair competition in violation of federal modification, extension, or addition to this and state laws. warranty. No licenses, express or implied, are granted Some states do not allow the exclusion or limitation of implied warranties or liability for with respect to any of the technology incidental or consequential damages, so the described in this document. Apple retains above limitation or exclusion may not apply to you. This warranty gives you specific legal all intellectual property rights associated rights, and you may also have other rights which with the technology described in this vary from state to state. document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, AppleScript Studio, Aqua, Carbon, Cocoa, Mac, Mac OS, Macintosh, QuickTime, and Xcode are trademarks of Apple Inc., registered in the United States and other countries. Finder is a trademark of Apple Inc. Objective-C is a registered trademark of NeXT Software, Inc. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Contents Introduction Introduction to AppleScript Studio Programming Guide 13 Who Should Read This Document 14 Organization of This Document 14 Conventions 15 See Also 15 Chapter 1 About AppleScript Studio 17 What Is AppleScript Studio? 17 What Makes AppleScript Studio Special? 17 AppleScript 18 Integrated Development Environment 18 Application Framework 19 Strengths and Limitations 20 How AppleScript Studio Works 21 AppleScript Studio’s Components 21 AppleScript Studio Applications 22 Connecting Actions to Scripts 22 Putting It All Together 25 Creating a Hello World Application 27 AppleScript Studio Sample Applications 35 Chapter 2 AppleScript Studio Components 39 AppleScript Overview 39 How AppleScript Is Implemented 40 Scripting in AppleScript Studio 41 Terms for Classes and Objects 41 Xcode Features for AppleScript Studio 42 AppleScript Studio Application Templates 43 AppleScript Studio Xcode Plug-in Template 43 Default Project Contents 44 The Targets Group 48 Source Code Editor 49 Debugging Features 51 Terminology Browser 51 Interface Builder Features for AppleScript Studio 53 3 2006-04-04 | © 2001, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Interface Creation 54 Interface Connections 56 Cocoa Framework Overview 58 Cocoa Scripting Support 58 Cocoa User Interface Objects 59 Cocoa Application Framework 59 AppleScriptKit Framework Overview 60 Chapter 3 Programming With AppleScript Studio 61 Additional Information on AppleScript Studio 61 Organizing an AppleScript Studio Project 62 Naming Conventions for Methods and Handlers 64 Accessing Code From AppleScript Studio Scripts 64 Persistent Script Properties 67 Accessing Script Globals 68 Overridden Scripting Additions 68 How Xcode Formats Scripts 69 Switching Between AppleScript Studio and Script Editor 70 Scripting AppleScript Studio Applications 71 Using Script Editor to Test AppleScript Studio Terminology 72 AppleScript Studio Terminology 73 Overview 73 General Sources of Scripting Terminology 74 Terminology From the AppleScriptKit Framework 75 Finding Terminology Information 77 Programming Tips 80 Targeting an AppleScript Studio Application 80 Using Make, Not Create, to Create New Objects in Scripts 80 Using the Log Command to Track Your Scripts 80 Basic Tips and Reminders 81 Troubleshooting 82 My Script Statements Aren’t Working 82 Several Windows in My Application Have ID 0 83 I Can’t Script My UI to Do QA Testing 83 Chapter 4 AppleScript Studio Cookbook 85 Performing User Interface Actions 85 Specifying Minimum Requirements for an Application 86 Adding AppleScript Studio Support to Your Cocoa Application 86 Setting the Keyboard Focus 87 Obtaining the Path to the Current Application 87 4 2006-04-04 | © 2001, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 5 Currency Converter Tutorial 89 Design the Application 90 Create a Project 90 Build the Interface 91 Launch Interface Builder 92 Adjust the Title, Size, and Other Attributes of the Currency Converter Window 92 Add Text Input Fields and Labels 98 Add a Result Field and Label 105 Add Number Formatters to the Input and Result Fields 107 Add a Convert Button 110 Add a Horizontal Separator 111 Finalize the Layout 112 Connect the Interface 112 Write Event Handlers 115 Build and Run the Application 117 Where To Go From Here 117 Chapter 6 Mail Search Tutorial: Design the Application 119 Before You Start This Tutorial 120 Identify a Goal for the Application 120 Examine Mail’s Scripting Dictionary 120 Specify Operations for Mail Search 122 Design the Interface 123 Identify Objects for the User Interface 123 Arrange the User Interface 125 Plan the Code 127 Event Handlers in Mail Search 128 Additional Handlers and Scripts in Mail Search 129 Chapter 7 Mail Search Tutorial: Create the Interface 133 Create a Project 133 Add an Image File to the Project 135 Build the Interface 136 Examine the Default Menus 136 Create the Message Window 137 Create a Status Dialog 145 Create the Search Window 152 Chapter 8 Mail Search Tutorial: Connect the Interface 169 Connect the Interface 169 Connect the Application Object 169 Connect Interface Items in the Search Window 172 5 2006-04-04 | © 2001, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 9 Mail Search Tutorial: Write the Code 187 Obtaining the Code for the Mail Search Tutorial 187 Define Global Variables and Properties 188 Write Event Handlers for the Interface 188 Application Object Handler 189 Search Window Handlers 189 Text Field Handler 191 Find Button Handler 191 Search Results Table View Handler 192 Write Scripts and Additional Handlers 192 Write the Controller Script 192 Write Handlers for Working With Controllers 203 Write Handlers for Working With the Status Dialog 204 Write Handlers for Working With Message Windows 204 Write Utility Handlers 204 Chapter 10 Mail Search Tutorial: Build and Test the Application 207 Build and Run Mail Search 207 Check for Syntax Errors 208 Chapter 11 Mail Search Tutorial: Customize the Application 211 Customize Menus 211 Rename Menus and Menu Items 211 Set Menu Attributes 213 Remove Menus and Menu Items 214 Customize the About Window 214 Customize Version and Copyright Information 216 Customize Icons 217 Add an Icon Resource File to the Project 219 Supply a Creator Code 222 Appendix A AppleScript Studio System Requirements and Version Information 223 Appendix B Mail Search Tutorial, Full Script Listing 225 Mail Search Copyright Notice 235 Glossary 237 Document Revision History 241 6 2006-04-04 | © 2001, 2006 Apple Computer, Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 About AppleScript Studio 17 Figure 1-1 The Drawer sample application 18 Figure 1-2 The components of AppleScript Studio 21 Figure 1-3 Connections between user interface items and scripts in an AppleScript Studio application 23 Figure 1-4 Interface Builder’s Palette window, showing the Cocoa-Controls palette 24 Figure 1-5 A window containing a button 24 Figure 1-6 The Info window for a button 25 Figure 1-7 Creating an application with AppleScript Studio 26 Figure 1-8 Choosing an AppleScript Studio application in Xcode 27 Figure 1-9 A newly-created AppleScript Studio application project 28 Figure 1-10 A project with many groups and files expanded 29 Figure 1-11 A default application window in Interface Builder 30 Figure 1-12 Interface Builder’s Palette window, showing the Cocoa-Controls palette 30 Figure 1-13 A window containing a button 31 Figure 1-14 The Hello World button 31 Figure