Volume Number: 16 (2000)
Issue Number: 5
Column Tag: Getting Started

Opening a Picture File

By Dan Parks Sydow

How a program opens a picture file and displays that file's contents in a window

In last month's Getting Started article we examined the details of how a program opens an existing text file, associates that file's text with a window, and then displays the text in that window. Doing this involves locating the file to open on disk, opening the file, reading the file's text to memory, maintaining a handle to the text in memory, and then binding that handle to a window. That same article stated that many of these techniques are applicable to files that hold data other than text. This month, we prove our case by substituting "picture" for "text." Last month you saw how your Mac program can create windows that keep track of text. Here you read the details of how your Mac program can create windows that keep track of graphics.

Windows and File Data Review

Last month in Getting Started you read about a scheme for associating a file's contents with a specific window. There we employed the use of an application-defined document record data type:

typedef  struct 
{
   TEHandle   windText;
   
} WindData, *WindDataPtr, **WindDataHandle;

The field or fields of the data structure can be of types of your choosing. For instance, we could just as easily define the WindData structure as a structure that holds a handle to a picture rather than a handle to editable text:

typedef  struct 
{
   PicHandle   windPict;
   
} WindData, *WindDataPtr, **WindDataHandle;

A new structure of this data type is easily created with a call to NewHandleClear().

WindDataHandle	theData;

theData = (WindDataHandle)NewHandleClear( sizeof(WindData) );   

Next, a window is opened. Then the application-defined data structure is associated with the new window by storing a handle to the data structure in the window's refCon field:

WindowPtr	theWindow;

theWindow = GetNewWindow( 128, nil, (WindowPtr)-1L );

SetWRefCon( theWindow, (long)theData );

At this point we've created an empty data structure and associated it with a window. Next we need to open an existing text file. A call to the Toolbox function StandardGetFilePreview()displays the standard open file dialog box for the user.

SFTypeList				typeList = { 'PICT', 0, 0, 0 };
StandardFileReply	reply;

StandardGetFilePreview( nil, 1, typeList, &reply );

The first argument can be a pointer to a filter function that assists in determining which file types should be displayed in the open dialog box file list. A value of nil is used if no such application-defined routine exists. The second argument to StandardGetFilePreview() passes the number of file types to be displayed. Pass 1 if your program only works with one file type. The third argument is of type SFTypeList. The SFTypeList variable is a list that specifies the four-character file type (surrounded in single quotes) of each of the types of files your program can work with. Fill the list with four values, using a 0 for each unused file type. Last month's example worked with text files, so then we used 'TEXT' as the one non-zero element in the SFTypeList. This month we'll be working with picture files, so instead use 'PICT' in this list. The last argument should be a pointer to a variable of type StandardFileReply. When the user dismisses the open dialog box, the members of this structure variable will get filled information (such as how the dialog box was dismissed and the disk location of the selected file (if the dialog box wasn't dismissed by a click on the Cancel button).

If the user dismissed the dialog box by clicking the Open button (or by double-clicking on a file name in the dialog box file list), the sfGood field of the StandardFileReply variable will have a value of true and the program can proceed to open the selected file. That's accomplished by calling FSpOpenDF():

short	fileRefNum;

FSpOpenDF( &reply.sfFile, fsRdPerm, &fileRefNum );

The first argument to FSpOpenDF() is the file system specification for the selected file. FSpOpenDF() opens this file's data fork, using the permission level specified in the second argument (with fsRdPerm representing read-only permission). After opening the file, FSpOpenDF() returns a file reference number. This number is then used by your program to reference the now open file.

Bringing a File's Picture Into Memory

After a picture file is open, your program needs to bring most of the file's data into memory. Note the word "most" in the previous sentence. Any file of type 'PICT' has a 512-byte header that can be used as the file-creating application sees fit. That means this first half K of data is always unrelated to the data that comprises the picture itself. Last month we used the Toolbox function GetEOF() to get a text file's size in bytes. Here we use the same function to get a picture file's size in bytes. The fileRefNum variable is the file reference number previously returned to the program by a call to FSpOpenDF().

long		fileLength;

GetEOF( fileRefNum, &fileLength );

SetFPos() is now called to move the file mark-the position marker used to keep track of the current position to read from or write to-512 bytes into the file. The fsFromStart constant tells SetFPos() to begin its byte count at the start of the file, while the 512 value tells the function to count that many bytes into the file.

SetFPos( fileRefNum, fsFromStart, 512 );

Now we need to create a memory buffer in which the contents of the selected file will be read to. To accomplish this for a text file we jumped right in with a call to NewPtr(). For a picture file we need to first make an adjustment to account for the fact that we're reading in less than the entire file (we're skipping the header portion). After that we create a new handle rather than a pointer. Recall that text that is to be made editable is read into a buffer referenced by a pointer, and then that pointer is used in a call to TESetText() to copy the text to memory referenced by a handle. A picture is read into memory referenced by a handle, and no similar kind of manipulation is needed.

Size			pictSize;
Handle		pictureBuffer;

pictSize = fileLength - 512;

pictureBuffer = NewHandleClear( pictSize );

At this point we have an area set aside in memory. That area is the size in bytes of the picture data in a picture file, and the memory area is referenced by a handle. It's now time to read the file's contents, storing the file data in the block of memory referenced by the pictureBuffer handle. Because FSRead() expects a pointer to a memory buffer, we need to dereference the handle one time (to get to the pointer that the handle references).

FSRead( fileRefNum, &pictSize, *pictureBuffer );

The call to FSRead() reads in the picture data, and that data is referenced by a generic handle named pictureBuffer. However, it will be as a PicHandle in the application-defined window data structure that we store the reference to the picture, so we want to convert this generic handle to the more specific PicHandle. A simple type cast does the trick.

PicHandle		pictureHandle;

pictureHandle = ( PicHandle )pictureBuffer;

At this point the program has a PicHandle that it can use as it might any other picture handle. For instance, a call to DrawPicture() could be made to draw the picture to a window (assuming a destination rectangle is set up and a window is open and its port is set). Alternatively, this PicHandle could be stored in the windPict field of an application-defined WindData window document record.

Associating a File's Contents With a Window

With a file's picture that has been copied to memory we need to associate that picture with one window-just as we did last month with a file's text that was copied to memory. With the picture data stored in memory, and a PicHandle referencing that memory, we're just about there. Our application-defined WindData structure defines a single field-the windPict field of type PicHandle. Earlier you saw how to create a new, empty WindData structure and how to use a window's refCon field to associate that structure with the window:

WindDataHandle	theData;
WindowPtr			theWindow;

theData = (WindDataHandle)NewHandleClear( sizeof(WindData) );   

theWindow = GetNewWindow( 128, nil, (WindowPtr)-1L );

SetWRefCon( theWindow, (long)theData );

To create a tie between the handle that references the file's contents in memory (pictureHandle) and the handle that is a part of the application-defined data structure in memory (windPict), we dereference the data structure handle twice to allow access to the structure member windPict. The windPict member is of type PicHandle, as is the pictureHandle variable - so one variable value can be assigned to the other variable. After the following line of code executes windPict references the same block of memory as pictureHandle.

(**theData).windPict = pictureHandle;

When our program needs to access a window's additional data (here, a picture - but we could have plenty of other data in our WindData data structure such as more than one picture and text) it now has a simple means of doing so. From the use of SetWRefCon(), a window's refCon field holds a reference to the associated data structure - a call to GetWRefCon retrieves the reference:

long		windRefCon;

windRefCon = GetWRefCon( theWindow );

Here the variable windRefCon holds a value that is a handle to the window's WindData structure. The refCon field is of type long, while WindData is of our application-defined type WindDataHandle. A typecast makes the proper conversion:

WindDataHandle	theData;

theData = (WindDataHandle)windRefCon;

To access the field of the WindData structure we double-dereference the handle that references the structure. Then the value in the structure's field can be assigned to a local variable and used as the program sees fit.

PicHandle		pictureHandle;

pictureHandle = (**theData).windPict;

The primary use a program has for a PicHandle is in drawing the picture the handle references. The bounding rectangle of the picture is held in the picFrame field of the picture structure that the PicHandle references. We can extract the width and height of the picture from this bounding rectangle:

Rect		pictRect;
short	pictWidth;
short	pictHeight;

pictRect = (**pictureHandle).picFrame;
pictWidth = pictRect.right - pictRect.left;
pictHeight = pictRect.bottom - pictRect.top;

From the picture dimensions we can then do something such as resize the associated window to match the size of the picture (assuming we want the picture to be the only thing displayed in the window).

SizeWindow( theWindow, pictWidth, pictHeight, false );

And, of course we can offset the picture's rectangle so that the drawing of the picture starts in the upper-left corner of the window, and then draw the picture to the window:

SetRect( &pictRect, 0, 0, pictWidth, pictHeight );
DrawPicture( pictureHandle, &pictRect );

OpenPictureFile

This month's program is OpenPictureFile. When you run OpenPictureFile you'll be presented with the dialog box pictured in Figure 1.

Figure 1. The OpenPictureFile dialog box with the preview section expanded.

When you click on a picture file in the dialog box file list (move to any drive and folder to find a suitable type 'PICT' file) you'll see a thumbnail image of that file's picture displayed under the Preview heading at the left side of the open file dialog box - as shown in Figure 2. Even though the file is a picture, the dialog box will place a small QuickTime-style control under the preview image. If you uncheck the Show Preview checkbox the dialog box will collapse and the preview information will disappear (see Figure 3).

Figure 2. The OpenPictureFile dialog box with the preview section collapsed.

When you select a picture file and click the Open button (or double-click on the file name in the list), the open file dialog box is dismissed and a new window holding the contents of the selected picture file appears - as shown in Figure 3.

Figure 3. The OpenPictureFile program displaying the contents of a picture file.

Notice that the window is sized to match the size of the picture - the program handles resizing of the window. When finished, click the mouse button to end the program.

Creating the OpenPictureFile Resources

Begin your development of the OpenPictureFile project by creating a new folder named OpenPictureFile in your main CodeWarrior folder. Start up ResEdit and create a new resource file named OpenPictureFile.rsrc. Specify that the OpenPictureFile folder serve as the resource file's destination. The OpenPictureFile.rsrc file will hold three resources-two of which you've created in previous examples. Together, ALRT 128 and DITL 128 define the program's error-handling alert. If the OpenPictureFile program runs into a serious problem while executing, then this alert appears and the program terminates. Figure 4 shows the three types of resources that this project requires.

Figure 4. The OpenPictureFile resources.

The remaining one resource is a WIND resource with an ID of 128. Neither the placement, size, or type of this window is critical. The program ends with a click of the mouse button, so the window doesn't require a close box. And the program will resize the window to match the size of the picture contained in a selected picture file, so pick an arbitrary initial size for the window. You may want to mark the window as initially hidden so that the program's resizing of the window isn't visible to the user.

After creating these three resources, save and close the resource file and get ready to start in on the project file.

Creating the OpenPictureFile Project

Create a new project by launching CodeWarrior and then choosing New Project from the File menu. Use the MacOS:C_C++:MacOS Toolbox:MacOS Toolbox Multi-Target project stationary for the new project. Uncheck the Create Folder check box, then click the OK button. Give the project the name OpenPictureFile.mcp and choose the existing OpenPictureFile folder as the project's destination.

Add the OpenPictureFile.rsrc resource file to the project and then remove the SillyBalls.rsrc file. If you want, go ahead and remove the ANSI Libraries folder-this project won't be making use of any ANSI C libraries. Now create a new source code window by choosing New from the File menu.. Save the window, giving it the name OpenPictureFile.c. To add the new source code file to the project, choose Add Window from the Project menu. Remove the SillyBalls.c placeholder file from the project window. Now you're all set to type in the source code.

If you want to save yourself a little typing, log on to the Internet and visit MacTech's ftp site at ftp://ftp.mactech.com/src/. There you'll find the OpenPictureFile source code file available for downloading.

Walking Through the Source Code

OpenPictureFile starts with the definition of a couple of constants. The constant kALRTResID holds the ID of the ALRT resource used to define the error-handling alert. kWINDResID holds the ID of the WIND resource used to define the window that's to hold the picture that's stored in a user-selected picture file.

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

#define		kALRTResID						128 
#define		kWINDResID						128

Next we define our own data structure-the WindData structure that holds data (in this case a reference to a picture in memory) that's to eventually be paired with a window.

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

typedef  struct 
{
   PicHandle   windPict;
   
} WindData, *WindDataPtr, **WindDataHandle;

We'll use a global variable to keep track of the one window that the program opens. If you modify this program to give it the capability to open more than one window at a time, then gPictureWindow can be used to point to the active (frontmost) window.

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

WindowPtr  gPictureWindow;

Next come the program's function prototypes.

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

void		ToolBoxInit( void );
void		OpenExistingPictureFile( void );
void		SizePictureWindow( void );
void		UpdatePictureWindow( void );
void		DoError( Str255 errorString );

The main() function of OpenPictureFile begins with the initialization of the Toolbox. Then the application-defined function OpenExistingPictureFile() gives the user the opportunity to open - you guessed it - an existing picture file. Before displaying the file's picture in the window, we call the Toolbox function ShowWindow()to display the previously hidden window. The application-defined function UpdatePictureWindow() is responsible for refreshing the window's contents. A while loop waits for a click of the mouse button and serves as our program's means of delaying its own termination. When that click occurs main(), and the program, ends.

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

void		main( void )
{ 
	ToolBoxInit();
      
	OpenExistingPictureFile();

	SizePictureWindow();
	
	ShowWindow( gPictureWindow );

	UpdatePictureWindow();
      
	while ( !Button() )
		;
}

The Toolbox initialization function ToolBoxInit() remains the same as previous versions.

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

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

The OpenExistingTextFile() function is responsible for the bulk of the program's work. takes care of most of the tasks discussed in this article. The routine starts with a number of variable declarations.

/************** OpenExistingPictureFile **************/

void		OpenExistingPictureFile( void )
{
	SFTypeList				typeList = { 'PICT', 0, 0, 0 };
	StandardFileReply	reply;
	short						fileRefNum;
	long							fileLength;
	Size							pictSize;
	Handle						pictureBuffer = nil;
	WindDataHandle		theData;
	PicHandle				pictureHandle;

StandardGetFilePreview() is first called to display the standard open file dialog box. After the user dismisses the dialog box (by clicking the Cancel or Open button, or by double-clicking on a picture file name in the dialog box list), the sfGood field of the returned reply variable is examined. If the user canceled, the program calls DoError() to quit.

	StandardGetFilePreview( nil, 1, typeList, &reply );
   
	if ( reply.sfGood == false )
		DoError( "\pError selecting a file." );

If the user didn't cancel, but instead made a selection, a new window is opened. A call to the Toolbox function SetWTitle() sets the window's title bar title to the name of the selected file. After that the window's port is made the current port to ensure that the eventual display of the picture occurs in this new window.

	gPictureWindow = GetNewWindow( kWINDResID, nil, (WindowPtr)-1L);
	if ( gPictureWindow == nil )
		DoError( "\pError attempting to open a new window." );
	
	SetWTitle( gPictureWindow, reply.sfFile.name );

	SetPort( gPictureWindow );

A call to the Toolbox function FSpOpenDF() opens the selected file (if no file was selected the program will have terminated before this point), and calls to GetEOF() and SetFPos() determine the file length in bytes and set the file mark to the appropriate place in the file for reading to start (that is, the 512 byte file header is skipped).

	FSpOpenDF( &reply.sfFile, fsRdPerm, &fileRefNum );

	GetEOF( fileRefNum, &fileLength );
	SetFPos( fileRefNum, fsFromStart, 512 );

The function GetEOF() returns the file's total length. From that we subtract the 512 byte header size to provide the program with the size, in bytes, of the picture data itself.

	pictSize = fileLength - 512;

Now we create a file buffer. The buffer is an area in memory in which we temporarily store a file's picture data. Into this buffer memory we read the contents of the user-selected picture file. After that we set a local PicHandle variable to reference this same area of memory.

	pictureBuffer = NewHandleClear( pictSize );
	
	HLock( pictureBuffer );
		FSRead( fileRefNum, &pictSize, *pictureBuffer );
	HUnlock( pictureBuffer );

	pictureHandle = ( PicHandle )pictureBuffer;

At this point we've got the file's contents stored in memory and referenced by a PicHandle variable. Now we need to create a new structure of the application-defined type WindData and set that structure's windPict field to reference this same area in memory.

	theData = (WindDataHandle)NewHandleClear(sizeof(WindData));   
	(**theData).windPict = pictureHandle;

We finish the routine off by setting the window's refCon field to hold the handle that references the WindData data structure in memory. Later, when we need to access the window information (the picture) for this window we'll be able to readily retrieve it.

	SetWRefCon( gPictureWindow, (long)theData );
}

In this program the main use of the application-defined data structure will be to hold a reference to a picture to draw to a window. There is, however, one other use for the picture-we can also use it to determine the size of the window in which it's to be displayed. Our SizePictureWindow() function does that.

/***************** SizePictureWindow *****************/

void		SizePictureWindow( void )
{
	WindDataHandle	theData;
	long						windRefCon;
	PicHandle			pictureHandle;
	Rect						pictRect;
	short					pictWidth;
	short					pictHeight;

After the declaration of several local variables, SizePictureWindow() makes a call to GetWRefCon() to retrieve the handle to the window's supplemental data. A typecast then coerces this long value to a handle to the WindData data structure.

	windRefCon = GetWRefCon( gPictureWindow );
   
	theData = (WindDataHandle)windRefCon;

To retrieve information from the data structure we double-dereference the data structure handle and then choose the field to access. In our example, the data structure consists of just a single field - the windPict field.

	pictureHandle = (**theData).windPict;

The remainder of the SizePictureWindow() function is devoted to determining the boundaries of the picture (by way of the picture handle's picFrame field), extracting the picture's dimensions from those boundaries, and then resizing the window to match the exact size of the picture.

	pictRect = (**pictureHandle).picFrame;

	pictWidth = pictRect.right - pictRect.left;
	pictHeight = pictRect.bottom - pictRect.top;

	SizeWindow( gPictureWindow, pictWidth, pictHeight, false );
}

The drawing of a picture to a window again involves accessing the data structure associated with that window. UpdatePictureWindow() begins with local variable declarations, and then calls GetWRefCon() to locate the window's accompanying data structure.

/***************** UpdatePictureWindow ******************/

void  UpdatePictureWindow( void )
{
	WindDataHandle	theData;
	long						windRefCon;
	PicHandle			pictureHandle;
	Rect						pictRect;
	short					pictWidth;
	short					pictHeight;

	SetPort( gPictureWindow );

	windRefCon = GetWRefCon( gPictureWindow );

Typecasting provides a reference to the window's data. From that data we retrieve a reference to the picture that's associated with the window.

	theData = (WindDataHandle)windRefCon;
   
	pictureHandle = (**theData).windPict;

Code similar found in the just-discussed function SizePictureWindow() follows. Here again we determine the boundaries, then the dimensions, of the window's picture (so feel free to write a single, common, function that handles this task!). Instead of using this information to resize the window, though, now we use it to draw the picture snuggly in the window.

	pictRect   = (**pictureHandle).picFrame;

	pictWidth  = pictRect.right - pictRect.left;
	pictHeight = pictRect.bottom - pictRect.top;
	SetRect( &pictRect, 0, 0, pictWidth, pictHeight );

	DrawPicture( pictureHandle, &pictRect ); 
}

DoError() should look quite familiar to you-it's the same as previous versions. A call to DoError() results in the posting of an alert that displays an appropriate error message. When the alert is dismissed, the program ends.

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

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

Running OpenPictureFile

Run OpenPictureFile by choosing Run from CodeWarrior's Project menu. After the code is compiled, CodeWarrior launches the OpenPictureFile program and displays the standard open file dialog box. Use this dialog box to select any picture file on your local drives. If you click the Cancel button, the program quits. If you instead select a picture file, that file will be opened and its contents will be displayed in a new window. Note that the window is sized to match the exact size of the picture held in the selected picture file. Clicking the mouse button ends the program.

Till Next Month...

Last month we covered a lot of new material, including the details on how to create an application-defined data structure that can be used to hold data of any type. You read how you can make good use of such a structure by associating it with a window so that the information held in the data structure "belongs" to one particular window. In last month's example code you saw how this data structure can hold the text from an existing text file. This month we worked with a similar structure and a similar scheme to associate the structure and a window. Here, though, we set things up such that our code created a data structure that held a picture from and existing picture file. Together these two examples should provide you with proof that we're on to a very powerful technique. While our examples have focused on data in files, you should be aware of the fact that you can set up your window data structure such that it also (or only) holds other types of data. For instance, here's a structure that keeps track of a string, the text from a text file, a picture from a picture file, and a picture that's stored in a resource:

typedef  struct 
{
	StringPtr	windString;
	TEHandle   windText;
	PicHandle	windPict1;
	PicHandle	windPict2;
   
} WindData, *WindDataPtr, **WindDataHandle;

In the above example you may wonder which picture is derived from the picture file, and which picture comes from a resource. The fact is that you can't tell the source of the picture because the source doesn't matter. In this month's and last month's Getting Started our emphasis has been on extracting data from files so that you'd learn some file-opening and file-reading techniques. But a data structure doesn't care where the data that gets stored in its fields comes from - it just wants its fields to reference valid data in memory! Knowing this, you should be able to combine last month's OpenTextFile code with this month's OpenPictureFile code, and add some data-handling code of your own to create a very powerful program that works with all sorts of information. As you wait for next month's article, go ahead and get started on that project now!