TweetFollow Us on Twitter

Jul 99 Getting Started

Volume Number: 15 (1999)
Issue Number: 7
Column Tag: Getting Started

Preferences Files

By Dan Parks Sydow

How a Mac program sets and retrieves program preferences

Two months back -- in May's Getting Started article -- we looked at how a program reads resources stored in an external resource file. In last month's Getting Started article we discussed how a Mac program reads data from a resource of a programmer-defined type. This month we introduce two new topics: creating a new resource file "on-the-fly" (during application execution), and writing data to a resource of a programmer-defined type. When we combine the concepts we covered in the previous two Getting Started articles with this month's new topics, the result is all the code necessary to provide your own application with the ability to create, read, modify, and make use of a preferences file.

Custom Resource Recap

Last month we developed the RsrcTemplate program to demonstrate how a Mac application works with resources of a custom type. Recall that we used ResEdit to create a single template resource of the standard resource type TMPL. In that resource we defined a number of fields, with each field having a ResEdit data type that corresponded to a C/C++ data type. Figure 1 shows last month's one TMPL resource, which we named TSTD. Recall that the name we chose was somewhat arbitrary (TSTD could be thought of as standing for TeST Data) -- the template name doesn't in any way define or limit the eventual contents of the template resource.



Figure 1. The TSTD template with three items.

A template resource itself doesn't hold data. Instead, a single TMPL resource serves to format any number of resources of still another type. That other type of resource is a custom type that bears the same name as the template that formats it. Continuing on with last month's example, Figure 2 shows that a custom TSTD resource displays its data in an easily readable manner because the TMPL resource of the same name is automatically used by ResEdit to display the resource.



Figure 2. A custom TSTD resource displayed using the TSTD template.

Figures 1 and 2 use the TSTD TMPL resource and the TSTD resource type -- but you'll note that in the figures these resources are held in a file named PrefFile.rsrc. This month's program PrefFile uses the exact same TMPL and TSTD resources that were developed last month. Yes, we did in fact have a valid reason for spending time creating those resources!

Once a custom resource exists, its data can be used by an application. PrefFile, as last month's RsrcTemplate program did, uses the value of the write item to see if the other TSTD resource data should be written to a program window. A write value of 0 means no, a write value of 1 means yes. The score item holds a high score (again, we're assuming we're writing a game), and the name item holds the name of the person who holds the high score.

An application accesses custom resource data by loading the resource into an application-defined data structure. This data structure defines fields that match the order and type of the data held in the resource. For the TSTD resource we came up with a corresponding data structure that looked like this:

typedef struct
{	
	short		write;
	long			score;
	Str255		name;
} TemplateRecord, *TemplatePtr, **TemplateHandle;

When the application needs to access information from a TSTD resource, it calls the Toolbox function Get1Resource() to load the resource data into memory and to return a handle to the data.

Handle		dataHandle;

dataHandle = Get1Resource( 'TSTD', 128 );

Accessing data is now done by typecasting the generic Handle to a handle of our own data structure type. Once that's done, any field in the structure can be accessed. Here the value of the write field is assigned to a local variable named resValue:

short		resValue;

resValue = (**(TemplateHandle)dataHandle).write;

Opening the Preferences File

Last month's RsrcTemplate program read data from a custom resource. If an application is to save user-defined data on disk for use in subsequent executions of the program, then that application also needs to be able to write data to a custom resource. Before writing a resource, though, we need to make sure the resource fork to be written to is open. If the fork is the appLication resource fork, we're all set -- that fork is always open. If, however, the fork is a part of an external file (which is the case for a preferences file), we need to open that fork.

Two months back, in the May Getting Started article, we looked at how a program opens the resource fork of a file in order to gain access to that file's resources. May's ResFiles example program used its OpenResourceFork() function to accomplish the task.

void		OpenResourceFork( void )
{
	short		volRef = 0;
	long			dirID = 0;
	FSSpec		rsrcFSSpec;
	OSErr		err;

	FSMakeFSSpec( volRef, DirID, kRsrcFileName, &rsrcFSSpec );

	gFileRsrcForkRef = FSpOpenResFile( &rsrcFSSpec, fsRdPerm );
	err = ResError();
	if ( err != noErr )
		DoError( "\pOpening resource file failed" );

	UseResFile( gFileRsrcForkRef );  
}

The above version of OpenResourceFork() works fine for a file that we know will be in the same folder as the application -- but that's not always this case. For a preferences file, that's almost never the case. Instead, a program should keep its preferences file in the Preferences folder in the System Folder on the user's startup drive. So instead of setting both the volume reference number and directory ID to 0 (which indicates that the item in question is in the same folder as the application), we'll use the Toolbox function FindFolder() to obtain a path to the user's Preferences folder.

FindFolder() is used to obtain path information to the Preferences folder, Apple Menu Item folder, Control Panels folder, and other system directories. The following is a typical call to the function.

short		volRef;
long			dirID;

FindFolder( kOnSystemDisk, kPreferencesFolderType,
					 kDontCreateFolder, &volRef, &dirID );

The first argument specifies the reference number of the volume that holds the folder in question. System-related folders should of course be on the startup disk, so the Apple-defined constant kOnSystemDisk is used here. To determine which folder to search for, FindFolder() accepts an Apple-defined constant as its second argument. The constant kPreferencesFolderType works for us. The third argument, which can be still another Apple-defined constant, specifies whether or not a new folder of this name should be created if an existing one can't be found. We'll assume that the user certainly has a Preferences folder. In return for this information, FindFolder() fills the fourth and fifth parameters with the volume reference number and directory ID of the sought-after folder.

With the path to the preferences file established, a file system specification, or FSSpec, for the file can be created. That FSSpec is then used in a call to FSpOpenResFile() to open the preferences file's resource fork. Since your program may be writing information to the file, make sure to pass the Apple-defined constant fsRdWrPerm as the second argument. This opens the file with both read and write permission.

FSMakeFSSpec( volRef, dirID, kPrefFileName, &prefFSSpec );

gFileRsrcForkRef = FSpOpenResFile(&prefFSSpec, fsRdWrPerm);

If FSpOpenResFile() fails to find the preferences file, it returns a value of -1. While a preferences file won't disappear on its own, a user who doesn't recognize the file by name may at some point "clean up" his disk and delete the file. In such a case, your program needs to create a new preferences file. In just a bit we'll cover how this is done. For now, we'll just make the check and then call our own CreateNewPrefFile() function if the preferences file is missing.

if ( gFileRsrcForkRef == -1 )
CreateNewPrefFile( prefFSSpec );

Writing To a Custom Resource

Writing data to a custom resource is essentially the reverse of the operations that were performed to read the data from the resource. In a previous snippet we assigned a local short variable named resValue the value of the write field of a TemplateRecord that was referenced by a handle named dataHandle.

Handle		dataHandle;
short		resValue;

dataHandle = Get1Resource( 'TSTD', 128 );
resValue = (**(TemplateHandle)dataHandle).write;

Here we'll now write back the value of resValue to the write field of a different TemplateRecord data structure. We begin by creating a new generic handle and clearing its memory. Next we typecast the handle to one of type TemplateHandle and then assign the write field the value of the resValue variable.

Handle			newDataHandle;

newDataHandle = NewHandleClear( sizeof( TemplateRecord ) );

 (**(TemplateHandle)newDataHandle).write = resValue;

Typically a program that saves user preferences includes a dialog box where the user enters his or her program preferences. If the user brings up this dialog box, enters some values, and then clicks the OK button, it's a simple matter for the program to collect the value from each dialog box item and fill in a data structure with those values. A program could work with the data structure that holds the original preferences values, and include a scheme to keep track of which values have changed and which are the same. But it's often easier to simply fill in the new structure completely without regard for which values have changed and which are unchanged.

After all of a structure's fields have been filled, the contents of the structure need to be saved to a resource on disk (at this point the data handle references the structure in memory, and has nothing to do with a resource). With the assumption that we've opened the preferences file, we begin by obtaining a handle that references the custom resource that we're about to save the new data to.

Handle			oldDataHandle;

oldDataHandle = Get1Resource( 'TSTD', 128 );

What we're about to do is delete the old, original resource and simply replace it with a new one. Before doing that we can get information about the original resource. The Toolbox function GetResInfo() returns a resource's ID, type, and name. The call to Get1Resource() included the type and ID of the resource -- so our program knew the type and ID of the resource in question. But the resource's name might not be known. While our example program doesn't provide a name for the custom resource (it has a type, TSTD, but any resources of that type haven't been named), your program might.

short			resID;
ResType		resType;
Str255			resName;

GetResInfo( oldDataHandle, &resID, &resType, resName );

Now it's time to remove the original resource and replace it with a new one that contains the data in memory that's referenced by the handle newDataHandle. The Toolbox functions RemoveResource() and AddResource() take care of this work for us.

RemoveResource( oldDataHandle );
AddResource( newDataHandle, resType, resID, resName );

Adding a resource doesn't write the new resource to disk -- a call to the Toolbox function WriteResource() does that.

WriteResource( newDataHandle );

Creating a New Preferences File

When a program attempts to open a file, that program needs to ensure that the file exists. In some cases, an external file may be critical to the operation of a program. That isn't, or shouldn't be, the case with a preferences file. While a missing preferences file will be an inconvenience to a user (the user's preferred settings will need to be re-entered), the program should be able to execute. To overcome the problem of a missing preferences file, your program can simply create a new preferences file and store a set of default values to it. The next time the user sets the preferences, the user's values will overwrite the default values.

If a program stores a copy of the custom resource used to hold preferences data in its own resource fork, the program will then always have a backup copy of a default set of preferences. In the case of our PrefFile program, the application would keep a TSTD resource in its own resource fork. If the program attempts to open its preferences file and the file is missing, the program will first load a copy of this TSTD resource into memory. After that, information about the resource is obtained by calling GetResInfo():

Handle			handle; 
 
handle = Get1Resource( 'TSTD', 128 );
GetResInfo( handle, &resID, &resType, resName );  

Now the resource data is in memory, and ready to be written to a file. A call to the Toolbox function FSpCreateResFile() creates the new resource file:

FSpCreateResFile( &prefFSSpec, 'RSED', 'rsrc', 
								 smSystemScript );

The first argument is an FSSpec that holds the path to the file that's to be created. If this file-creation code is the result of a failed attempt to open a preferences file, then your program will already have a suitable FSSpec. In the above snippet we'll assume that prefFSSpec is an FSSpec variable that comes from the code shown in this article's Opening the Preferences File section.

The second and third arguments are the application signature (or creator) and the file type for the program that can, by default, open the file. In the above snippet 'RSED' is the signature and 'rsrc' is the creator for ResEdit. Thus double-clicking on the file created by the above call to FSpCreateResFile() results in the launching of ResEdit and the opening of the file. This shouldn't be a concern for the user (since the user shouldn't ever need to go into the Preferences folder in the System Folder to open a preferences file), but it makes it easy for you should you ever want to take a look at the contents of the file your program is creating.

The final argument is a script code. A file's script code identifies how the Finder displays the file's name. Here you can use the Apple-defined constant smSystemScript.

With the file created, its resource fork can be opened. This is the same code that was introduced in the earlier discussion on opening a resource file:

	gFileRsrcForkRef = FSpOpenResFile(&prefFSSpec, fsRdWrPerm);

You've already seen how calls to AddResource() and WriteResource() are used to save a resource to a file. Your program will again use these calls to add the default TSTD resource to the newly created preferences file. The complete code for creating a new preferences file appears in the CreateNewPrefFile() function in the PrefFile listing.

PrefFile

This month's program is PrefFile. Running PrefFile results in the appearance of the window shown in Figure 3. As they were for last month's RsrcTemplate program, the contents displayed in the window are read from a TSTD resource. Unlike RsrcTemplate, the data from this resource is read in from an external file -- a preferences file.



Figure 3. The PrefFile window.

The PrefFile program allows the user to change the value of the string and the number that get displayed in the window. The user can also specify whether the string and number are displayed in the window when the program launches. Typical of most Mac programs, this is done in a dialog box that appears when the user chooses Preferences from the Edit menu. While the Preferences item can appear in any menu, it's customary to make this item be the last item in the Edit menu. Figure 4 shows the program's preferences dialog box.



Figure 4. The PrefFile preferences dialog box.

When the user clicks the OK button, the information from the dialog box is stored in the program's preferences file -- it replaces whatever data had been in the one TSTD resource in a file named MyPrefFile in the user's Preferences folder in the System Folder. Changes to the preferences don't affect the program now, but the next time the PrefFile program is started, this new information is used.

Creating the PrefFile Resources

Start the project by creating a new folder named PrefFile in your CodeWarrior development folder. Launch ResEdit, then create a new resource file named PrefFile.rsrc. Make sure to specify the PrefFile folder as the resource file's destination. The resource file will hold resources of the types shown in Figure 5.



Figure 5. The PrefFile resources.

Figure 6 shows the three MENU resources that the PrefFile program uses. After creating the MENU resources, create a MBAR resource that references the ID of each of the three menus.



Figure 6. The MENU resources.

The size and screen placement of the preferences dialog box is defined by a DLOG resource -- in the PrefFile.rsrc file this resource should have an ID of 128. The values you use for these DLOG fields aren't critical. Instead, focus on the corresponding DITL resource. In Figure 7 you see the DITL resource that's used to display the preferences dialog box shown back in Figure 4. When creating this resource, make sure to assign the proper numbers to the enabled items (the two Edit Text boxes, the Check Box, and the Button). These items need to have numbers that match the values you use in the item constants in your code. PrefFile's code defines these dialog item constants:

#define		kOKButton			1
#define		kNameString			2
#define		kScoreString		3
#define		kShowInfoCheck	4



Figure 7. The DITL resource.

A single WIND resource wraps up the interface-related resources. Give this resource an ID of 128 and you're all set -- the size and placement of the window aren't significant.

You'll need to include a single template resource and one custom resource. There's no need to go into detail about these resources -- we're using the same TMPL and TSTD resources that we covered in detail in last month's Getting Started column. Look back at Figures 1 and 2 in this article to get another look at both resources. Note that whatever values you use for the data in the TSTD resource will be used in the preferences file as default values should the preferences file ever need to be re-created. Back in Figure 2 you see that the number 0 and the string "Winner" are in the TSTD resource, and in Figure 3 you see that the score and name displayed in the PrefFile program match this data.

Creating the PrefFile Project

Start CodeWarrior and choose New Project from the File menu. Use the MacOS:C_C++:MacOS Toolbox:MacOS Toolbox Multi-Target project stationary for the new project. You've already created a project folder, so uncheck the Create Folder check box before clicking the OK button. Name the project PrefFile.mcp, and make sure the project's destination is the PrefFile folder.

Add the PrefFile.rsrc resource_file to the new project. Now remove the SillyBalls.rsrc file. The project doesn't require any of the standard ANSI libraries, so go ahead and remove the ANSI Libraries folder from the project window if you want.

Choose New from the File menu to create a new source code window. Save the new window, giving it the name PrefFile.c. Next, choose Add Window from the Project menu to add this empty file to the project. Now remove the SillyBalls.c placeholder file from the project window. Now you're ready to type in the source code.

To save yourself quite a bit of typing, go to from MacTech's ftp site at ftp://ftp.mactech.com/src/mactech/volume15_1999/15.07.sit. There you'll find the PrefFile source code file available for downloading.

Walking Through the Source Code

The PrefFile listing begins with a host of constant definitions -- most of which are resource-related. One constant is worthy of note -- kPrefFileName. When it comes time for the program to open its preferences file, it will expect that this file be named MyPrefFile.

/********************* constants *********************/

#define		kDLOGResID			128
#define		kOKButton			1
#define		kNameString			2
#define		kScoreString		3
#define		kShowInfoCheck	4

#define		kWINDResID			128
#define		kTSTDResID			128
#define		kResTypeTSTD		'TSTD'

#define		kWINDResID			128
#define		kMBARResID			128
#define		kALRTResID			128
#define		kPrefFileName		"\pMyPrefFile"

#define		kSleep					7
#define		kMoveToFront		(WindowPtr)-1L

#define		mApple					128
#define		iAbout					1

#define		mFile					129
#define		iQuit					1

#define		mEdit					130
#define		iUndo					1
#define		iCut						3
#define		iCopy					4
#define		iPaste					5
#define		iClear					6
#define		iPreferences		8

So that the program knows the format of our custom TSTD resource, we define a data structure that includes fields that match the order and data type of each item in the custom TSTD resource. This same data structure was introduced in last month's Getting Started article.

/******************* data structures *****************/

typedef struct
{	
	short		write;
	long			score;
	Str255		name;
} TemplateRecord, *TemplatePtr, **TemplateHandle;

PrefFile declares six global variables. The first three come directly from last month's RsrcTemplate program: gWriteScoreInfo tells the program whether it should write the TSTD resource score and name values to a window, and the gHighScore and gName variables hold those two values. The gApplRsrcForkRef and gFileRsrcForkRef are used to keep track of which resource fork is to be used (since it's possible for a program to keep both the application resource fork and a preferences file resource fork open at the same time). The Boolean gDone signals the program when it's time to quit.

/****************** global variables *****************/

Boolean 		gWriteScoreInfo = false;
long	 			gHighScore;
Str255			gName;
short			gApplRsrcForkRef;
short			gFileRsrcForkRef = 0;
Boolean		gDone;

Next come the program's function prototypes.

/********************* functions *********************/

void		ToolBoxInit( void );
void		MenuBarInit( void );
void		WriteValuesToWindow( void );
void		OpenPrefFile( void );
void		CreateNewPrefFile( FSSpec pref_FSSpec );
void		GetPrefValues( void );
void		SetPrefValues( void );
void		OpenPrefDialog( void );
void		EventLoop( void );
void		DoEvent( EventRecord *eventPtr );
void		HandleMouseDown( EventRecord *eventPtr );
void		HandleMenuChoice( long menuChoice );
void		HandleAppleChoice( short item );
void		HandleFileChoice( short item );
void		HandleEditChoice( short item );
void		DoError( Str255 errorString );

The main() function begins by initializing the Toolbox and the menu bar. Then a reference number for the application resource fork is obtained for later use by the program. Next, a window is opened for the (possible) display of the preferences values. A call to the application-defined GetPrefValues() is made in order to load to memory the data from the preferences file's TSTD resource. Next, the value of gWriteScoreInfo (which was determined in GetPrefValues()) is checked to determine if the remaining TSTD data should be written to the window. If writing should take place, we delegate that work to the application-defined function WriteValuesToWindow() -- a routine we lifted from last month's program. After that the program enters an event loop.

/********************** main *************************/

void		main( void )
{  
	WindowPtr	window;

	ToolBoxInit();
	MenuBarInit();

	gApplRsrcForkRef = CurResFile();
  
	window = GetNewWindow( kWINDResID, nil, (WindowPtr)-1L );
	SetPort( window );
  
	GetPrefValues();

	if ( gWriteScoreInfo == true )
		WriteValuesToWindow();
  
	EventLoop();
}

ToolBoxInit() and MenuBarInit() are the same as prior versions.

/******************** ToolBoxInit ********************/

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

/******************** MenuBarInit ********************/

void		MenuBarInit( void )
{
	Handle				menuBar;
	MenuHandle		menu;
	
	menuBar = GetNewMBar( kMBARResID );
	SetMenuBar( menuBar );

	menu = GetMenuHandle( mApple );
	AppendResMenu( menu, 'DRVR' );
	
	DrawMenuBar();
}

After GetPrefValues() executes (we'll get to that routine just ahead), the gHighScore variable holds the value that was stored in the score item in the TSTD resource, and the gName variable holds the string that was stored in the name item in that same resource. The WriteValuesToWindow() routine is invoked from main() to write these two values to the program's window.

/************** WriteValuesToWindow ******************/

void		WriteValuesToWindow( void )
{
	Str255	tempStr;

	MoveTo( 20, 20 );
	NumToString( gHighScore, tempStr );
	DrawString( tempStr );

	MoveTo( 20, 40 );
	DrawString( gName );
}

The application-defined function OpenPrefFile() is called to, yes, open the preferences file. Actually, OpenPrefFile() opens just the resource fork of this file. That's fine and dandy, though, because it's in this fork that all the preferences data is stored. The code that makes up this function was discussed earlier in this article. And, if much of it looks very familiar, you've probably got the May Getting Started ResFiles example on your mind -- OpenPrefFile() is similar to the ResFiles function OpenResourceFork().

/******************** OpenPrefFile ******************/

void		OpenPrefFile( void )
{
	short		volRef;
	long			dirID;
	FSSpec		prefFSSpec;
  
	FindFolder( kOnSystemDisk, kPreferencesFolderType,
						 kDontCreateFolder, &volRef, &dirID );
            
	FSMakeFSSpec( volRef, dirID, kPrefFileName, &prefFSSpec );

	gFileRsrcForkRef = FSpOpenResFile(&prefFSSpec, fsRdWrPerm);

	if ( gFileRsrcForkRef == -1 )
		CreateNewPrefFile( prefFSSpec );

	UseResFile( gFileRsrcForkRef );  
}

If OpenPrefFile() fails to find the specified file, it calls CreateNewPrefFile() to create a new preferences file. Most of the code found in CreateNewPrefFile() has been described earlier in this article -- you'll want to especially take note of the Creating a New Preferences File section.

/**************** CreateNewPrefFile *****************/

void		CreateNewPrefFile( FSSpec prefFSSpec )
{
	Handle			handle;  
	Short			resID;
	ResType		resType;
	Str255			resName;
   
	UseResFile( gApplRsrcForkRef );
  
	handle = Get1Resource( kResTypeTSTD, kTSTDResID );

	GetResInfo( handle, &resID, &resType, resName );  
	DetachResource( handle );

	FSpCreateResFile( &prefFSSpec, 'RSED', 
									'rsrc', smSystemScript );
	gFileRsrcForkRef = FSpOpenResFile(&prefFSSpec, fsRdWrPerm);
	UseResFile( gFileRsrcForkRef );
  
	AddResource( handle, resType, resID, resName );
	ChangedResource( handle );
	WriteResource( handle );  
	ReleaseResource( handle );
}

At startup, the PrefFile program calls GetPrefValues() to open the preferences file and to extract the user preferences from that file. GetPrefValues() calls the just-discussed OpenPrefFile() to open the file, then goes on to call Get1Resource() to load to memory the data from the custom TSTD resource.

/******************* GetPrefValues *******************/

void		GetPrefValues( void )
{
	short			write; 
	Handle			dataHandle;
	StringPtr	sourceStr;
	Size				bytes;

	OpenPrefFile();
	  
	dataHandle = Get1Resource( kResTypeTSTD, kTSTDResID );

Next, global variables are assigned values based on the resource data which is now in memory. The code to do that comes from last month's RsrcTemplate program. With the global variables assigned values, there's no longer a need for the preferences file to be open -- so we call CloseResFile() to close it.

	write = (**(TemplateHandle)dataHandle).write;
	if ( write == 0 )
		gWriteScoreInfo = false;
	else
		gWriteScoreInfo = true;

	gHighScore = (**(TemplateHandle)dataHandle).score;
  
	sourceStr = (**(TemplateHandle)dataHandle).name;
	bytes = (**(TemplateHandle)dataHandle).name[0] + 1;
	BlockMoveData( sourceStr, gName, bytes );

	CloseResFile( gFileRsrcForkRef );

	UseResFile( gApplRsrcForkRef );  
}

The entering of new preferences values is performed by the user through the use of a dialog box brought on by choosing Preferences from the Edit menu. Before looking at the code that implements that dialog box, let's see how the writing of a resource is the inverse of reading one. You've just seen the code for GetPrefValues() -- now here's the code for SetPrefValues(). Take a moment to compare the two routines.

/******************* SetPrefValues *********************/

void		SetPrefValues( void )
{
	Handle			oldDataHandle;
	Handle			newDataHandle;
	Short			resID;
	ResType		resType;
	Str255			resName;
	short			write;
	Size				bytes;
   
	OpenPrefFile();

	newDataHandle = NewHandleClear( sizeof( TemplateRecord ) );
	HLock( newDataHandle );
  
	if ( gWriteScoreInfo == true )
		write = 1;
	else
		write = 0;
	(**(TemplateHandle)newDataHandle).write = write;

	(**(TemplateHandle)newDataHandle).score = gHighScore;
 
	bytes = gName[0] + 1;
	BlockMoveData( gName, 
					 (**(TemplateHandle)newDataHandle).name, bytes );

	oldDataHandle = Get1Resource( kResTypeTSTD, kTSTDResID );
  
	GetResInfo( oldDataHandle, &resID, &resType, resName); 	
  
	RemoveResource( oldDataHandle );
	AddResource( newDataHandle, resType, resID, resName );
	WriteResource( newDataHandle );

	HUnlock( newDataHandle );

	ReleaseResource( newDataHandle );

	CloseResFile( gFileRsrcForkRef );

	UseResFile( gApplRsrcForkRef );  
}

When the user chooses the Preferences menu item, OpenPrefDialog() is invoked. This is a fairly long routine, but there's nothing too tricky about it. OpenPrefDialog() begins with the declaration of a number of local variables, and then a call to GetNewDialog().

/****************** OpenPrefDialog *******************/

void		OpenPrefDialog( void )
{
	DialogPtr	dialog;
	Boolean		done = false;
	short			oldValue;
	short			item;
	short			type;
	Handle			handle;
	Rect				rect;
	Str255			scoreStr;
  
	dialog = GetNewDialog( kDLOGResID, nil, (WindowPtr)-1L );

	GetDialogItem( dialog, kNameString, &type, &handle, &rect);

Before displaying the dialog box (shown back in Figure 4) on screen, we'll fill in the two edit boxes and set the state of the check box. At program startup we saved the preferences values to global variables, so here we can use those values -- there's no need to again open the preferences file and extract the custom resource data.

	SetDialogItemText( handle, gName );

	NumToString( gHighScore, scoreStr );
	GetDialogItem(dialog, kScoreString, &type, &handle, &rect);
	SetDialogItemText( handle, scoreStr );

	GetDialogItem( dialog, kShowInfoCheck, &type, 
								&handle, &rect );  
	if ( gWriteScoreInfo == true )
		SetControlValue( (ControlHandle)handle, 1 ); 
	else
		SetControlValue( (ControlHandle)handle, 0 ); 

	ShowWindow( dialog );
	SetPort( dialog );

Until the user clicks on the dialog box OK button, a while loop watches the user's actions. If the check box is clicked on, its state is toggled and the value of the global variable gWriteScoreInfo is adjusted. The text that's typed in either of the edit boxes isn't of concern until the user does click the OK button. Only at that time do we bother to read the string from each of these two edit boxes.

	while ( done == false )
	{
		ModalDialog( nil, &item );
     
		switch ( item )
		{
			case kShowInfoCheck:
				GetDialogItem( dialog, kShowInfoCheck, &type, 
											&handle, &rect );  
				oldValue = GetControlValue( (ControlHandle)handle ); 
				if ( oldValue == 1 )
				{
					SetControlValue( (ControlHandle)handle, 0 ); 
					gWriteScoreInfo = false;
				}
				else
				{
					SetControlValue( (ControlHandle)handle, 1 ); 
					gWriteScoreInfo = true;
				}
				break;

			case kOKButton:      
				GetDialogItem( dialog, kNameString, &type, 
											&handle, &rect );
				GetDialogItemText( handle, gName );

				GetDialogItem( dialog, kScoreString, &type, 
											&handle, &rect );
				GetDialogItemText( handle, scoreStr );
				StringToNum( scoreStr, &gHighScore );

				done = true;
				break;
		}   
	}

After the OK button is clicked the dialog box is dismissed, and the new user preferences are saved to the preferences file. A call to the previously described SetPrefValues() function takes care of the work of opening the preferences file and of saving the new values to a TSTD resource in that file. A call to DisposeDialog() frees the memory that had been reserved for the dialog box.

	SetPrefValues();
  
	DisposeDialog( dialog ); 
}

As is true of most of our examples, the PrefFile program is event driven -- so the remaining event-handling code should look quite familiar. EventLoop() is called from main() -- its purpose is to repeatedly grab an event and pass it to DoEvent(). DoEvent() determines the type of the event, and calls the routine appropriate to handling the event. If the event involves a menu item selection, then HandleMenuChoice() calls the appropriate menu-handling routine. In PrefFile our chief concern is the display of the preferences dialog box. That dialog box is posted by OpenPrefDialog() -- a function invoked from HandleEditChoice().

/******************** EventLoop **********************/

void		EventLoop( void )
{		
	EventRecord		event;

	gDone = false;
	while ( gDone == false )
	{
		if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) )
			DoEvent( &event );
	}
}

/*********************** 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;
		case updateEvt:
			BeginUpdate( (WindowPtr)(eventPtr->message) );
			EndUpdate( (WindowPtr)(eventPtr->message) );
			break;
	}
}

/****************** 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;
	}
}

/****************** 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 mEdit:
				HandleEditChoice( item );
				break;
		}
		HiliteMenu( 0 );
	}
}

/***************** HandleAppleChoice *****************/

void		HandleAppleChoice( short item )
{
	MenuHandle		appleMenu;
	Str255				accName;
	short				accNumber;
	
	switch ( item )
	{
		case iAbout:
			SysBeep( 10 );
			break;
		default:
			appleMenu = GetMenuHandle( mApple );
			GetMenuItemText( appleMenu, item, accName );
			accNumber = OpenDeskAcc( accName );
			break;
	}
}

/***************** HandleEditChoice ******************/

void		HandleEditChoice( short item )
{
	switch ( item )
	{
		case iPreferences:
			OpenPrefDialog();
			break;
	}
}

/***************** HandleFileChoice ******************/

void		HandleFileChoice( short item )
{
	switch ( item )
	{
		case iQuit:
			gDone = true;
			break;
	}
}

/********************** DoError **********************/

void		DoError( Str255 errorString )
{
	ParamText( errorString, "\p", "\p", "\p" );
	
	StopAlert( kALRTResID, nil );
	
	ExitToShell();
}

Running PrefFile

Run PrefFile by selecting Run from CodeWarrior's Project menu. After compiling the code and building a program, CodeWarrior runs the program. A small window appears and, based on the first value stored in the preferences file, other preferences data is or isn't drawn in this window. Choose Preferences from the Edit menu to see the preferences-setting dialog box. Make some changes here, then dismiss the dialog box. Your changes won't be noticeable now. But the next time you run PrefFile, the changes will be in effect (hint, hint: quit PrefFile and rerun the program)!

Till Next Month...

The PrefFile program makes use of a very simple preferences file. Your real-world application will no doubt require a more sophisticated custom resource in which your program's settings are stored. Now that you know the basics of creating a new resource file, and of creating, reading, and writing custom resource data, you're all set to implement such a preferences file. To make sure you understand the many concepts covered in the last few articles, start out slowly. For instance, try modifying the TSTD template to include just one more field. Then edit the TSTD resource to include a value for the new field. Now modify the PrefFile code appropriately -- you'll need to add a corresponding field to the definition of the program's one struct. You'll also want to add to the GetPrefValues() and SetPrefValues() functions so that these routines properly read in, and write to, the preferences file. Modifying this month's project should keep you busy until next month when we visit a completely new topic...

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniGraffle Pro 6.1.4 - Create diagrams,...
OmniGraffle Pro helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use... Read more
OmniGraffle 6.1.4 - Create diagrams, flo...
OmniGraffle helps you draw beautiful diagrams, family trees, flow charts, org charts, layouts, and (mathematically speaking) any other directed or non-directed graphs. We've had people use Graffle to... Read more
MegaSeg 5.9.5 - Professional MP3 DJ appl...
MegaSeg is a complete solution for pro audio/video DJ mixing, radio automation, and music scheduling with rock-solid performance and an easy-to-use design. Mix with visual waveforms and Magic... Read more
MarsEdit 3.6.8 - Quick and convenient bl...
MarsEdit is a blog editor for OS X that makes editing your blog like writing email, with spell-checking, drafts, multiple windows, and even AppleScript support. It works with with most blog services... Read more
BBEdit 11.0.3 - Powerful text and HTML e...
BBEdit is the leading professional HTML and text editor for the Mac. Specifically crafted in response to the needs of Web authors and software developers, this award-winning product provides a... Read more
Microsoft Office Preview 15.8 - Popular...
Welcome to the new and modern Microsoft Office for Mac. You will receive regular updates automatically until the official release in the second half of 2015. With the redesigned Ribbon and your... Read more
Yosemite Cache Cleaner 9.0.5 - Clear cac...
Yosemite Cache Cleaner is an award-winning general purpose tool for OS X. YCC makes system maintenance simple with an easy point-and-click interface to many OS X functions. Novice and expert users... Read more
ExpanDrive 4.3.2 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
RapidWeaver 6.0.8 - Create template-base...
RapidWeaver is a next-generation Web design application to help you easily create professional-looking Web sites in minutes. No knowledge of complex code is required, RapidWeaver will take care of... Read more
Artlantis Studio 5.1.2.7 - 3D rendering...
Artlantis Studio is a unique and ideal tool for performing very high resolution rendering easily and in real time. The new FastRadiosity engine now lets you compute images in radiosity-even in... Read more

Bored? MyLeisure FreeTime Maximizer Will...
Bored? MyLeisure FreeTime Maximizer Will Take Care of That! Posted by Jessica Fisher on March 5th, 2015 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
New Publisher Allstar Games Heads West w...
Allstar Games has announced its first mobile title designed for western audiences, Allstar Heroes. The game will be a massive online battle arena (MOBA) that offers dozens of heroes for you to collect and pit against your opponents. As each hero has... | Read more »
RAD Boarding Review
RAD Boarding Review By Jennifer Allen on March 5th, 2015 Our Rating: :: NEARLY RADUniversal App - Designed for iPhone and iPad RAD Boarding isn’t quite one of the greats, but it has potential.   | Read more »
Presenting the International Mobile Gami...
11th Annual International Mobile Gaming Awards ceremony, hosted by actress Allison Haislip, gathered mobile game developers and publishers from around the world. They chose 13 winners out of the 93 nominations. British studio USTWO won the the Grand... | Read more »
AG Drive Review
AG Drive Review By Tre Lawrence on March 5th, 2015 Our Rating: :: FUTURISTIC STREET RACING.Universal App - Designed for iPhone and iPad Futuristic racing… interstellar style.   | Read more »
GDC 2015 – Nightmare Guardians is an Int...
GDC 2015 – Nightmare Guardians is an Interesting Hybrid of MOBA and Lane Defense Posted by Rob Rich on March 5th, 2015 [ permalink ] I have to say that lane defense (i.e. | Read more »
Overkill 3 Review
Overkill 3 Review By Tre Lawrence on March 5th, 2015 Our Rating: :: WHO'S NEXT?Universal App - Designed for iPhone and iPad Cover system gameplay in the third-person.   Developer: Craneballs Price: Free Version Reviewed: 1.1.6... | Read more »
Warner Bros. Interactive Entertainment A...
Warner Bros. has some exciting games coming down the pipe! | Read more »
GDC 2015 – Star Trek Timelines will Prob...
GDC 2015 – Star Trek Timelines will Probably Make Your Inner Trekkie Squeal With Glee Posted by Rob Rich on March 4th, 2015 [ permalink ] Any popular fictional universe has its fair share of fan fiction – where belo | Read more »
Protect Yourself from an Onslaught of Ca...
Surprise Attack Games has announced a Cat-astrophic new physics puzzler called Fort Meow! In the game, a young girl named Nia finds her grandfather’s journal which triggers an all mighty feline attack! Why do the cats want the journal? Who knows,... | Read more »

Price Scanner via MacPrices.net

Apple restocks refurbished 15-inch Retina Mac...
The Apple Store has restocked Apple Certified Refurbished 2014 15″ Retina MacBook Pros, available for up to $400 off the cost of new models. An Apple one-year warranty is included with each model,... Read more
Roundup of MacBook Air sale prices, models up...
B&H Photo has MacBook Airs on sale for up to $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 128GB MacBook Air: $799 100 off MSRP - 11″ 256GB MacBook Air: $999 $100... Read more
New Firstrade Mobile App Enables On-The-Go Tr...
Firstrade Securities Inc. has announced its new mobile app, which gives investors immediate access to the company’s trading platform on all mobile devices. The app was developed in-house and was... Read more
Sonnet Introduces USB 3.0 + eSATA Thunderbolt...
Sonnet has announced the launch of its new USB 3.0 + eSATA Thunderbolt Adapter for easy connectivity to USB 3.0 devices and eSATA storage, and USB 3.0 + Gigabit Ethernet Thunderbolt Adapter for easy... Read more
Apple restocks refurbished 27-inch 5K iMacs f...
The Apple Store has restocked Apple Certified Refurbished 27″ 3.5GHz 5K iMacs for $2119 including free shipping. Their price is $380 off the cost of new models, and it’s the lowest price available... Read more
Free Clean Reader Mobile App Hides Swear Word...
The new Clean Reader app, now available in the Apple App Store and Google Play, delivers the opportunity of reading any book without being exposed to profanity. By selecting how clean they want their... Read more
Kinsa Launches “Groups” App to Monitor Illnes...
Kinsa, makers of the first FDA approved app-enabled smartphone thermometer thst won the 2013 Cleveland Clinic Medical Innovation Grand Prize and recently appeared in Apple’s “Parenthood” TV... Read more
iPad: A More Positive Outlook – The ‘Book Mys...
It’s good to hear someone saying positive things about the iPad. I’ve been trying to bend my mind around how Apple’s tablet could have gone from zero to bestselling personal computing device on the... Read more
Mac Pros on sale for up to $279 off MSRP
Amazon has Mac Pros in stock and on sale for up to $279 off MSRP. Shipping is free: - 4-Core Mac Pro: $2725.87, $273 off MSRP (9%) - 6-Core Mac Pro: $3719.99, $279 off MSRP (7%) Read more
Sale! 13-inch Retina MacBook Pros for up to $...
B&H Photo has 13″ Retina MacBook Pros on sale for up to $205 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.6GHz/128GB Retina MacBook Pro: $1219.99 save $80 - 13″ 2.... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.