Carbon Overview 2005-11-09 Intel and Intel Core are registered Apple Computer, Inc. trademarks of Intel Corportation or its © 2005 Apple Computer, Inc. subsidiaries in the United States and other All rights reserved. countries. Java and all Java-based trademarks are No part of this publication may be trademarks or registered trademarks of Sun reproduced, stored in a retrieval system, or Microsystems, Inc. in the U.S. and other transmitted, in any form or by any means, countries. mechanical, electronic, photocopying, recording, or otherwise, without prior OpenGL is a registered trademark of Silicon written permission of Apple Computer, Inc., Graphics, Inc. with the following exceptions: Any person PowerPC and and the PowerPC logo are is hereby authorized to store documentation trademarks of International Business on a single computer for personal use only Machines Corporation, used under license and to print copies of documentation for therefrom. personal use provided that the Simultaneously published in the United documentation contains Apple’s copyright States and Canada. notice. Even though Apple has reviewed this document, The Apple logo is a trademark of Apple APPLE MAKES NO WARRANTY OR Computer, Inc. REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS Use of the “keyboard” Apple logo DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A (Option-Shift-K) for commercial purposes PARTICULAR PURPOSE. AS A RESULT, THIS without the prior written consent of Apple DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE may constitute trademark infringement and ENTIRE RISK AS TO ITS QUALITY AND unfair competition in violation of federal ACCURACY. and state laws. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, No licenses, express or implied, are granted OR CONSEQUENTIAL DAMAGES with respect to any of the technology RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if described in this document. Apple retains advised of the possibility of such damages. all intellectual property rights associated THE WARRANTY AND REMEDIES SET with the technology described in this FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, document. This document is intended to EXPRESS OR IMPLIED. No Apple dealer, agent, assist application developers to develop or employee is authorized to make any applications only for Apple-labeled or modification, extension, or addition to this warranty. Apple-licensed computers. Some states do not allow the exclusion or Every effort has been made to ensure that limitation of implied warranties or liability for incidental or consequential damages, so the the information in this document is above limitation or exclusion may not apply to accurate. Apple is not responsible for you. This warranty gives you specific legal rights, and you may also have other rights which typographical errors. vary from state to state. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, Aqua, Carbon, Cocoa, ColorSync, FontSync, iPod, Keychain, Logic, Mac, Mac OS, Macintosh, PowerBook, Quartz, QuickDraw, QuickTime, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. eMac, Finder, and Spotlight are trademarks of Apple Computer, Inc. Objective-C is a registered trademark of NeXT Software, Inc. Contents Introduction Introduction to Carbon Overview 5 Who Should Read This Document? 5 Organization of This Document 5 See Also 6 Chapter 1 Carbon Basics 7 What's in Carbon? 7 Carbon and Mac OS X 7 Building Carbon Applications 8 Chapter 2 The Carbon Factory Tour 9 The Starter Kit 9 The Toolbox Interfaces 9 The User Interface 10 Accessibility 10 Under the Hood 11 The Expansion Pack 11 Specialty and NonCarbon Interfaces 13 QuickTime 13 Core Video 13 Core Audio 14 Color, Images, and Print Production 14 3D Graphics 14 HTML 14 Disc Recording and Playback 14 Sync Services 15 Speech 15 Text and International Services 15 Internet and Networking 16 Security 17 Low-Level Tweaking 17 Utility Interfaces 17 3 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 3 Legacy Interfaces 19 Document Revision History 23 4 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction to Carbon Overview Originally designed to provide a gentle migration path for developers transitioning from Mac OS 9, Carbon is a collection of C programming interfaces that let you implement basic application functionality such as the user interface, event handling, file management, and so on. Note: A programming interface is the set of functions and data structures defined by one piece of software, such as an operating system service, for use by client software, such as applications and device drivers. For example, you would access one programming interface to enable your application to print and another to manipulate your application's menus This document describes Carbon's place in Mac OS X and gives overviews of the Carbon interfaces. It also describes a wide variety of other programming interfaces that Carbon applications can use, supporting everything from video playback to alternate text input. As Carbon is a C interface, you can also use all the standard C library APis; however, Mac OS X often has superior replacements (for example, Unicode string manipulation APIs versus the ASCII-related APIs, such as strcmp in the standard C library). Who Should Read This Document? You should read this document if you are new to Mac OS X and would like to write Mac OS X applications using procedural C or C++. Organization of This Document This document contains two chapters: ■ "Carbon Basics" (page 7) briefly describes how Carbon fits into Mac OS X and the tools available to build Carbon applications. ■ "The Carbon Factory Tour" (page 9) gives an overview of Carbon managers and services, including nonCarbon specialty services. ■ "Legacy Interfaces" (page 19) describes managers and services that have been superseded by newer technologies. If you are a new developer, this chapter is of historical interest only. Who Should Read This Document? 5 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction to Carbon Overview See Also When you are ready to explore Carbon programming, see Getting Started with Carbon to determine which documents to start reading. 6 See Also 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Carbon Basics This chapter describes the basics of Carbon, how it fits into Mac OS X, and the tools you use to build Carbon applications. What's in Carbon? Carbon contains thousands of functions, data structures, and constants. Related functions and data structures are organized into functional groups, usually referred to as managers or services. For example, the Window Manager contains functions and data structures that let you create, remove, and otherwise manipulate application windows. As a general rule, Carbon interfaces are those that are part of the Carbon umbrella framework; that is, those that are included when you include the Carbon.h header. This document also describes a number of managers or services that you can call from a Carbon application (for example, Quartz and QuickTime). Some of these technologies use Objective-C, which may require you to write some wrapper code. Carbon and Mac OS X As shown in the following figure, Carbon is one of several application environments available on Mac OS X. Carbon Cocoa Java (JDK) BSD QuickTime Application Services Core Services Kernel environment These other environments include: ■ Cocoa. The object-oriented interface for writing Mac OS X applications in Objective-C. What's in Carbon? 7 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Carbon Basics ■ Java. A JDK-compliant virtual machine for running Java applications. These environments depend on the same application and core services for their operation, and the underlying services rely on Darwin (Apple's open-source core operating system) and the Mach kernel. Each environment (including the optional BSD command-line environment) has advantages and disadvantages, but for C and C++ programmers, Carbon is the best choice. Building Carbon Applications Xcode and Interface Builder are Apple's development tools for building Mach-O-based applications on Mac OS X. Both tools support Carbon, and they come free with Mac OS X, making them excellent choices for new developers targeting Mac OS X. Also Xcode is currently the only development environment that allows compiling for both PowerPC and Intel-based Macintosh computers. Note: Mach-O is the native executable format on Mac OS X. While Carbon supports the PEF or CFM-based executable formats, you should not use this format unless you need to be compatible with pre-Mac OS X systems (not likely). Xcode and Interface Builder work in conjunction with each other to make building applications easier than ever: ■ Xcode. The main development environment; it lets you create and assemble the components of your application. When you create a new Carbon application, Xcode uses a Carbon Event-based template that automatically provides basic event-handling support. Xcode also makes it easy to build universal binaries, which support both PowerPC and Intel-based Macintosh hardware. ■ Interface Builder. A WYSIWYG tool that lets you lay out user interfaces in a simple, intuitive manner. These interface templates are stored as a .nib file, which your application can then access to create its windows, menus, and other elements. Xcode uses open-source developer tools (such as the GCC compiler) under the hood. If you are comfortable doing so, you can run these tools yourself from the command line using the Terminal application, writing Make files and so on. 8 Building Carbon Applications 2005-11-09 | © 2005 Apple Computer, Inc. All Rights Reserved. CHAPTER 2 The Carbon Factory Tour Carbon contains many programming interfaces. What interfaces you will require depends on the type of applications you want to write, but as is often the case, some are more commonly used than others.