Related Info: Quickdraw Window Manager Font Manager
Menu Manager TextEdit Dialog Manager

A Role of the Dice

Traditional C programming vs. Macintosh C programming

By Dave Mark, MacTutor Regular Contributing Author

About the author

Dave Mark is an accomplished Macintosh author and an Apple Partner. He is the author of The Macintosh Programming Primer Series which includes: Macintosh C Programming Primer, Volumes 1 and 2; Macintosh Pascal Programming Primer, Volume 1, and his latest book, Learn C on the Macintosh. These books are available through the MacTutor Mail Order Store located in the back of the magazine. Dave is also the “professor” on the Learn Programming Forum on CompuServe. To get there, type GO MACDEV, then check out section 11.

Last month, we discussed Macintosh development economics in an article entitled, “Getting the best rate on an adjustable, MPW/Inside Macintosh, jumbo mortgage”. This month, we’re going to build two programs, each of which tackles the same task. The first uses the traditional, character-based approach typical of a PC or Unix-based environment. The second program solves the same problem using an approach that is pure Macintosh. Get your Mac fired up, and let’s get started.

The Environment

Since we’re going to be coding together, I thought I’d pass along some specifics about my development environment. All the code presented in this column was developed and tested in this environment. I’m using a Mac IIci with 8 MB of RAM and a Daystar Digital FastCache card. I’m running THINK C 5.0, and ResEdit 2.1.1. The whole shooting match runs under System 7, with 32-bit mode turned on.

GenericDice: Proof That Math Really Works!

Our first application, GenericDice, rolls a pair of simulated dice 1000 times, displaying the results in THINK C’s console window (Figure 1). The results are listed in 11 rows, one for each possible roll of the dice. The first row shows the number of rolls that total 2, the second row shows the number of rolls that total 3, etc. The x’s to the right of each roll count show the roll count graphically. Each x represents 10 rolls.

Figure 1: GenericDice in action.

For example, of the 1000 rolls in Figure 1, 31 had a total of 2, 48 had a total of 3, 88 had a total of 4, etc. Notice the bell-shaped curve formed by the x’s. You math-hounds out there should recognize a normal distribution from your probability and statistics days.

Creating the GenericDice Project

Launch THINK C, creating a new project called GenericDice.Π (The Π character is created by typing option-p). THINK C will create a project window with the title GenericDice.Π. The project window (and the project file it represents) acts as a miniature database, tying together all the source code and library files that make up your project.

Select New from the File menu to create a new source code window. Type the following source code into the window:

/* 1 */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

short RollOne( void );
void  PrintRolls( short rolls[] );
void  PrintX( short howMany );

main()
{
 short  rolls[ 11 ], twoDice, i;
 
 srand( clock() );
 for ( i=0; i<11; i++ )
 rolls[ i ] = 0; 
 for ( i=1; i <= 1000; i++ )
 {
 twoDice = RollOne() + RollOne();
 ++ rolls[ twoDice - 2 ];
 }

 PrintRolls( rolls );
}

/****************** RollOne ************/
short RollOne( void )
{
 long rawResult;
 short  roll;
 
 rawResult = rand();
 roll = (rawResult * 6) / 32768;
 return( roll + 1 );
}

/****************** PrintRolls ************/
void  PrintRolls( short rolls[] )
{
 short  i;
 
 for ( i=0; i<11; i++ )
 {
 printf( "%3d  ", rolls[ i ] );
 PrintX( rolls[ i ] / 10 );
 printf( "\n" );
 }
}


/****************** PrintX ************/
void  PrintX( short howMany )
{
 short  i;
 
 for ( i=0; i<howMany; i++ )
 printf( "x" );


}

Select Save from the File menu and save the source code under the name GenericDice.c. Next, select Add (not Add...) from the Source menu to add GenericDice.c to the project. Finally, select Add... from the Source menu to add the ANSI library to the project. You’ll find ANSI inside your Development folder, inside the THINK C Folder, inside the C Libraries folder. ANSI contains the standard C routines defined by the ANSI C standard. ANSI contains such routines as printf(), getchar(), and strcpy().

Figure 2: The GenericDice project window, before compilation.

Once ANSI has been added to your project, your project window should look like the one shown in Figure 2. The number to the right of each of the two files indicates the size of the object code associated with each file. Since GenericDice.c hasn’t been compiled yet and ANSI hasn’t been loaded, both files have an object size of 0.

Running GenericDice.Π

Select Run from the Project menu, asking THINK C to compile and run your project. If you run into any compile or link errors, check the code over carefully. Once your project runs, you should see something similar to Figure 1. Since GenericDice uses a random number generator to roll its dice, the numbers will change each time you run the program.

Walking Through the Source Code

GenericDice consists of four routines, main(), RollOne(), PrintRolls(), and PrintX(). GenericDice.c starts off by including <stdio.h>, <stdlib.h>, and <time.h>. These three files contain the prototypes and constants needed to access the ANSI library functions printf(), srand(), and clock().

/* 2 */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

The ANSI library is one of the reasons for C’s tremendous success. As evidenced by this program, as long as a program is restricted to the functions that make up the program itself, as well as functions in the standard libraries, the program will recompile and run under any ANSI-compliant C environment.

Next come the function prototypes:

/* 3 */

short RollOne( void );
void  PrintRolls( short rolls[] );
void  PrintX( short howMany );

main() starts by initializing the standard ANSI random number generator. The random number generator’s seed is based on the time returned by clock().

/* 4 */

main()
{
 short  rolls[ 11 ], twoDice, i;
 
 srand( clock() );

Next, the array rolls is iniatialized to 0. rolls consists of 11 shorts, one for each possible two-dice total. rolls[ 0 ] holds the number of 2’s rolled. rolls[ 1 ] holds the number of 3’s rolled. You get the idea.

/* 5 */

 for ( i=0; i<11; i++ )
 rolls[ i ] = 0;

Next, the dice are rolled 1000 times. The routine RollOne() returns a number between 1 and 6. The two rolls are added together and the appropriate entry in the rolls array is incremented.

/* 6 */

 for ( i=1; i <= 1000; i++ )
 {
 twoDice = RollOne() + RollOne();
 ++ rolls[ twoDice - 2 ];
 }

Finally, the data in the rolls array is displayed via the call to PrintRolls().

/* 7 */

 PrintRolls( rolls );

RollOne() uses the ANSI library routine rand() to return a number between 1 and 6.

/* 8 */

/****************** RollOne ************/

short RollOne( void )
{
 long rawResult;
 short  roll;
 
 rawResult = rand();
 roll = (rawResult * 6) / 32768;
 return( roll + 1 );
}

PrintRolls() uses printf() to print each total in THINK C’s console window. Once a row’s total is printed, PrintX() is called to print the appropriate number of x’s. Once the x’s are printed, a carriage return sends the cursor to the beginning of the next line in the console window.

/* 9 */

/****************** PrintRolls ************/
void  PrintRolls( short rolls[] )
{
 short  i;
 
 for ( i=0; i<11; i++ )
 {
 printf( "%3d  ", rolls[ i ] );
 PrintX( rolls[ i ] / 10 );
 printf( "\n" );
 }
}

PrintX() uses printf() to print the letter x in the console window.

/* 10 */

/****************** PrintX ************/
void  PrintX( short howMany )
{
 short  i;
 
 for ( i=0; i<howMany; i++ )
 printf( "x" );
}

True Portability vs. the Macintosh Way

When you build a C program for a PC or Unix environment, you’ll typically use routines such as printf() and scanf() to implement the user interface. All interaction with the user occurs in a screen area known as the console. A typical console is 80 characters wide and 24 characters tall. To get to the next line of a console, you’ll use a line like:

printf( "\n" );

Most consoles support scrolling, so when you print a carriage return on the bottom line of the console, the console automatically scrolls up one line. Some consoles support escape sequences that allow you to move the text cursor to a specific character position.

If you write an ANSI C program, you’ll be able to run that program under any ANSI C environment. You’ll also be stuck with an extremely limited, character-based user interface. It’s a classic tradeoff - portability vs. innovation and flexibility.

When you enter the world of Macintosh programming, you’ll leave portability at the door. You’re going to write programs designed to run specifically on the Macintosh. Your programs won’t run on a PC, but they will sport the beauty and elegance of the Macintosh look and feel. Macintosh programs go well beyond the traditional console-based user interface. They’re constructed of far superior raw materials: scroll bars, icons, menus.

Each of these elements carries the leverage of the Apple design team. You’ll add the exact same scroll bars to your programs that the power programmers at Microsoft add to theirs. Just as generations of C programmers have benefitted from the standard ANSI libraries, you’ll make use of the Mac’s standard libraries, together known as the Macintosh Toolbox. There are Mac Toolbox routines designed to create a new window, others that implement a pull-down menu. The Macintosh Toolbox is made up of over 2000 functions that, together, implement the Macintosh user interface. Each month, we’ll dig a little deeper into the Toolbox to learn how to implement new and wondrous Mac interface elements.

Our next program, MacDice, is a Macintized version of GenericDice. Though the basic data structures and logic will stay the same, MacDice foregoes ANSI routines like printf() in favor of a user interface that relies exclusively on the Macintosh Toolbox. Observe...

Creating the MacDice Project

Back in THINK C, close the GenericDice project. Create a new project called MacDice.Π. When the MacDice.Π project window appears, select New from the File menu to create a new source code window. Type the following source code into the window:

/* 11 */

#define kVisible false
#define kMoveToFront (WindowPtr)-1L
#define kNoGoAwayfalse
#define kNilRefCon 0L

void  ToolBoxInit( void );
void  WindowInit( void );
short RollOne( void );
void  PrintRolls( short rolls[] );
void  PrintX( short howMany );

/****************** main ************/
main()
{
 short  rolls[ 11 ], twoDice, i;
 
 ToolBoxInit();
 WindowInit();
 
 GetDateTime( (unsigned long *)(&randSeed) );
 
 for ( i=0; i<11; i++ )
 rolls[ i ] = 0;
 
 for ( i=1; i <= 1000; i++ )
 {
 twoDice = RollOne() + RollOne();
 ++ rolls[ twoDice - 2 ];
 }
 
 PrintRolls( rolls );
 while ( ! Button() ) ;
}

/****************** ToolBoxInit ***********/
void  ToolBoxInit( void )
{
 InitGraf( &thePort );
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs( nil );
 InitCursor();
}

/****************** WindowInit *************/
void  WindowInit( void )
{
 WindowPtrwindow;
 Rect   windowRect;
 
 SetRect( &windowRect, 20, 40, 220, 230 );

 window = NewWindow( nil, &windowRect, "\pMacDice",
 kVisible, documentProc, kMoveToFront,
 kNoGoAway, kNilRefCon );
 
 if ( window == nil )
 {
 SysBeep( 10 );  /*  Couldn't create a window!!!  */
 ExitToShell();
 }
 
 ShowWindow( window );
 SetPort( window );
 TextFont( monaco );
 TextSize( 12 );
}

/****************** RollOne ************/
short RollOne( void )
{
 long   rawResult;
 short  roll;
 
 rawResult = Random();
 if ( rawResult < 0 )
 rawResult *= -1;
 roll = (rawResult * 6) / 32768;
 return( roll + 1 );
}

/****************** PrintRolls ************/
void  PrintRolls( short rolls[] )
{
 short  i;
 Str255 string;
 
 for ( i=0; i<11; i++ )
 {
 MoveTo( 10, 20 + 15 * i );
 NumToString( (long)(rolls[ i ]), string );
 DrawString( string );



 MoveTo( 45, 20 + 15 * i );
 PrintX( rolls[ i ] / 10 );
 }
}

/****************** PrintX ************/
void  PrintX( short howMany )
{
 short  i;
 
 for ( i=0; i<howMany; i++ )
 DrawChar( 'x' );
}

Figure 3: The MacDice project window, before compilation.

Select Save from the File menu and save the source code under the name MacDice.c. Next, select Add (not Add...) from the Source menu to add MacDice.c to the project. Finally, select Add... from the Source menu and add the MacTraps library to the project. You’ll find ANSI inside your Development folder, inside the THINK C Folder, inside the Mac Libraries folder. Where ANSI contains the standard C routines defined by the ANSI C standard, MacTraps contains the interfaces to the routines that make up the Macintosh Toolbox. We won’t be adding ANSI to this project.

Once MacTraps has been added to your project, your project window should look like the one shown in Figure 3.

Running MacDice.Π

Select Run from the Project menu, asking THINK C to compile and run your project. If you run into any compile or link errors, check the code over carefully. Once your project runs, you should see something similar to Figure 4. Like GenericDice, MacDice will change every time you run it. To exit MacDice, just click the mouse button.

Figure 4: MacDice in action!

Walking Through the Source Code

MacDice consists of six routines, main(), ToolBoxInit(), WindowInit(), RollOne(), PrintRolls(), and PrintX(). MacDice.c starts off by defining some useful constants. I’ll explain each of these as they occur in context.

/* 12 */

#define kVisible false
#define kMoveToFront (WindowPtr)-1L
#define kNoGoAwayfalse
#define kNilRefCon 0L

Next come the function prototypes. You do prototype all your functions, right?

/* 13 */

void  ToolBoxInit( void );
void  WindowInit( void );
short RollOne( void );
void  PrintRolls( short rolls[] );
void  PrintX( short howMany );

main() starts off by initializing the Macintosh Toolbox. Every Mac program you write will start off this way. Once the Toolbox is initialized, you can call the Toolbox as much as you like. Our first venture into the Toolbox lies inside the routine WindowInit(), which creates a standard Macintosh window.

/* 14 */

/****************** main ************/
main()
{
 short  rolls[ 11 ], twoDice, i;
 
 ToolBoxInit();
 WindowInit();

Next, the Mac’s random number generator is seeded using a Toolbox routine that fetches the current time in seconds. randSeed is a system global, a global variable automatically made available to every Macintosh program. There are lots of system globals. For the most part, you won’t need to access them directly, however. To find out more, check out the table of system globals in the Inside Macintosh X-Ref.

/* 15 */

 GetDateTime( (unsigned long *)(&randSeed) );

The rest of main() should look pretty familiar. Most of it is identical to its GenericDice.c counterpart. Roll a pair of dice 1000 times, keep track of the results, then call PrintRolls() to display that beautiful bell curve.

/* 16 */

 for ( i=0; i<11; i++ )
 rolls[ i ] = 0;
 
 for ( i=1; i <= 1000; i++ )
 {
 twoDice = RollOne() + RollOne();
 ++ rolls[ twoDice - 2 ];
 }
 
 PrintRolls( rolls );

The ANSI C standard limits the user interface of your program to straight text input and output. If you want to draw a circle on the screen, you’ll have to make one out of ASCII characters like '.' or 'x'. Program output intended for the user's eyes are displayed on the user's console. THINK C provides a special window that serves as a console. This console window is created automatically whenever you call a routine that makes use of it. Once your program finishes, THINK C waits for you to hit a carriage return (or to select Quit from the File menu) before it closes the console window and terminates the program.

Proper Macintosh programs do not make use of the console. One of the biggest challenges in porting a console-based C program to the Macintosh lies in converting all the printf() and scanf() calls to the appropriate Mac Toolbox calls.

For the moment, we’ll call a Mac Toolbox routine named Button() to determine when to exit. Button() returns true if the mouse button is currently pressed. This line of code loops until the mouse button is pressed:

/* 17 */

 while ( ! Button() ) ;

A friendly (yet somewhat sinister) warning from the Thought Police: A proper Macintosh program exits when Quit is selected from the File menu. Since we haven’t covered menus yet (we’ll get to it, don’t worry), we’ve received temporary dispensation to exit when we detect a mouse click.

The Macintosh Toolbox is made up of a series of managers. Each manager is a collection of related functions. For example, the Window Manager is a collection of routines to create and manage windows. QuickDraw is a collections of routines that allow you to draw inside a window. The Font Manager helps you draw text in a window.

ToolBoxInit() initializes each of the managers used by your program. InitGraf() initializes QuickDraw, setting up a data structure called thePort, which acts as a focal point for all drawing performed by your program. InitFonts() initializes the Font Manager, InitWindows() initializes the Window Manager, InitMenus() initializes the Menu Manager, TEInit() initializes the Text Edit Manager, InitDialogs() initializes the Dialog Manager, and InitCursor() sets the cursor to the traditional, arrow shaped cursor.

/* 18 */

/****************** ToolBoxInit ***********/
void  ToolBoxInit( void )
{
 InitGraf( &thePort );
 InitFonts();
 InitWindows();
 InitMenus();
 TEInit();
 InitDialogs( nil );
 InitCursor();
}

For the moment, don’t worry too much about what each of these routines do. Just remember to call ToolBoxInit() before you call any Mac Toolbox routines that depend on the data structures initialized by ToolBoxInit(). Next month, we’ll explore some of these data structures. For now, we’ll call ToolBoxInit() right out of the box.

WindowInit() (not to be confused with the InitWindows() Toolbox routine) uses NewWindow() to create a brand new window data structure. The dimensions of the window are specified by windowRect, a variable of type Rect. A Rect has four fields, shorts named left, top, right, and bottom. The Toolbox routine SetRect() sets the fields of windowRect with the four specified parameters. SetRect() is described on page 174 of Volume I of Inside Macintosh. From now on, references to Inside Macintosh will appear in the form (I:174). (I:174) refers to Volume I, page 174.

/* 19 */

/****************** WindowInit *************/
void  WindowInit( void )
{
 WindowPtrwindow;
 Rect   windowRect;
 
 SetRect( &windowRect, 20, 40, 220, 230 );

NewWindow() creates a new window based on its eight parameters, returning a pointer to the data structure in memory. NewWindow() is described on (I:282).

The first parameter points to the memory allocated for the window. Passing nil asks the Window Manager to allocate memory for you. The second parameter is a Rect that determines where the window will appear on the screen. The third parameter is a Str255 specifying the window’s title. The \p in the string tells THINK C to generate the string in Pascal format as opposed to C format.

While C strings are null terminated, Pascal strings start with a length byte, followed by the specified number of bytes. Pascal strings are limited to a total of 256 bytes, including the length byte. Be cautious! Most Mac Toolbox routines require their strings in Pascal format. Why is that? Simple. The Mac System software was originally written in Pascal and, naturally enough, the Toolbox interfaces were designed with Pascal in mind.

/* 20 */

 window = NewWindow( nil, &windowRect, "\pMacDice",
 kVisible, documentProc, kMoveToFront,
 kNoGoAway, kNilRefCon );

The fourth parameter to NewWindow() specifies whether the window should be drawn on the screen or not. Typically, you’ll create a window invisibly, then make it visible when you are ready. You’ll see how in a minute.

The fifth parameter to NewWindow() specifies the type of window you’d like. A list of legal window types (and their respective comments) appear on (I:273). Experiment with these constants.

The sixth parameter specifies which window our new window should appear behind/in front of. By passing a constant of -1, we’re telling the Window Manager to make the window appear in front of all other windows.

The seventh parameter tells NewWindow() whether you’d like a close box in your window:

The eighth parameter is a long provided for your own use. Any value passed will be copied into the window’s data structure, available for later retrieval. In future programs, we’ll make use of this parameter. For now, we’ll pass a value of 0.

If NewWindow() couldn’t create the window (perhaps it ran out of memory) it will return a value of nil. In that case, we’ll beep once, then exit immediately. The parameter to SysBeep() is ignored.

/* 21 */

 if ( window == nil )
 {
 SysBeep( 10 );  /*  Couldn't create a window!!!  */
 ExitToShell();
 }

ShowWindow() makes the specified window visible. SetPort() makes the specified window the current port. Any subsequent QuickDraw calls will be performed on this port.

/* 22 */

 ShowWindow( window );
 SetPort( window );

At this point, don’t worry too much about the difference between ports and windows. We’ll get into ports and QuickDraw in next months column.

TextFont() and TextSize() specify the font and font size of all text drawn in the current port. After these two calls, all text drawn will appear in 12 point monaco. Feel free to experiment with different fonts and sizes. A list of predefined font names is provided in the file Fonts.h in the THINK C Folder, in the Mac #includes folder, inside the Apple #includes folder.

/* 23 */

 TextFont( monaco );
 TextSize( 12 );

RollOne() is pretty much the same as the version presented in GenericDice. The difference lies in the use of the Mac Toolbox random number generator Random(). Random() behaves almost exactly the same as the ANSI function rand(), with the exception that Random() returns both positive and negative numbers. If Random() returns a negative number, the returned value is multiplied by -1.

/* 24 */

/****************** RollOne ************/
short RollOne( void )
{
 long   rawResult;
 short  roll;
 
 rawResult = Random();
 if ( rawResult < 0 )
 rawResult *= -1;

 roll = (rawResult * 6) / 32768;
 return( roll + 1 );
}

PrintRolls() is much the same as its GenericDice counterpart. There is one important difference, however. The original PrintRolls() used printf() to display its data. Each character appeared, one after the other, in sequential order in the console window. To move to the next line, a carriage return is printed. There is a definite sense of moving to the right, and then downwards in the console window. When the bottom of the window is reached, it scrolls automatically.

The new PrintRolls() is completely responsible for determining the exact position of each character drawn. Instead of being restricted to one of 80 x 24 character positions, you can draw a character starting at any pixel within the current window. The resolution of the console is 80 x 24. The resolution of a window is <the window’s width in pixels> x <the window’s height in pixels>. A window 400 pixels wide and 300 pixels tall has a resolution of 400 x 300. Freedom! Flexibility! Hooray!

/* 25 */

/****************** PrintRolls ************/
void  PrintRolls( short rolls[] )
{
 short  i;
 Str255 string;
 
 for ( i=0; i<11; i++ ) {

The routine MoveTo() specifies the postion of the next drawing operation. This position is also known as the current pen position. NumToString() converts the specified long to a pascal string. DrawString() draws the string at the current position, moving the position of the pen to the end of the string just drawn.

/* 26 */

 MoveTo( 10, 20 + 15 * i );
 NumToString( (long)(rolls[ i ]), string );
 DrawString( string );

MoveTo() is called once again to move the pen a little bit to the right, in preparation of our call to PrintX().

/* 27 */

 MoveTo( 45, 20 + 15 * i );
 PrintX( rolls[ i ] / 10 );

Just as it did earlier, PrintX() draws the specified number of x’s. This time, however, the Toolbox routine DrawChar() is called to draw a single character in the current port, at the current pen position. DrawChar() and DrawString() each update the pen position, placing it at the end of the last character drawn.

/* 28 */

/****************** PrintX ************/
void  PrintX( short howMany )
{
 short  i;
 
 for ( i=0; i<howMany; i++ )
 DrawChar( 'x' );
}

Until Next Month...

Well, that’s about it for this month. Next month, we’ll look more closely at the relationship between the Window Manager and QuickDraw. We’ll discuss the Macintosh coordinate system, and you’ll learn the difference between local and global coordinates.

By the way, for those of you following the harrowing adventures of Dave Mark, father-to-be, you’ll be happy to know that Deneen and I went through the sonogram process today. If you don’t want to know the results, turn the page, quick! [Dramatic music, followed by rapid drum-roll]. A boy, a boy, it’s going to be a boy!!! All advice, congratulations, etc should be addressed to me on CompuServe, (70007,2530)...