Integrating Carbon and Cocoa in Your Application Preliminary January 1, 2003 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2003, 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, Mac OS, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Objective-C is a trademark of NeXT Software, 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 Carbon and Cocoa Integration 7 Chapter 2 Carbon and Cocoa Integration Concepts 9 Carbon and Cocoa Communication 9 C-Callable Wrapper Functions 12 Compiler Preprocessors 13 Interchangeable Data Types 13 Chapter 3 Carbon and Cocoa Integration Tasks 15 Using Cocoa Functionality in a Carbon Application 15 About the Spelling Checker Application 16 Writing a Cocoa Bundle 16 Making Your Carbon Code Access the Cocoa Bundle 20 Summary 24 Using Carbon Functionality in a Cocoa Application 24 Working With QuickTime Movies 25 Accessing a Resource Fork From Cocoa 26 Obtaining an FSSpec Structure 26 Managing Core Foundation Objects in Cocoa 27 Summary 28 Using a Cocoa User Interface in a Carbon Application 28 About the CocoaInCarbon Application 29 Writing the Cocoa Bundle 31 Setting Up the Carbon Application to Use the Cocoa Interface 36 Summary 39 Using a Carbon User Interface in a Cocoa Application 39 About the CarbonInCocoa Application 40 Creating the Carbon User Interface 41 Setting Up the Cocoa Application to Use the Carbon User Interface 41 Summary 44 Document Revision History 45 3 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS 4 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. Tables, Figures, and Listings Chapter 2 Carbon and Cocoa Integration Concepts 9 Figure 2-1 The path of user events in Mac OS X 10 Figure 2-2 Events communicated between Carbon and Cocoa 11 Table 2-1 Filename extensions and compilation 13 Table 2-2 Data types that can be used interchangeably between Carbon and Cocoa 14 Chapter 3 Carbon and Cocoa Integration Tasks 15 Figure 3-1 The user interface for the Spelling Checker application 16 Figure 3-2 The Carbon user interface for the CocoaInCarbon application 30 Figure 3-3 The Cocoa window for the CocoaInCarbon application 30 Figure 3-4 Connecting a button to a button-pressed action 36 Figure 3-5 The Cocoa user interface for the CarbonInCocoa application 40 Figure 3-6 The Carbon user interface for the CarbonInCocoa application 40 Listing 3-1 A C-callable wrapper function for the uniqueSpellDocumentTag: method 19 Listing 3-2 A C-callable wrapper function for the checkSpellingOfString:startingAt: method 19 Listing 3-3 A C-callable wrapper function for the sharedApplication method 20 Listing 3-4 A utility function to load a bundle from the application's Frameworks folder 21 Listing 3-5 Defining data types for function pointers 22 Listing 3-6 Declaring function pointers 22 Listing 3-7 Calling a C-wrapper function from your Carbon application 23 Listing 3-8 Building an array of track media types for a QuickTime movie 25 Listing 3-9 Calling Resource Manager functions from a Cocoa application 26 Listing 3-10 A Cocoa method to obtain an FSSpec structure 27 Listing 3-11 The contents of the common header for the Cocoa bundle and the Carbon application 32 Listing 3-12 Implementing the controller in the Cocoa bundle 32 Listing 3-13 Declaring the interface for the controller 33 Listing 3-14 C-callable wrapper functions for the Cocoa bundle 34 Listing 3-15 Calling the initializeBundle C-wrapper function using a function pointer 37 Listing 3-16 Calling the C-wrapper function to open the Cocoa window 38 Listing 3-17 A Carbon function that handles a Cocoa button press 38 Listing 3-18 The declaration for the controller 42 Listing 3-19 Loading a nib file for a Carbon window 42 5 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. TABLES, FIGURES, AND LISTINGS Table 3-1 C-callable wrapper functions for Cocoa methods 18 6 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to Carbon and Cocoa Integration No matter which development environment you choose to develop applicationsÐCocoa or CarbonÐyou may find the other development environment offers functionality you'd like to use in your application. Choosing the Cocoa or Carbon development environment to create new applications doesn't restrict you to using the API defined for that environment. You can use the Carbon API from a Cocoa application or the Cocoa API from a Carbon application. This document shows you how. There are a number of reasons you might want to integrate Cocoa and Carbon in an application, including the following: ■ You want to leverage existing code while getting the benefits of technologies offered by another framework. ■ You are developing a common service that you want to make available to both Carbon and Cocoa. ■ It's easier for you to do some tasks in Cocoa than in Carbon, or vice versa. ■ You already created a terrific user interface in one environment and want to access it from the other environment. ■ Your programming team consists of engineers with different skill setsÐCocoa and Carbon. You'll find, by reading the following chapters, that intermixing Carbon and Cocoa in an application is a relatively straightforward process. ■ Chapter 2, ªCarbon and Cocoa Integration Conceptsº, discusses how Carbon and Cocoa communicate between each other and provides information on C-callable wrapper functions, compiler preprocessors, and interchangeable data types. ■ Chapter 3, ªCarbon and Cocoa Integration Tasksº, provides information on how you can call Cocoa functions from a Carbon application and Carbon functions from a Cocoa application, including how to share user interface elements between the two environments. This document assumes you are programming for Cocoa in Objective-C and does not discuss Java integration issues. To get the full benefit of this document, you should have experience programming in either the Cocoa or Carbon environment. In addition, it is desirable that you have some basic knowledge of the other environment. See the Mac OS X Programming Getting Started website for tutorials, examples, and a reading list of essential documents: http://developer.apple.com/macosx/gettingstarted/ 7 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Introduction to Carbon and Cocoa Integration Important: This is a preliminary document. Although it has been reviewed for technical accuracy, it is not final. Apple Computer, Inc. is supplying this information to help you plan for the adoption of the technology described herein. This information is subject to change, and software implemented according to this document should be tested with final operating-system software and final documentation. You can check http://developer.apple.com/documentation/ for information about updates to this and other developer documents. To receive notification of documentation updates, you can sign up for ADC©s free Online Program and receive their weekly Apple Developer Connection News email newsletter. (See http://developer.apple.com/membership/ for more details about the Online Program.) 8 Preliminary © 2003, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 2 Carbon and Cocoa Integration Concepts It has always been possible to integrate Cocoa and Carbon functionality in the same application, at least when it comes to functionality that doesn't handle user interface elements.