Because Carbon contains many, many programming interfaces, it can be quite daunting to a new developer. While this book provides a good start, at some point you will need to begin fending for yourself. 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. This section divides up the Carbon interfaces according to usage (from fundamental to esoteric) and gives some useful information about each one. To learn more about a particular interface, you can use the Carbon Help feature integrated into Project Builder (to be described later in this book). You can also consult the technical documentation on the Apple developer web site.
This section covers the interfaces most likely to be called by a Macintosh application (and covers those that can be found in this book). These managers and services provide basic user interface functionality as well as fundamental features, such as the ability to save and print files. You can build basic but fully functional Carbon applications using the interfaces described here.
Note
If Carbon were an interface to build automobiles, the Starter Kit interfaces would define the engine, wheels, brakes and other essential components, as well as the user interface (dashboard, steering wheel, gas and brake pedals, and so on).
The following interfaces are grouped together because they generally work together to create and manage the user interfaces. In most cases, Interface Builder and the Interface Builder Services interface can handle the creation and control of the basic user interface. However, to accomplish more esoteric tasks, you may need to call additional functions in one of these so-called Human Interface Toolbox interfaces:
The Appearance Manager. Coordinates the look of the standard Mac OS human interface and allows for the adaptation of custom human interface elements to a coordinated appearance. The Appearance Manager provides the underlying support for themes, which unify the appearance of human interface objects in your application, including alert icons, controls, background colors, dialogs, menus, and windows.
The Control Manager. Lets you create and manipulate controls, which are user interface elements belonging to a window. Buttons, scroll bars, and sliders are examples of controls.
The Dialog Manager. Lets you create and manipulate dialogs, which are windows that either prompt you for input or display information. Although the Window Manager can give you much of the same functionality, the Dialog Manager is a simpler interface for managing these specific types of windows.
The Window Manager. Lets you create and manipulate windows, which are the user’s primary means of interacting with your software.
Interface Builder Services. Lets your code access the user interface elements created with Interface Builder and stored in a nib file. Obviously, if you aren’t using Interface Builder, you don’t need this interface.
Aqua is not an interface, but you need to follow the Aqua guidelines when designing and laying out your user interface. While the Carbon programming interfaces are flexible enough to let you do just about anything with your user interface, that doesn’t mean you should. Just as adherence to common rules and customs when designing steering wheels and dashboards makes driving more pleasant and less confusing, following the Aqua guidelines lets your application provide the best possible experience for your users.
The following interfaces work behind the scenes, as it were, to provide the basic functionality that you expect from most applications:
The Carbon Event Manager. Controls the event model for Macintosh applications. Note that Carbon also contains an older event-handling system (simply called the Event Manager), which is included only to assist legacy applications moving to Mac OS X.
The Carbon Printing Manager. Lets you print from Macintosh applications.
Navigation Services. Creates a standard user interface for opening and saving documents.
The File Manager. Lets you read and write data to storage media (hard drives, Zip drives, and so on).
Bundle Services. Lets you access data stored in a bundle file hierarchy, which is the standard method of packaging applications in Mac OS X.
The Resource Manager. Lets you access information in a bundle hierarchy stored as an old-style Mac OS resource (that is, in a data fork-based file with the
.rsrcextension). The Resource Manager complements Bundle Services in allowing access to images, text, and other resources stored in a bundle.String Services. Allows basic manipulation of Unicode strings.
The Multilingual Text Engine (MLTE). Provides basic text display and formatting features. Because it is Unicode-based, MLTE can easily handle other languages and script systems.
QuickDraw. Carbon’s interface for drawing 2D graphics to the screen.
The Memory Manager. Allows you to allocate and release temporary memory for your application.
This section lists interfaces that are desirable, but not necessary for most applications. Full-featured commercial applications usually adopt a number of these interfaces.
Note
Continuing the automobile metaphor, these interfaces would add useful features that may be essential in some cases, such as power-steering, windshield wipers, and air conditioning.
The Scrap Manager. Lets the user copy items to and from the Clipboard for cut-and-paste operations.
The Drag Manager. Used for implementing drag and drop between applications. For example, the user can select text in one application and then, rather than copying and pasting, simply drag the text into the window of another application.
The Font Manager. Lets you manipulate the fonts that your application uses to display or print text. For example, if you want your application to support a Font menu, you probably need the Font Manager.
Icon Services. Provides a simplified way to present icons in your application. Instead of storing every type of icon you need with your application, you can obtain commonly used icons through Icon Services. Doing so minimizes the amount of work you have to do and increases system efficiency.
The Folder Manager. Lets you find, create, and otherwise manipulate folders.
The Alias Manager. Lets you create and resolve aliases to files and folders. An alias is a small “copy” of an application, folder, or file that points to the original.
The Open Scripting Architecture. Describes the interfaces to control or automate the actions of one or more applications. You use the Apple Event Manager portion to interpret and react to events received from other applications, and AppleScript is the scripting language that you use to describe what actions to take. For example, if your application might be used in an automated workflow, where multiple applications manipulate a file in turn, you should make your application Apple Event savvy so it can act upon commands sent to it from an external script.
Note
The Apple Event Manager is different from the Carbon Event Manager. While there is some overlap in their capabilities, Carbon events are typically received from the user interface or operating system, while Apple events come from scripts or other applications.
Core Foundation. A collection of interfaces that can simplify common needs of applications. Bundle Services and String Services (already described in Section 1.4.1) are Core Foundation services. Other Core Foundation interfaces handle plug-ins, preferences, and so on. The complete list of Core Foundation interfaces is as follows:
QuickDraw Text. Lets you draw simple text with more control than MLTE can give you. For more complex text manipulations, look into Apple Type Services for Unicode Imaging (ATSUI).
The Gestalt Manager. Lets your application determine specific information about the system or its interfaces. For example, you can call the Gestalt Manager to determine what version of a particular technology is installed. Doing so lets you avoid calling functions that may not be available on a particular computer.
Multiprocessing Services. Lets you create preemptively scheduled execution tasks (threads) in your application. If your application might want to perform several actions simultaneously (such as downloading files or performing background calculations), you should consider adopting Multiprocessing Services. Tasks created with this interface will automatically take advantage of multiple processors, if present.
The Thread Manager. Lets you create cooperatively scheduled threads in your application. This interface is generally not as useful as Multiprocessing Services. However, if you need a certain amount of control over when your threads execute, you should consider the Thread Manager.
The Display Manager. Provides a way to manipulate multiple monitor locations and resolutions from your application. If your application needs the kind of control that the Monitors pane of System Preferences gives users, then consider adopting the Display Manager.
These are more esoteric interfaces that you generally would not use unless you were interested in creating specific types of applications. Some provide specialized features, while others expand on basic functionality (such as text manipulation). You use these interfaces to create highly sophisticated applications that take full advantage of the system software.
Note
For automobiles, these features would be for specific types of cars: turbocharging and tight suspensions for sports cars, flatbeds and towhooks for trucks, leather seats and soft suspensions for luxury cars, and so on.
QuickTime is Apple’s multimedia programming interface. You use QuickTime to create and play file-based or streaming movies, virtual reality environments, sounds, and music files. The Carbon developer documentation site groups QuickTime into the following categories:
As you can see, the QuickTime programming interface is huge and somewhat daunting. However, a good place to start exploring is the book Discovering QuickTime, published by Morgan-Kaufmann (see Appendix A).
These interfaces are for applications that create and manipulate images, such as a photo retouching program:
The Color Picker Manager lets you bring up a simple user interface for choosing colors, which can be useful for paint programs as well as any application that allows the user to customize colors.
ColorSync is an Apple technology that ensures consistent color calibration across different applications and hardware. For example, when using ColorSync, users can be sure that the particular shade of green they see on their monitor is as close as possible to what they will get when the local print house prints their brochure.
Picture Utilities are used to obtain information about a graphic image, such as the colors used, its resolution, and any comments that may be included.
For high-quality 3D graphics, the interface of choice is OpenGL. Okay, in actuality this is an industry-standard interface and not part of Carbon, but it is fully compatible with Carbon (just make sure you link to the OpenGL framework when you build). You can use OpenGL’s 3D rendering capabilities for everything from medical imaging to virtual reality to incredibly photorealistic games.
To display HTML text and images, you can use the HTML Rendering Library. Essentially, this interface allows you to render text and images in a window as if it were in a browser. It provides support for such design elements as border and scroll bars, as well as for navigation using URL links.
These interfaces let your application speak text or recognize speech:
The Speech Recognition Manager lets your application recognize spoken commands. For example, you can navigate between windows, open files, or run scripts solely through voice commands. It can be especially useful to activate commands that would normally require navigating deeply nested menus or multiple dialogs.
The Speech Synthesis Manager lets your application speak lines of text using a number of different voices. Note that the speech recognition and speech synthesis interfaces use the same English dictionary, which allows them to work in conjunction with each other. For example, you could use the Speech Synthesis Manager to determine how to pronounce a word, so the Speech Recognition Manager can recognize it more easily.
Most of these interfaces are only for developers writing text-intensive applications or those that handle multiple text encodings. For basic text input and display, the Multilingual Text Engine provides a much simpler interface for most of the same functionality.
ATSUI is the interface for drawing Unicode text. It allows precise control over all aspects of the text, from kerning to ligatures to bidirectionality.
The ATS types interface defines data types used by ATSUI and other text interfaces.
Date, Time, and Measurement Utilities contain functions to obtain and manipulate date, time, location, and other values that may need to be localized for different countries or regions.
The Dictionary Manager provides an easy interface to access dictionary files. For example, if your application contained a spell checker, it could use this interface to look up words in a dictionary file. Similarly, text input methods that require looking up words in a file could also use this interface.
The International Resources contain structures and constants that are used for localizing text to different countries or regions. In most cases, you won’t need to access this interface yourself, because other text interfaces will access it for you.
The Text Services Manager provides support for text input methods. For example, some non-Western text cannot be typed directly into a document, but first must be entered into a second window, using multiple keystrokes.
FontSync allows you to synchronize fonts available on different computers or printers to prevent font mismatches. For example, two fonts on different computers may have the same name but not be identical. FontSync can attempt to match fonts based on content rather than name, thus minimizing the possibility of a mismatch when a text file is moved from one computer to another.
The Language Analysis Manager allows your application to manage language analysis engines (stored as plug-ins). These engines are typically used with text input methods to isolate meaningful words or characters. For example, for Japanese text input you may use a language analysis engine to interpret the keystrokes the user enters, so you can display the Kanji characters that match their meaning.
The Script Manager allows you to handle older Mac OS script systems (or text encodings), providing support for text input and display processing. On Mac OS X you will usually be handling Unicode text, so you probably won’t need this interface.
The Text Encoding Conversion Manager allows you to change text from one encoding to another. This conversion can be useful for text going to or from the Internet, where many different text encodings exist. For example, to read text streamed over a network from a Windows computer, you may need to convert it from the Windows text encoding to the corresponding one for Macintosh computers. Similarly, if you are handling input methods or file systems that only support the older Mac OS encodings, you can use the Text Encoding Converter to convert between them and Unicode.
Text Utilities let you perform basic manipulation of non-Unicode text strings. If Mac OS X is your primary platform, you will likely be using Unicode strings, which means you should investigate the Unicode Utilities or Core Foundation String Services instead.
Unicode Utilities let you perform basic manipulation of Unicode strings. Note that Core Foundation String Services provide similar functionality and are more portable across Mac OS X execution environments.
If your application uses or enables network access, you will need to call functions from the following managers or services:
Internet Config, which is used to access Internet networking preferences from a global repository on a user’s machine. For example, Internet Config stores the user’s default browser selection, so if another application needs to launch a browser (when a URL is clicked), it can easily determine which one to activate.
Open Transport is Carbon’s low-level networking interface. Typically you need this interface only if you are implementing network protocols (such as TCP/IP) in your application or driver.
Network Services Location Manager, which provides an easy way to find network services on a local network.
URL Access Manager, which provides an easy interface for uploading and downloading files to and from a given URL.
If you want your application to provide security measures available on the Macintosh, you should consider these interfaces:
Security Services is the interface you use to add such security features as certificates and encryption/decryption to your application.
The Keychain Manager manages the keychain, which is an encrypted repository for all of a user’s passwords. By using the keychain, a user need remember only the password that unlocks the keychain. Once the keychain is unlocked, the user can access transparently all the services or applications whose passwords are stored in the keychain. If your application prompts the user for passwords to access particular services or features, you can use the Keychain Manager to access or store these passwords in the keychain.
If your application needs to access or control specific low-level functionality, you should consider these interfaces. Note, however, that Mac OS X is designed to shield applications from low-level workings of the system. To that end, you should use one of these interfaces only if you are sure you need its particular functionality:
I/O Kit is the Mac OS X interface for hardware. While not considered part of the Carbon programming interface, if you are writing driver-level code that needs to talk directly to hardware (such as a video card), you need to use I/O Kit. Most applications don’t need this level of control and should not be at all dependent on hardware.
The Power Manager allows you to control power management features. For example, a screen saver program could use this interface to put the PowerBook to sleep after a given time. Other applications may want to monitor the battery status of the PowerBook.
Memory Management Utilities are used for specialized low-level memory operations, such as direct memory access (DMA) and those that take place at the interrupt level. Many of the functions in this interface aren’t even supported in Carbon, and it is unlikely that you will need to use the ones that are.
This section covers utility interfaces that may be useful, depending on the application. These managers and services aren’t particularly related to any technology or functionality:
Note
If Carbon were for cars, these interfaces would add possibly useful features, such as headlight wipers, cup holders, curb feelers, and GPS units.
Error Handler. Lets you trap and display certain system errors. It’s mostly used by system software, and you will probably never need to use it.
Time Manager. Lets you set timers to perform periodic actions or to have actions occur at a particular time. Although timers in the Carbon Event Manager can provide some of the same functionality, the Time Manager is useful for cases where you need something to happen outside of your usual event loops.
Finder. This interface contains a number of structures that are useful for giving information to the Finder.
Debugger Services. Contains functions that can assist you in debugging your application. In most cases, however, you should begin with the debugging facilities available with Project Builder before using this interface.
Mathematical and Logical Utilities. Exactly what you think it is.
Pascal String Utilities. More or less what you think it is. In most cases you will be using Unicode Strings on Mac OS X, but if you need to manipulate Pascal strings, this is where to go.
This section covers Carbon interfaces that are mostly of historical interest. These interfaces were included to assist developers porting legacy Mac OS code to Mac OS X. For new developers, these interfaces may be useful only to gain perspective on the evolution of Macintosh system software. In most cases, the functionality of these managers is covered in a newer interface.
Note
If Carbon were for cars, these interfaces would add older features such as hubcaps, ashtrays, carburetors, and whitewall tires.
Event Manager. Originally written to handle the older cooperative multitasking event model. The Carbon Event Manager is both more efficient and easier to implement.
Process Manager. Also written for the older cooperative multitasking environment.
Code Fragment Manager. Written to allow the system and applications to prepare and execute Preferred Executable Format (PEF) binaries, the native executable file format for PowerPC Macintosh computers. While Mac OS X supports PEF binaries, the native executable file format is called Mach-O.
Component Manager. Older Mac OS programs often loaded special format plug-ins using the Component Manager. On Mac OS X, you should use the Plug-In Services interface in Core Foundation.
Collection Manager. This interface let you create abstract data types to store related information together. On Mac OS X, you should use the Core Foundation interface Collection Services instead.
Device Manager. Older Mac OS programs accessed hardware through the Device Manager. On Mac OS X, you should use the I/O Kit instead.
List Manager. Formerly used to create columned lists of data (similar to the list view option in a Finder window), you should now use the data browser functions and data types that have been added to the Control Manager.
TextEdit. An interface to perform basic text manipulation. Its replacement, the Multilingual Text Engine, offers significant additional features, such as Unicode support.
Palette Manager. This interface allowed to you specify the contents of palettes, which let you specify the colors to use to render an image. For example, if a picture contained mostly dark colors, grays and blues, you could index the palette to use only those colors, eliminating those that didn’t appear (yellows, bright red). Using a fixed selection of colors allowed you to reduce the size of the image, because not as much information was needed to render it. The Palette Manager was useful in the days when, due to memory constraints, many computers could display only a limited number of colors.
Notification Manager. This interface allowed applications in the background to notify the user (for example, after finishing a lengthy calculation). Because the Carbon Event Manager defines events that cover the same functionality, you should use that interface instead.
Mixed Mode Manager. Originally designed to allow PowerPC code to call emulated 68K code (and vice versa), the Mixed Mode Manager is now used to allow CFM-based PEF code to call Mac OS X’s native Mach-O code and vice versa. Because you are already building Mach-O-based applications with Project Builder, however, you don’t need this interface.
Low Memory Accessors. These functions allowed you to access useful system information (such as the location of the mouse) stored as global variables in so-called “low memory.” This practice of accessing low memory directly was questionable even then, and certainly not suggested now. In almost all cases, better, safer functions exist in other interfaces for obtaining the same information.
SCSI Manager. Originally written to communicate with SCSI devices. On Mac OS X you should use the I/O Kit instead.
Get Learning Carbon now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
