TweetFollow Us on Twitter

MACINTOSH C CARBON
MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Mac OS in C
Version 1.0
2001 K. J. Bricknell
Go to Contents

PREFACE

The Carbon Application Programming Interface

Apple announced the intended introduction of a new operating system, to be known as Mac OS X, at the 1998 World Wide Developers Conference. Mac OS X, the first version of which was released on 24 March 2001, is not just another Mac OS update; it is a completely new operating system complete with "modern" operating system features such as pre-emptive multitasking and protected memory. It features a completely new user interface, called Aqua, whose appearance and behaviour differs significantly from that of the original Mac OS (represented in its latest, and no doubt last, incarnation by Mac OS 9).

Mac OS X runs on G3 and G4 PowerPC machines only, meaning that machines based on PowerPC 604 and 603 microprocessors must necessarily remain with Mac OS 9 and earlier. A large installed base of these latter machines will no doubt remain for many years to come. In addition, it is likely that many owners of machines capable of running Mac OS X will nonetheless remain with Mac OS 9 and earlier. In these circumstances, it was perceived as all but essential that programs written to take advantage of Mac OS X's advanced features also be capable of running on Mac OS 8 and 9 without modification. Fortunately, Apple has devised the means whereby this can be achieved, namely, the Carbon Application Programming Interface (API).

An API is basically a collection of system software routines, two examples being GetNewCWindow (which programmers call to create windows) and FSpOpenDF (which programmers call to open a file). Mac OS 9 includes a collection of more than 8,000 such system software routines, which are now known collectively as the Classic API. Apple determined that about 2000 of these APIs were incompatible with a modern operating system like Mac OS X. The remaining 6000 or so "clean" APIs were isolated and, together with many additions, included in the Carbon API.

It turns out, therefore, that experienced Macintosh programmers will not need to learn a completely new API in order to program for the completely new operating system that is Mac OS X. Any programmer familiar with the Classic API will be able to transition to the Carbon API with comparatively little effort. In addition, newcomers to Macintosh programming will not be required to learn two APIs in order to write applications intended to run native on both Mac OS X and Mac OS 8 and 9.

That said, there is another API, called Cocoa, that may be used to write programs for Mac OS X. Cocoa's advantage is that it allows applications to be written more quickly than is the case using the Carbon API; however, such applications will not run on Mac OS 8 and 9.

A further advantage of Carbon is that existing applications written using the Classic API can be "carbonized" with but a fraction of the effort that would be required to completely rewrite them for Mac OS X using the Cocoa API.

This book, then, is for those who wish to learn to create applications that will, firstly, run on both Mac OS X and Mac OS 8 and 9 and, secondly, take advantage of Mac OS X's unique features when run on that system. It is intended as a reasonably comprehensive entry point to programming the Macintosh using the Carbon API.

The First Task - Learn the C Language and CodeWarrior IDE

The main assumption made by this book is that you have already learned both the C language and the Metrowerks CodeWarrior IDE (Integrated Development Environment).

CodeWarriorU conducts on-line courses in the C language and the CodeWarrior IDE.

The Macintosh C Carbon Phase

When you have learned the C language and the fundamentals of the CodeWarrior IDE, you are ready to open this book. As you move through this second phase of the journey, you will quickly discover that learning C and the IDE was by far the easiest part!

Essentially, this book covers all of the territory which, in the author's judgement, needs to be covered before you write your first serious application. This includes, for example, how to create and manage all elements of the user interface (menus, windows, controls, dialogs, alerts, lists, drag and drop, etc.), how to perform file input/output, how to print documents, how to draw text and graphics, and so on.

General Structure of Macintosh C Carbon

The general structure of most chapters in this book is the same: first comes the information, then a list of constants, data types and functions relevant to the subject of that chapter, then the source code listing of one or more demonstration programs related to the subject of that chapter, and, finally, line-by-line comments that explain the workings of the source code.

The book itself is supported by the demonstration program package, which contains the CodeWarrior project and source code files, and Resorcerer resource files, for all demonstration programs. The demonstration programs associated with Chapter 18 to 25 exist in two versions:

  • The primary version, which utilises the Carbon event model introduced at Chapter 17, is the version whose source code listing and associated comments are included in the book itself.

  • The secondary version utilises the Classic event model (see Chapter 2). The explanatory comments for this version are contained in PDF files included in the relevant demonstration program (Classic event model version) folders.

What You Will Need

System Software

For Mac OS 8 and 9, Macintosh C Carbon requires:

  • CarbonLib 1.4 or later. (CarbonLib is the extension, located in the Extensions folder in the System folder, that implements the Carbon API on Mac OS 8 and 9.)

  • Mac OS 8.6 or later. (CarbonLib 1.4 and later are not compatible with versions of Mac OS 8 earlier than 8.6.)

For Mac OS X, Version 10.0.3 or later is required. (The so-called frameworks that implement the Carbon API on Mac OS X are an integral part of Mac OS X and are installed when you install that system. Frameworks are like shared libraries on Mac OS 8/9.)

Development System

As previously stated, it is assumed that your development system will be Metrowerks CodeWarrior. CodeWarrior Pro 6 (or later) is itself a Carbon application, and is much to be preferred.

Resource Editor

A resource editor allows you to create resources for programs and files. The resource editor you will need is Resorcerer, a product of Mathemaesthetics.

References and Other Sources of Information

References enable you to access information relating to the system software, and are quite indispensable. The Carbon Developer Documentation section and the Mac OS 8 and 9 Developer Documentation Function Index at Apple's WWW site are the most up-to-date sources of information available. You might also wish to subscribe to Apple's Carbon development mailing list .

Programmer's Calculator

You will find a programmer's calculator very useful for converting between decimal, hexadecimal and binary values, the shareware program CalcWorks being ideal for that purpose.

Icon Editor

Versions of Resorcerer earlier than Version 2.4 did not facilitate the creation of 32-bit icons or the large (128 by 128 pixel) thumbnail icons utilised by Mac OS X. If your version of Resorcerer is earlier than Version 2.4, the shareware program Iconographer is possibly the best option for the creation of these icons.

Universal Headers, CarbonLib, and Stub Libraries

The demonstration programs assume the use of Version 3.4.1 or later of the Universal Headers and, as previously stated, CarbonLib 1.4 or later.

The Universal Headers were introduced at the same time as the Power Macintosh. Amongst other things, they enabled programmers to write (Classic API) source code capable of being compiled as either 680x0 code or PowerPC code - hence the term "Universal".

If the version of CodeWarrior you are using includes an earlier version of the Universal Headers and/or the version of CarbonLib in your Mac OS 8/9 Extensions folder is earlier than 1.4 (or does not exist), you should download the CarbonLib SDK (Software Development Kit) Version 1.4GM (or later) and:

  • Replace the existing folder CIncludes in Metrowerks CodeWarrior / Mac OS Support / Universal / Interfaces with the one in the SDK.

  • Copy the extension CarbonLib from the SDK to the Mac OS 8/9 Extensions folder, replacing the existing version if it exists.

  • Copy the two stub libraries CarbonLib and CarbonFrameWorkLib from the SDK to Metrowerks CodeWarrior / Mac OS Support / Universal / Libraries / StubLibraries, replacing the existing versions if they exist.

Human Interface Guidelines - Mac OS 8/9

Useful additions to your library when you get further down the track would be the publications:

Demonstration Programs

For Mac OS 8/9, you should simply copy the folder Mac C Carbon Demos from the CD-ROM to a convenient location on your hard drive. For Mac OS X, you should copy the folder titled Mac C Carbon Demos to the Applications folder and the folder titled Demo Documents to the relevant user's Documents folder.

Before running a demonstration program, you should read the top section of the source code comments in the relevant chapter (or, for the Chapters 18-15 Classic event model versions, in the previously-mentioned PDF files). For most programs, this explains what to do, what to expect, and what to note. Note that the comments sections occasionally contain additional information incidental to the main purpose of the demonstration.

As far as is possible, each demonstration program avoids making calls to system software routines that are only explained in a later chapter. However, achieving that ideal has not been possible in the demonstration programs associated with the earlier chapters. For example, the demonstration program associated with Chapter 1 must, of necessity, make calls to system software routines relating to windows (the subject of Chapter 4) and drawing in a graphics port (the subject of Chapter 12). Where this occurs, you should simply accept, on faith, that the associated source code does as is stated in the demonstration program comments section. The important thing is to concentrate on that part of the source code pertaining to the subject of the chapter with which the program is associated.

Terminology

All but the later volumes of the official Mac OS reference work (Inside Macintosh) are Pascal-oriented, reflecting the fact that system software routines were originally designed to be called from a Pascal program. Because of this historically cosy relationship between Pascal and the Mac OS 8/9 system software, the C programmer will often be confronted by Pascal terminology. For example:

  • The Pascal terms "procedure" and "record" are sometimes used in C-oriented programming books and other publications in a context where the C programmer would ordinarily expect the terms "function" and "structure".

    In C, a routine which returns a value and a routine which does not return anything are both called functions. In Pascal, a routine which returns a value is also called a function; however, a routine which does not return anything is called a procedure.

  • The names of many system software data structures end in Rec (for record) rather than, say, Struc (for structure).

  • The names of certain fields in many system software data structures end in Proc (for procedure) rather than, say, Func (for function).

As a reflection of the fact that the later additions to Apple's Inside Macintosh series of publications are C-oriented rather than Pascal-oriented, this book uses C terminology exclusively. Hence "structure" is used rather than "record" and "function" is used rather than "procedure".

Early Days

This version of Macintosh C Carbon was finalised during the early days of both Mac OS X and the Mac OS 8/9 Carbon implementation. At that time, both systems contained bugs which impacted on some of the demonstration programs. Known issues in this regard, for which the author begs the reader's indulgence, are listed in the ReadMe file in the demonstration programs folder.

K. J. Bricknell, AM
Canberra
Australia
August 2001
brick@asiaonline.net.au

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Posterino 3.3.6 - Create posters, collag...
Posterino offers enhanced customization and flexibility including a variety of new, stylish templates featuring grids of identical or odd-sized image boxes. You can customize the size and shape of... Read more
Together 3.8.3 - Store and organize all...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Features Smart storage. With simple drag-and-drop... Read more
iClock Pro 3.4.9 - Customize your menuba...
iClock Pro is a menu bar replacement clock for Apple's default clock. iClock Pro is an update, total rewrite and improvement to the popular iClock. Have the day, date and time in different fonts and... Read more
Things 2.8.12 - Elegant personal task ma...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
Typinator 7.2 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Spotify 1.0.53.758. - Stream music, crea...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
beaTunes 4.6.14 - Organize your music co...
beaTunes is a full-featured music player and organizational tool for music collections. How well organized is your music library? Are your artists always spelled the same way? Any R.E.M. vs REM?... Read more
Vienna 3.1.10 :d05d7a5d: - RSS and Atom...
Vienna is a freeware and Open-Source RSS/Atom newsreader with article storage and management via a SQLite database, written in Objective-C and Cocoa, for the OS X operating system. It provides... Read more
Day One 2.1.8 - Maintain a daily journal...
Day One is the easiest and best-looking way to use a journal / diary / text-logging application for the Mac. Day One is well designed and extremely focused to encourage you to write more through... Read more
iDefrag 5.1.8 - Disk defragmentation and...
iDefrag helps defragment and optimize your disk for improved performance. Features include: Supports HFS and HFS+ (Mac OS Extended). Supports case sensitive and journaled filesystems. Supports... Read more

Latest Forum Discussions

See All

Fantasy MMORPG MU Origin adds new modes,...
MU Origin, Webzen’s highly popular fantasy MMORPG is getting ready to shake things up for the second time this year, as a new update makes its way to the Google Play and App Store from today. Introducing new systems, modes, and events, the land of... | Read more »
Blizzard is looking to hire a mobile dev...
A new thread on the popular video game rumor forum, NeoGAF, uncovered an interesting job listing over at Blizzard Entertainment. It appears the studio behindStarCraft, World of WarCraft, Hearthstone,andOverwatch is looking to bring on a new hire... | Read more »
Legend of Zelda meets Cooking Mama in ne...
Dungeon Chef is what happens when you mix the RPG elements (and style) of a Legend of Zelda game, with cooking elements. Although, now that The Legend of Zelda: Breath of the Wild also has cookingelements, so maybe the gameplay is not so novel.... | Read more »
ChordFlow (Music)
ChordFlow 1.0.0 Device: iOS Universal Category: Music Price: $6.99, Version: 1.0.0 (iTunes) Description: ChordFlow is a chord sequencer with a unique 4-track polyphonic arpeggiator, extensive chord library, MIDI out and Ableton Link... | Read more »
The Walking Dead: A New Frontier is out...
The newest season of Telltale Games'The Walking Dead is well underway. After the release of the third episode, "Above the Law" about a month ago, episode four, "Thicker Than Water" is hot and ready for more zombies and gut-wrenching emotional... | Read more »
Best games we played this week
Another week, another new wave of mobile games do dive into. We've dug through the list of apps that came out this week to tell you which apps are worth your sweet time. And while there weren't too many games this week, there were some big ones.... | Read more »
Vignettes (Games)
Vignettes 1.0.1 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.1 (iTunes) Description: Vignettes is a casual but unique exploration game without text or characters, where objects shapeshift as you spin them around... | Read more »
Get Me Outta Here is an 80s retro shoote...
Are you ready to fight some aliens? Because Crescent Moon Games has released the retro shooter Get Me Outta Here on iOS devices today. [Read more] | Read more »
Get a bunch of Apple productivity apps f...
If you're an Apple Mac owner, you're probably aware of the host of Apple productivity apps the company includes in all new Mac purchases. Apps like iMovie, Keynote, and of course, GarageBand. While you used to be able to also buy these apps... | Read more »
Terra Mystica (Games)
Terra Mystica 1.03 Device: iOS Universal Category: Games Price: $9.99, Version: 1.03 (iTunes) Description: Short Summary:≈≈≈≈≈≈≈≈≈≈≈≈≈ | Read more »

Price Scanner via MacPrices.net

DEVONthink To Go 2.1.3 For iOS Adds New Declu...
DEVONtechnologies has updated DEVONthink To Go, its iOS companion to DEVONthink for Mac. Enhancements and bug fixes in Version 2.1.3 include DEVONtechnologies’ new decluttering service for clipping... Read more
Use Apple’s Education discount to save up to...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free: -... Read more
Apple refurbished Apple Watches available sta...
Apple is now offering Certified Refurbished Series 1 and Series 2 Apple Watches for 14-16% off MSRP, starting at $229. An Apple one-year warranty is included with each watch. Shipping is free: Series... Read more
15-inch Touch Bar MacBook Pros, Apple refurbi...
Apple is offering Certified Refurbished 2016 15″ Touch Bar MacBook Pros for $360 to $420 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2.6GHz... Read more
13-inch MacBook Airs on sale for up to $150 o...
Overstock.com has 13″ MacBook Airs on sale for up to $150 off MSRP including free shipping: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $869.99 $130 off MSRP - 13″ 1.6GHz/256GB MacBook Air (sku... Read more
15-inch Touch Bar MacBook Pros on sale for $1...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $200 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
15-inch 2.7GHz Touch Bar MacBook Pros on sale...
Amazon has 2016 15″ 2.7GHz Apple Touch Bar MacBook Pros in stock today and on sale for $150-$200 off MSRP. Shipping is free: - 15″ 2.7GHz Touch Bar MacBook Pro Space Gray (sku MLH42LL/A): $2599 $200... Read more
Apple now offering Certified Refurbished 13-i...
Apple is now offering Certified Refurbished 2016 13″ Touch Bar MacBook Pros for $270-$300 off original MSRP. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.9GHz... Read more
MyGiHealth Digestive Symptom Tracker Version...
My Total Health, Inc. has announced the release of MyGiHealth 2.1, an important update to their digestive symptom tracker developed exclusively for iPhone, iPad and iPod touch devices. MyGiHealth is... Read more
Galaxy S8 Materials Costs Highest by Far Comp...
The new Samsung Galaxy S8 equipped with 64 gigabytes (GB) of NAND flash memory carries a bill of materials (BOM) cost that comes out to US$301.60, much higher than for previous versions of the... Read more

Jobs Board

*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Music Marketing Lead, iTunes & *Apple*...
# Music Marketing Lead, iTunes & Apple Music Job Number: 56868140 Culver City, California, United States Posted: Apr. 17, 2017 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Media Products - Commerce Engineerin...
Apple Media Products - Commerce Engineering Manager Job Number: 57037480 Santa Clara Valley, California, United States Posted: Apr. 18, 2017 Weekly Hours: 40.00 Job Read more
*Apple* Mac Computer Technician - GeekHampto...
…complex computer issues over the phone and in person? GeekHampton, Long Island's Apple Premium Service Provider, is looking for you! Come work with our crew Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.