ColorMondrian
Volume 9
Number 12
Column Tag: Getting Started
Color Quickdraw, Part II 
Walking through the ColorMondrian code
By Dave Mark, MacTech Magazine Regular Contributing Author
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Last month’s column introduced ColorMondrian, our first attempt at
programming with Color QuickDraw. This month, we’ll walk through the
ColorMondrian code and take a closer look at Color QuickDraw and Gestalt(), the
Toolbox routine that knows everything there is to know about your Macintosh.
Before we get started, let’s take a quick look back at ColorMondrian. Figure 1
shows a sample ColorMondrian window. On a Macintosh with a single display, the
window will appear centered below the menu bar. On a Macintosh with more than one
display, the window will appear centered on the display with the deepest pixel settings
(more on pixel depth in a minute). If that display contains the menu bar, the centering
algorithm takes that into account.
Figure 1. ColorMondrian in action.
Another feature of ColorMondrian is the Devices menu. A hex address appears in
the Devices menu for every monitor attached to your Macintosh. A check-mark appears
next to the address representing the monitor with the deepest settings. Figure 2 shows
my Devices menu.
Figure 2. My devices menu.
Some Color Quickdraw History
Early Macintosh models operated under a relatively simple graphics model. Color
consisted of a choice of 8 colors (one of blackColor, whiteColor, redColor, greenColor,
blueColor, cyanColor, magentaColor, and yellowColor). The color of the quickdraw pen
was specified using the routines ForeColor() and BackColor(). This model was later
named Classic QuickDraw.
On a Classic QuickDraw Mac, the display was built in to the Macintosh itself. A
portion of RAM was dedicated to the pixels of the display. Since each pixel was either
black or white, one bit was required for each pixel on the screen. Each row of pixels
was represented by a sequence of bytes, each byte representing 8 consecutive pixels.
The next row always started off with a new byte.
Remember the BitMapper program of a few month’s back? When it created a new
BitMap, it had to calculate the proper value for the rowBytes field of the BitMap.
Here’s the line of code that was used:
bPtr->rowBytes = (rPtr->right - rPtr->left + 7) / 8;
Alexei Lebedev (one of my CompuServe compatriots) rightly pointed out that this
code contains an error. Here’s the correct code:
/* 1 */
bPtr->rowBytes = (rPtr->right - rPtr->left + 7) / 8;
i = bPtr->rowBytes / 2;
if ( (2 * i) != bPtr->rowBytes )
bPtr->rowBytes ++;
Remember, we were trying to calculate the number of bytes needed to represent
one row of pixels in the Rect pointed to by rPtr. The first calculation was pretty
simple-minded. It forgot to take into account the fact that rowBytes must be even. An
even simpler way to do this:
/* 2 */
bPtr->rowBytes =
(((rPtr->right - rPtr->left - 1) / 16) + 1) * 2;
This uses less code, accomplishes the same thing, but seems a little less readable
to me. Ah, well, use whichever one you like...
As I was saying, a Classic QuickDraw Mac reserved part of main RAM to
represent the pixels on the screen, approximately one bit per pixel (allowing for some
possible wasted space at the end of each row). One bit-per-pixel is also known as a
pixel-depth of 1. To represent the eight colors of Classic QuickDraw, you’d need a
pixel-depth of 3 (to represent 8 possible values, you’d need 3 bits- 23 = 8)
When the Macintosh II was introduced, the first version of Color QuickDraw was
also introduced. This version of Color QuickDraw allowed you to display up to 256
simultaneous colors, representing a pixel depth of 8. For the first time, a Mac was
delivered that used a separate card for its video RAM, freeing up main RAM for
application/System use! The Mac II also represented the first Mac with a separate
monitor. The video card was attached to the mother board via the Mac’s new bus
structure, named NuBus.
Later versions of Color QuickDraw allowed for higher pixel-depths. The version
of Color QuickDraw that could handle a pixel-depth up to 32 became known as 32-Bit
QuickDraw. When 32-Bit QuickDraw was first released, it required a separate
extension to work, though this code was later added to the System and became a standard
part of a Mac’s ROM.
Color QuickDraw represents each graphics device attached to your Mac (whether
a display or an offscreen color device) using a gDevice data structure. Routines like
GetNextDevice() and GetMainDevice() (you’ll see them in a bit, when we walk through
the code) work with the list of gDevice’s maintained by Color QuickDraw and the Color
Manager.
The RGB Model
Color QuickDraw represents colors using the RGB model. RGB stands for red,
green, and blue, the three colors that combine to make up an RGB color. The RGB model
is based on the RGBColor data structure:
struct RGBColor
{
unsigned short red;
unsigned short green;
unsigned short blue;
};
Each component of an RGBColor can take on a value from 0 to 65535. If red,
green, and blue are all 0, the RGBColor represents the color black. If all three are
65535, the RGBColor represents the color white. If red is 65535 and blue and green
both 0, the color is red. You get the idea.
We’ll work with the RGB model throughout this program. Color QuickDraw does
support two other color models (HSV, which is hue, saturation and brightness and
CMY, which is cyan, magenta, yellow) and provides routines that convert colors
between all three models.
Color Windows
To take advantage of the Color QuickDraw routines, you’ll want to replace your
use of WindowRecords with CWindowRecords. CWindowRecords are similar to
WindowRecords with a CGrafPort replacing the traditional GrafPort. Even with these
changes, you can pass a pointer to a CWindowRecord to all the routines that usually
take a WindowPtr. You’ll see how this works as we walk through the code.
Before we get to the code, there’s one more topic to cover. Gestalt() provides
your application with information about the current state of your Mac’s hardware and
software. Here’s the prototype for Gestalt():
OSErr Gestalt( OSType selector,long *response );
Gestalt() takes two parameters. The first, selector, allows you to tell Gestalt()
what part of the hardware or software you are interested in. You can use Gestalt() to
find out how much RAM is on the current Mac, what version of the operating system is
installed, what processor this Mac is running, whether this machine supports Color
QuickDraw, and much, much more.
Depending on the selector used, the second parameter, response, contains the
requested information. You can tell the type of information returned by the last few
characters of the selector. If the selector ends in Attr, the response is in the form of a
32-bit bitmap, where different bits stand for different features being available. A set
of constants are available for each Attr selector you’ll use to see if the bits you are
interested in are set.
If the selector ends in Count, the response is a number indicating an amount.
If the selector ends in Size, the response is a size, usually in bytes.
If the selector ends in Table, the response is the address of the first byte of a
table.
If the selector ends in Type, the response is a value describing a particular type
of feature. You’ll compare this value to a list of constants provided for each type.
If the selector ends in Version, the response is a version number. A version
number with a decimal point (like 7.01) is usually represented as a two byte value
with the left side of the decimal in the left byte and the right side of the decimal in the
right byte.
Take the time to read about Gestalt(), either in Inside Macintosh or in THINK
Reference. Take a look at each of the list of posssible selector codes in the “Using the
Gestalt Manager” writeup.
In general, if you want to take advantage of a feature of the Macintosh that is not
necessarily available on every Mac, you’ll want to call Gestalt() to make sure the
feature is available. In case you were wondering, Gestalt() itself is not always
available. The routine SysEnvirons() is a precursor to Gestalt(). THINK C (version
5.0 and later) provides special glue that converts your Gestalt() call to the
appropriate SysEnvirons() call on a machine that doesn’t support Gestalt().
Therefore, you can always call Gestalt(). Be sure to check the error code returned by
Gestalt(), just in case it has trouble processing your request.
The ColorMondrian Source Code
Let’s get started with last month’s source code. We started off with two important
#includes. was included to give us access to sprintf(). sprintf() was used to
create the hex addresses in the Devices menu. was included to give us
access to Gestalt() and all its selector codes.
/* 3 */
#include
#include
These #defines will be explained as they appear in the code.
/* 4 */
#define kMBARResID 128
#define kErrorAlertID 128
#define kAboutALRTid 129
#define kSleep 0L
#define kAutoStorage NULL
#define kVisible true
#define kWindowTitle "\pColorMondrian
#define kMoveToFront (WindowPtr)-1
#define kNoGoAway false
#define kNULLRefCon 60L
#define mApple 128
#define iAbout 1
#define mFile 129
#define iQuit 1
#define mDevice 131
#define kWindowMargin 5
#define kRandomUpperLimit 32768
#define kEmptyString "\p
#define kNULLFilterProc NULL
The global gDone is set to false initially, then set to true when Quit is selected
from the File menu.
/* 5 */
/*************/
/* Globals */
/*************/
Boolean gDone;
As always, here are the function prototypes.
/* 6 */
/***************/
/* Functions */
/***************/
void ToolboxInit( void );
void MenuBarInit( void );
void CreateWindow( GDHandle device );
void EventLoop( void );
void DoEvent( EventRecord * eventPtr );
void HandleMouseDown( EventRecord * eventPtr );
void HandleMenuChoice( long menuChoice );
void HandleAppleChoice( short item );
void HandleFileChoice( short item );
void HandleDeviceChoice( short item );
Boolean HasColorQD( void );
GDHandle GetDeepestDevice( void );
short GetDeviceDepth( GDHandle device );
void DrawRandomRect( void );
void RandomColor( RGBColor *colorPtr );
void RandomRect( Rect *rectPtr );
short Randomize( short range );
void DoError( Str255 errorString );
main() starts by initializing the Toolbox. Next, the routine HasColorQD() is
called to see if Color QuickDraw is installed on this Macintosh. As you’ve probably
guessed, HasColorQD() uses Gestalt() to answer this question. If Color QuickDraw is
not available, an error message is displayed.
/* 7 */
/****************** main ***************************/
void main( void )
{
ToolboxInit();
if ( ! HasColorQD() )
DoError(
"\pThis machine doesn't support Color QuickDraw!" );
If Color QuickDraw is not installed, we should exit the program, probably by
calling ExitToShell() immediately after DoError(). You might also exit the program
from inside DoError().
A more sophisticated approach is to create a global Boolean named
hasColorQuickDraw or somesuch that you set at the beginning of your program, and
that you can check throughout your program. In many cases, you’ll want your program
to work, whether Color QuickDraw is available or not. Using a global makes this
information available throughout your program.
This approach is fine if the requested feature is something that won’t change as
your program executes. For example, if Color QuickDraw is not installed, it won’t
suddenly be installed halfway through your program’s execution.
On the other hand, there are some features of your environment that might
change as your program runs. For example, the user might change the color depth of
their monitor(s) as the program runs. If this is important to you, you can still
represent this information via a global, but you’d better update the global frequently.
Next, the menu bar is set up and the ColorMondrian window is created. The
routine GetDeepestDevice() returns a handle to the GDevice with the greatest
pixel-depth. This handle is passed to CreateWindow().
/* 8 */
MenuBarInit();
CreateWindow( GetDeepestDevice() );
Once the window is created, we start the color shape generation loop.
EventLoop();
}
Nothing new here.
/* 9 */
/****************** ToolboxInit *********************/
void ToolboxInit( void )
{
InitGraf( &thePort );
InitFonts();
InitWindows();
InitMenus();
TEInit();
InitDialogs( nil );
InitCursor();
}
MenuBarInit() starts off by loading the MBAR resource and adding the DRVRs to
the menu.
/* 10 */
/****************** MenuBarInit ***********************/
void MenuBarInit( void )
{
Handle menuBar;
MenuHandle menu;
GDHandle device, deepestDevice;
Str255 itemStr;
short curDeviceNumber = 1;
menuBar = GetNewMBar( kMBARResID );
SetMenuBar( menuBar );
menu = GetMHandle( mApple );
AddResMenu( menu, 'DRVR' );
Next, we set up the Devices menu. We retrieve the MenuHandle so we can add
items to it with AppendMenu(). Then, we retrieve a handle to the device with the
deepest pixel-depth.
/* 11 */
menu = GetMHandle( mDevice );
deepestDevice = GetDeepestDevice();
Next, GetDeviceList() gets called. GetDeviceList() returns a handle to the first
device in the list of devices. We’ll pass this device to GetNextDevice() to retrieve the
next device in the list. When the device we pass to GetNextDevice() is the last device in
the list, GetNextDevice() returns NULL.
/* 12 */
device = GetDeviceList();
For each device in the list, we’ll create a 10 character pascal string which will
contain the address, in hex, stored in the handle. We’ll use sprintf() to place the
address, in the desired format, in itemStr. Finally, the item is added to the menu via
AppendMenu().
/* 13 */
while ( device != NULL )
{
itemStr[0] = 10;
sprintf( (char *)(&(itemStr[1])),
"0x%08lX", (unsigned long)device );
AppendMenu( menu, itemStr );
If the device just added was the deepest device, we’ll add a check mark to the item.
/* 14 */
if ( device == deepestDevice )
CheckItem( menu, curDeviceNumber, true );
Finally, we’ll call GetNextDevice() and bump the value in curDeviceNumber.
/* 15 */
device = GetNextDevice( device );
curDeviceNumber++;
}
Once we drop out of the device loop, we draw the menu bar.
/* 16*/
DrawMenuBar();
}
CreateWindow() creates a window on the specified device.
/* 17 */
/****************** CreateWindow ***********************/
void CreateWindow( GDHandle device )
{
WindowPtr window;
Rect wBounds;
The handle stored in device must be dereferenced twice to get to the GDevice
struct. The gdRect field is a Rect containing the devices bounding rectangle.
/* 18 */
wBounds = (**device).gdRect;
GetMainDevice() returns a handle to the device containing the menu bar. If this
device is the main device, we need to take the height of the menu bar into account when
calculating the window’s Rect. GetMBarHeight() returns the height of the menu bar in
pixels.
/* 19 */
if ( device == GetMainDevice() )
wBounds.top += GetMBarHeight();
We use InsetRect() to make the window a little smaller, purely for aesthetics.
/* 20 */
InsetRect( &wBounds, kWindowMargin, kWindowMargin );
Now we call NewCWindow() to create a new CWindowRecord, as opposed to a
WindowRecord created by NewWindow().
/* 21 */
window = NewCWindow( kAutoStorage,
&wBounds,
kWindowTitle,
kVisible,
altDBoxProc,
kMoveToFront,
kNoGoAway,
kNULLRefCon );
If the window couldn’t be created, we display an error message. Again, I should
add a call to ExitToShell() at the end of DoError(), since there’s not a lot we can do
without a window to draw in.
/* 22 */
if ( window == nil )
{
DoError( "\pCouldn't create window!" );
}
else
{
ShowWindow( window );
SetPort( window );
}
}
EventLoop() is the same as it ever was, though we’ve added a call to
DrawRandomRect() to draw a ColorMondrian shape.
You might want to add some code here to recheck the pixel depth of all monitors
and update the check mark in the Devices menu if necessary. In fact, if the relative
depth’s of the monitors change (let’s say the user changes the depth of a monitor using
the Monitors control panel), you might want to move the window to the monitor that
just became deepest.
/* 23 */
/*********************** EventLoop *********/
void EventLoop( void )
{
EventRecord event;
GetDateTime( (unsigned long *)(&randSeed) );
gDone = false;
while ( gDone == false )
{
if ( WaitNextEvent( everyEvent, & event, kSleep, nil ) )
DoEvent( &event );
DrawRandomRect();
}
}
Nothing new here.
/* 24 */
/************************ DoEvent **********/
void DoEvent( EventRecord * eventPtr )
{
char theChar;
switch ( eventPtr->what )
{
case mouseDown:
HandleMouseDown( eventPtr );
break;
case keyDown:
case autoKey:
theChar = eventPtr->message & charCodeMask;
if ( ( eventPtr->modifiers & cmdKey) != 0 )
HandleMenuChoice( MenuKey( theChar ) );
break;
}
}
Nothing new here.
/* 25 */
/*********************** HandleMouseDown ***************/
void HandleMouseDown( EventRecord * eventPtr )
{
WindowPtr window;
short thePart;
long menuChoice;
thePart = FindWindow( eventPtr->where, &window );
switch ( thePart )
{
case inMenuBar:
menuChoice = MenuSelect( eventPtr->where );
HandleMenuChoice( menuChoice );
break;
case inSysWindow :
SystemClick( eventPtr, window );
break;
}
}
Nope. Same as always.
/* 26 */
/****************** HandleMenuChoice ***********************/
void HandleMenuChoice( long menuChoice )
{
short menu;
short item;
if ( menuChoice != 0 )
{
menu = HiWord( menuChoice );
item = LoWord( menuChoice );
switch ( menu )
{
case mApple:
HandleAppleChoice( item );
break;
case mFile:
HandleFileChoice( item );
break;
case mDevice:
HandleDeviceChoice( item );
break;
}
HiliteMenu( 0 );
}
}
In HandleAppleChoice() we added an about alert.
/* 27 */
/****************** HandleAppleChoice ***********************/
void HandleAppleChoice( short item )
{
MenuHandle appleMenu;
Str255 accName;
short accNumber;
switch ( item )
{
case iAbout:
NoteAlert( kAboutALRTid, kNULLFilterProc );
break;
default:
appleMenu = GetMHandle( mApple );
GetItem( appleMenu, item, accName );
accNumber = OpenDeskAcc( accName );
break;
}
}
Handle the File menu’s Quit item.
/* 28 */
/****************** HandleFileChoice ***********************/
void HandleFileChoice( short item )
{
switch ( item )
{
case iQuit :
gDone = true;
break;
}
}
This routine doesn’t do anything, but you might want to add some code here as
indicated by the comment. The toughest part here is finding a system with more than
one monitor to work with...
/* 29 */
/****************** HandleDeviceChoice ********************/
void HandleDeviceChoice( short item )
{
/* Try this:
Modify the program so that when a device is selected
from the Device menu, the current window gets closed and a
new window is opened on the selected device. Be careful when
you translate the menu item back into an address. Debug your
program thoroughly before you try to use the address as an
address. You don't want to accidentally reformat your hard
drive, right?
Also, don't forget to update the check mark!
*/
}
Here’s our call to Gestalt() to tell whether Color QuickDraw is installed. The
gestaltQuickDrawVersion selector retrieves a two byte value describing the version of
QuickDraw installed on this machine. If the first byte is 1, 8-bit Color QuickDraw is
installed. If the first byte is 2, 32-bit Color QuickDraw is installed. Either one of
these is fine for our purposes.
/* 30 */
/****************** HasColorQD *****************/
Boolean HasColorQD( void )
{
unsigned char version[ 4 ];
OSErr err;
err = Gestalt( gestaltQuickDrawVersion, (long *)version );
I should have called DoError() here. Either way, this doesn’t really represent a
proper error-handling strategy. I’d love to see an article on error handling in a future
issue of MacTech. Any takers?
/* 31 */
if ( err != noErr )
{
SysBeep( 10 ); /* Error calling Gestalt!!! */
ExitToShell();
}
If the 3rd byte (this is a 4-byte value - the 3rd and 4th bytes contain the 2
version bytes) is 1 or more, Color QuickDraw is installed.
/* 32 */
if ( version[ 2 ] > 0 )
return( true );
else
return( false );
}
GetDeepestDevice() steps through the device list, calling GetDeviceDepth() to
determine the device with the deepest pixel setting.
/* 33 */
/****************** GetDeepestDevice *****************/
GDHandle GetDeepestDevice( void )
{
GDHandle curDevice, maxDevice = NULL;
short curDepth, maxDepth = 0;
curDevice = GetDeviceList();
while ( curDevice != NULL )
{
curDepth = GetDeviceDepth( curDevice );
if ( curDepth > maxDepth )
{
maxDepth = curDepth;
maxDevice = curDevice;
}
curDevice = GetNextDevice( curDevice );
}
return( maxDevice );
}
GetDeviceDepth() starts by retrieving a handle to the device’s PixMap from the
GDevice struct. A PixMap is a color version of a BitMap. Check out the PixMap struct
in Inside Macintosh.
/* 34 */
/****************** GetDeviceDepth *****************/
short GetDeviceDepth( GDHandle device )
{
PixMapHandle screenPixMapH;
screenPixMapH = (**device).gdPMap;
The pixelSize field tells you the depth of this PixMap.
return( (**screenPixMapH).pixelSize );
}
DrawRandomRect() creates a random rectangle in the current window, generates
a random color, makes that color the current foreground color, then draws an oval in
that color.
/* 35 */
/****************** DrawRandomRect *****************/
void DrawRandomRect( void )
{
Rect randomRect;
RGBColor color;
RandomRect( &randomRect );
RandomColor( &color );
RGBForeColor( &color );
PaintOval( &randomRect );
}
RandomColor() randomly generates an RGBColor by randomly generating values
for red, green, and blue that range from 0 to 65534. Remember, Random() generates
values ranging from -32767 to 32767.
/* 36 */
/****************** RandomColor *********************/
void RandomColor( RGBColor *colorPtr )
{
colorPtr->red = Random() + 32767;
colorPtr->blue = Random() + 32767;
colorPtr->green = Random() + 32767;
}
RandomRect() generates a random Rect in the frontmost window.
/* 37 */
/****************** RandomRect *********************/
void RandomRect( Rect *rectPtr )
{
WindowPtr window;
window = FrontWindow();
rectPtr->left = Randomize( window->portRect.right
- window->portRect.left );
rectPtr->right = Randomize( window->portRect.right
- window->portRect.left );
rectPtr->top = Randomize( window->portRect.bottom
- window->portRect.top );
rectPtr->bottom = Randomize( window->portRect.bottom
- window->portRect.top );
}
Randomize() generates a number from 0 to the specified upper limit.
/* 38 */
/****************** Randomize **********************/
short Randomize( short range )
{
long randomNumber;
randomNumber = Random();
if ( randomNumber < 0 )
randomNumber *= -1;
return( (randomNumber * range) / kRandomUpperLimit );
}
/***************** DoError ********************/
void DoError( Str255 errorString )
{
ParamText( errorString, kEmptyString,
kEmptyString, kEmptyString );
StopAlert( kErrorAlertID, kNULLFilterProc );
}
Till Next Month...
There’s a lot to learn about Color QuickDraw. Hopefully, this column gave you a
good foothold. You will definitely want to read about the Color Manager, PixMaps, and
the Palette Manager in Inside Macintosh. In the meantime, I’m going to try to update
BitMapper to handle color. Look for PixMapper sometime soon...
