Setting up Your Carbon Application to Use the Services Menu

Setting Up Your Carbon Application to Use the Services Menu December 10, 2003 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2002, 2004 Apple Computer, Inc. Even though Apple has reviewed this manual, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, No part of this publication may be ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, MANUAL IS SOLD ªAS IS,º AND YOU, THE mechanical, electronic, photocopying, PURCHASER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. recording, or otherwise, without prior IN NO EVENT WILL APPLE BE LIABLE FOR written permission of Apple Computer, Inc., DIRECT, INDIRECT, SPECIAL, INCIDENTAL, with the following exceptions: Any person OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR is hereby authorized to store documentation INACCURACY IN THIS MANUAL, even if on a single computer for personal use only advised of the possibility of such damages. and to print copies of documentation for THE WARRANTY AND REMEDIES SET personal use provided that the FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, documentation contains Apple’s copyright EXPRESS OR IMPLIED. No Apple dealer, agent, notice. or employee is authorized to make any modification, extension, or addition to this The Apple logo is a trademark of Apple warranty. Computer, Inc. Some states do not allow the exclusion or limitation of implied warranties or liability for Use of the “keyboard” Apple logo incidental or consequential damages, so the (Option-Shift-K) for commercial purposes above limitation or exclusion may not apply to you. This warranty gives you specific legal without the prior written consent of Apple rights, and you may also have other rights which may constitute trademark infringement and vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this 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 Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Aqua, Carbon, Cocoa, Mac, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder is a trademark of Apple Computer, Inc. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Contents Chapter 1 Introduction to Application Services 7 Who Should Read This Document? 7 Organization of This Document 7 See Also 8 Chapter 2 Application Services Concepts 9 Types of Application Services 9 Installation Paths for Services 11 Items in the Services Menu 12 Services Properties 12 What Happens When a Service Is Invoked 14 Chapter 3 Application Services Tasks 17 Using a Service 17 Declaring Services Events 17 Specifying the Data Types Used by Your Application 18 Handling Copy and Paste Events 20 Installing a Carbon Event Handler 24 Providing a Service 24 Adding the NSServices Property to the Information Property List 25 Making Sure There's a Bundle Identifier Property 26 Handling the Service Perform Event 26 Installing a Carbon Event Handler 33 Registering the Service 33 Appendix A Carbon Events for Services 35 Event Classes and Kinds 35 Event Parameters for Services Events 35 Document Revision History 37 3 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS 4 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. Tables, Figures, and Listings Chapter 2 Application Services Concepts 9 Figure 2-1 Make Sticky is a processor service 10 Figure 2-2 Open URL is a processor service 10 Figure 2-3 Grab is a provider service 11 Figure 2-4 The Wolf Facts document after a screenshot has been inserted 11 Figure 2-5 The NSServices property for the Grab application 14 Chapter 3 Application Services Tasks 17 Figure 3-1 Three services provided by SimplerText 28 Figure 3-2 Text provided by the service requestor 30 Figure 3-3 Giving text to the service requestor 31 Figure 3-4 Modified text returned to the service requestor 33 Listing 3-1 Declaring an EventTypeSpec structure for services events 18 Listing 3-2 Declaring an EventTypeSpec structure for a variety of Carbon events 18 Listing 3-3 Declaring the data types used in an application 19 Listing 3-4 Supplying the data types used by your application 19 Listing 3-5 Handling a copy event 21 Listing 3-6 Handling a paste event 22 Listing 3-7 Getting the Carbon event parameter for the event kind kEventServicePerform 26 Listing 3-8 Getting data from the service requestor 29 Listing 3-9 Giving data to the service requestor 30 Listing 3-10 Modifying data from the service requestor 31 Appendix A Carbon Events for Services 35 Table A-1 Event classes and kinds used by application services 35 Table A-2 Carbon event parameters for service events 36 5 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. TABLES, FIGURES, AND LISTINGS 6 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to Application Services Application services give applications an open-ended way to extend each other's functionality by allowing them to: ■ Provide services to other applications ■ Access functionality provided by other applications An application that provides a service advertises the operation it can perform on a particular type of dataÐfor example, encryption of text, optical character recognition of a bitmapped image, or generating text such as a message of the day. Any application that signs up to use services automatically accesses the advertised functionality through its Services menu. An application doesn't need to know in advance what operations are available; it merely needs to indicate the types of data it uses, and the Services menu makes available the operations that apply to those types of data. Who Should Read This Document? This document describes how application services work, shows some typical Services menus, and provides instructions on how you can use services in your application. You should read this document if you are an application developer and want to provide your application's services to other applications or make services from other applications available to your application. Before you read this document, you should be familiar with information property lists. You need to know what they are and how to add properties to a list. Carbon developers should also know how to write and install Carbon event handlers. Organization of This Document This document is organized as follows: ■ ªApplication Services Conceptsº (page 9), discusses the types of services, the Services menu, services properties, and what happens when a service is invoked. Who Should Read This Document? 7 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to Application Services ■ ªApplication Services Tasksº (page 17), provides instructions on how to set up your application to use services provided by other applications and how to provide your services to other applications. ■ ªCarbon Events for Servicesº (page 35), describes the Carbon event classes, kinds, and event parameters defined for services events. See Also ■ Aqua Human Interface Guidelines in User Experience Documentation provides guidelines on naming menu items and designing the interface for a services application. ■ Handling Carbon Events in Carbon Events & Other Input Documentation describes how to implement Carbon events in your application. ■ System Overview in Mac OS X Documentation contains information on property lists and how they are used in Mac OS X. ■ Learning Carbon, available through O'Reilly and Associates, contains information on writing and using Carbon event handlers as well as information on how to set up and use property lists. 8 See Also © 2002, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 2 Application Services Concepts This chapter provides an overview of the Services menu and describes how application services are provided and accessed. It also shows typical examples of the services available to, or provided by, applications in Mac OS X. Types of Application Services Mac OS X offers two types of services: ■ Processor. This type of service acts on data. A processor service acts on the current selection and then sends it to the service. For example, if a user selects an email address in a TextEdit document, and then chooses Mail > Mail To from the Services menu, Mail copies the person's address, launches the Mail application, and pastes the address into the To field of a new email message. ■ Provider. This type of service gives data to the calling application. For example, if a user chooses Grab > Screen from the Services menu, the Grab application opens, takes a screenshot, then returns the screenshot (TIFF data in this case) to the calling application. The calling application (such as TextEdit) is responsible for pasting the data into the active document. Let's take a look at a few examples. Figure 2-1 (page 10) shows the Services menu from the TextEdit application. Make Sticky is an example of a processor service. The Make Sticky command takes the current selection in the TextEdit document, opens a new Stickies document, and then pastes the selection into the Stickies document. Types of Application Services 9 © 2002, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 2 Application Services Concepts Figure 2-1 Make Sticky is a processor service Figure 2-2 (page 10) shows another example of a processor service.

Load more