---

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. 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 Documentation Help feature integrated into Xcode. You can also consult the technical documentation on the Apple developer web site.

Carbon interfaces are defined as those accessed through the Carbon umbrella framework. See the header Carbon.h to see which interfaces are included.

In this section:

The Starter Kit
The Expansion Pack
Specialty and NonCarbon Interfaces
Utility Interfaces

The Starter Kit

This section covers the interfaces most likely to be called by a Macintosh application. These managers and services provide the basic user interface 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.

The Toolbox Interfaces

The following interfaces (sometimes called the Human Interface Toolbox or HIToolbox) are grouped together because they generally work together to create and manage the user interface. In most cases, Interface Builder and the Interface Builder Services programming 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 the Human Interface Toolbox interfaces:

• HIView/Control Manager. Lets you create and manipulate views, which are building blocks for user interface elements. All standard controls (buttons, scroll bars, sliders, and so on) are views, as is content displayed in a menu. Special views also exist for displaying text, HTML, and QuickTime content. HIView is superseding the older Control Manager, which let you manipulate controls. At the implementation level, however, HIViews and controls are identical objects in memory and can be used interchangeably.

• Dialog Manager. Lets you create and manipulate dialogs, which are windows that either prompt you for input or display information. Interface Builder and Carbon event handlers mostly supersede the Dialog Manager, except in the cases where you want to put up a standard alert dialog box or sheet.

• Menu Manager. Lets you create and manipulate menus.

• Window Manager. Lets you create and manipulate windows, which are the user's primary means of interacting with your software.

• HIToolbar. Lets you create and manipulate toolbars.

• HITheme/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. When you draw nonstandard user interface elements with HITheme, their appearance will continue to match the standard elements even if the theme changes (for example, from Aqua to Graphite). The Appearance Manager is the older QuickDraw-centric version of HITheme.

• 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.

• Interface Builder Services. Lets your code access the user interface elements created with Interface Builder and stored in a nib file. While Interface Builder is not required for creating your user interface, it simplifies the process and makes localization easier as well.

The User Interface

While the HIToolbox interfaces are flexible enough to let you do just about anything with your user interface, that doesn't mean you should. When designing and laying out your user interface, you need to follow the Apple Human Interface Guidelines. Just as adherence to common rules and customs when designing steering wheels and dashboards makes driving more pleasant and less confusing, following the Apple guidelines lets your application provide the best possible experience for your users.

If you use Interface Builder, adhering to the Apple Guidelines is that much easier; you can have it automatically tell you when various items in a window are spaced correctly.

Accessibility

While the standard user interface is sufficient for most users, those who have disabilities may need alternate methods to interact with your application. Apple provides a number of special accessibility features to meet this need. If you plan to sell your application to governmental agencies in the United States, your application must support accessibility.

Accessibility is not just a benefit for disabled users. An application that supports accessibility is also easier to test, and it makes it easier to provide explanatory help for all users.

See Accessibility Overview to learn more about accessibility on Mac OS X, and Accessibility Programming Guidelines for Carbon to learn what you need to do to support accessibility in Carbon applications.

Under the Hood

The following interfaces work behind the scenes, as it were, to provide the basic functionality that you expect from most applications:

• Carbon Printing Manager. Lets you print from Macintosh applications.

• Navigation Services. Creates a standard user interface for opening and saving documents.

• File Manager. Lets you read and write data to storage media (hard drives, USB drives, and so on).

• HIObject. A "base class" that provides the underlying support for HIViews. You probably won't need to access HIObject APIs directly unless you are creating custom HIViews.

• HIArchive. Provides an easy way to store and retrieve data and HIObjects (including HIViews). HIArchives are stored in a flattened format that you can save on disk or pass to other applications or services as desired.

• Bundle Services. Lets you access data stored in a bundle file hierarchy, which is the standard method of packaging applications in Mac OS X. Bundle Services is part of Core Foundation.

• String Services. Allows basic manipulation of Unicode strings. String Services is part of Core Foundation.

• 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. MLTE also provides support for spellchecking and accessing the standard system font panel.

• Quartz. Handles all the 2D drawing to the Macintosh screen. Quartz is a powerful imaging technology that provides easy access to features such as transparency, layers, path-based drawing, offscreen rendering, advanced color management, anti-aliased rendering, and PDF document creation, display, and parsing.

• HIShape. A Quartz-compatible interface for creating and manipulating arbitrary graphical shapes.

• HIGeometry. A Quartz-compatible interface for defining and manipulating basic graphical forms (points and rectangles).

• Uniform Type Identifers. Not a technology, but a standard for identifying data and file types that eliminates having to keep track of all the possible ways to tag a particular type (for example, using file extensions, MIME types, OSTypes, and so on). Navigation Services and the Pasteboard Manager are two technologies that use uniform type identifiers.

The Expansion Pack

This section lists interfaces that are desirable, but not necessary for most applications. Full-featured commercial applications usually adopt a number of these interfaces.

• Pasteboard Manager. Lets the user copy items to and from the Clipboard for cut-and-paste operations. More generally, you can use pasteboards for any sort of data interchange. For example, the Drag Manager uses pasteboards to transfer drag and drop data.

• 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.

• 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.

• Folder Manager. Lets you find, create, and otherwise manipulate specific folders such as a user's home directory or the system's Fonts folder.

• Alias Manager. Lets you create and resolve aliases to files and folders. An alias is a link or reference to an application, folder, or file.

• 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 object-based interfaces that can handle data types and various system services. Bundle Services and String Services (already described in "The Starter Kit") are Core Foundation services. Other Core Foundation interfaces handle plug-ins, preferences, and so on. For the complete list of Core Foundation interfaces see Core Foundation Framework Reference. To learn how to use Core Foundation APIs, see Getting Started with Core Foundation.

• Search Kit. Provides powerful text searching capability for your application. Apple’s Spotlight technology is built on top of Search Kit to provide content searching in Finder, Mail, and the Spotlight menu.

• Gestalt Manager. Lets your application determine specific information about the system, its interfaces, or the underlying hardware. 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.

• Notification Manager. This interface allows applications in the background to notify the user (for example, after finishing a lengthy calculation). A primary use of the Notification Manager is to notify the Dock about changes to the application.

• Process Manager. Lets you obtain useful information about running processes.

• 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.

• 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.

• Quartz Services. Lets you access low-level features of the Mac OS X Window Server. For example, you can use Quartz Services to change display modes, monitor configurations, and so on.

Specialty and NonCarbon Interfaces

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.

Many of these interfaces are not part of the Carbon framework, but can be called from Carbon applications.

Some of these interfaces have Objective-C APIs, which will require you to write some Objective-C code. For details on how to call Objective C code from C code, see Carbon-Cocoa Integration Guide.

QuickTime

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 QuickTime programming interface is broad and very powerful. To gain a better understanding of its features, read Getting Started with QuickTime and QuickTime Overview.

Core Video

Core Video complements QuickTime as it provides a way to access individual frames in the video pipeline. You can then manipulate the frames using OpenGL or Core Image. For example, if you want to add filter effects to the video, or map the video onto a shape, you can use Core Video to do so. See Core Video Programming Guide for more information.

Core Audio

Core Audio is the audio architecture for Mac OS X. It provides a broad range of audio and MIDI services for hardware and application developers, such as state-of-the-art audio recording and playback, digital signal processing, MIDI sequencing, low-level access to audio devices, software-based sound synthesis, and much more.

Color, Images, and Print Production

These interfaces are for applications that create and manipulate images, such as a photo retouching program:

• 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.

• Core Image provides access to built-in image filters for both still images and video and provides support for custom filters and near real-time processing. Core Image is an Objective-C API.

3D Graphics

For high-quality 3D graphics, the interface of choice is OpenGL. 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. See OpenGL Programming Guide for Mac OS X for more information about how to use OpenGL in Mac OS X.

HTML

To render HTML in Carbon windows, you can use Web Kit. HIView has a special web view that can display HTML acquired with Web Kit. See WebKit C Reference for more details.

Disc Recording and Playback

These interfaces let your application interact with CDs or DVDs.

• To burn data or audio to a CD or DVD from your application, use the Disc Recording API.

• To access and play DVD video content, use the DVD Playback API.

Sync Services

If your application needs to synchronize some of its data with a device, such as an iPod or PDA, you should use Sync Services to do so. You can also synchronize separate Macintosh computers if the user has a .Mac account. Sync Services is an Objective-C API.

Speech

These interfaces let your application speak text or recognize speech:

• 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.

• 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.

Text and International Services

Most of these interfaces are only for developers writing text-intensive applications. 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.

• ATS Types interface defines data types and callback functions 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.

• 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.

• Font Manager. Lets you manipulate the fonts that your application uses to display or print text.

• 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.

• Text Services Manager provides support for text input methods. For example, editing some types of non-Western text requires close cooperation between the application and the Text Services Manager to allow text input methods to access the application's windows. If you use the Multilingual Text Engine, all Text Services Manager support is handled automatically.

• 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.

• 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.

• 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.

• 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.

• Ink Services is an interface that lets users enter text using a stylus on a graphics tablet. The text is automatically recognized and translated into keystrokes that your application can then interpret.

Internet and Networking

If your application uses or enables network access, you may need to use one of the following managers or services:

• Core Foundation's CFNetwork Services provides interfaces for basic networking tasks, such as working with BSD sockets, managing information about remote hosts, and working with HTTP, HTTPS, and FTP servers. See CFNetwork Programming Guide for more information.

• Network Services Location Manager, which provides an easy way to find network services on a local network.

• Web Services, which provides an interface for transferring data over the internet using standard protocols such as HTTP and XML.

• 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.

Mac OS X also supports standard networking security features, such as SSL/TLS. See “Security” for more information.

Security

Mac OS X supports a number of standard security services (certificates, an authentication interface, SSL/TLS for networking, and so on) as well as Apple-specific features, such as keychains, which allow you store and access multiple passwords using a master password. For an overview of basic security concepts and the security services available in Mac OS X, see Security Overview. Getting Started with Security describes documentation available for implementing security features.

Low-Level Tweaking

Mac OS X is designed to shield applications from low-level workings of the system. However, 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.To that end, you should use I/O Kit only if you are sure you need it.

Utility Interfaces

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:

• 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 Xcode before using this interface.

• Assert Macros. Contains debugging macros that you might find useful. Many Apple code samples use these macros, so it's useful to understand how they work. These macros are defined in AssertMacros.h, which you can find in the /usr/include directory (use Terminal to access).

• Mathematical and Logical Utilities. Contains functions and constants for mathematical and logical operations (for example, FloatToFixed, pi, and BitAnd).

---