Legacy Document

Inside Macintosh: Files /

Chapter 1 - Introduction to File Management / Using Files

Opening Files at Application Startup Time

A user often launches your application by double-clicking one of its document icons or by selecting one or more document icons and choosing the Open command in the Finder's File menu. In these cases, your application needs to determine which files the user selected so that it can open each one and display its contents in a window. There are two ways in which your application can determine this.

If the user opens a file from the Finder and if your application supports high-level events, the Finder sends it an Open Documents event. Your application then needs to determine which file or files to open and react accordingly. For a complete description of how to process the Open Documents event, see the chapter "Apple Event Manager" in Inside Macintosh: Interapplication Communication.

IMPORTANT

If at all possible, your application should support high-level events. You should use the techniques illustrated in this section only if your application doesn't support high-level events.

If your application does not support high-level events, you need to ask the Finder at application launch time whether or not the user launched the application by selecting some documents. You can do this by calling the CountAppFiles procedure and seeing whether the count of files is 1 or more. Then you can call the procedures GetAppFiles and ClrAppFiles to retrieve the information about the selected files. The technique is illustrated in Listing 1-17.

The CountAppFiles procedure determines how many files, if any, the user selected at application startup time. If the value of the myNum parameter is nonzero, then myJob contains a value that indicates whether the files were selected for opening or printing. Currently, myJob can have one of two values:

CONST
   appOpen  =  0;    {open the document(s)}
   appPrint =  1;    {print the document(s)}

Listing 1-17 Opening files at application launch time

PROCEDURE DoInitFiles;
VAR
   myNum:   Integer;    {number of files to be opened or printed}
   myJob:   Integer;    {open or print the files?}
   index:   Integer;    {index of current file}
   myFile:  AppFile;    {file info}
   mySpec:  FSSpec;     {file system specification}
   myErr:   OSErr;
BEGIN
   CountAppFiles(myJob, myNum);
   IF myNum > 0 THEN                         {user selected some files}
      IF myJob = appOpen THEN                {files are to be opened}
         FOR index := 1 TO myNum DO
            BEGIN
               GetAppFiles(index, myFile);   {get file info from Finder}
               myErr := FSMakeFSSpec(myFile.vRefNum, 0, myFile.fName,
                                    mySpec); {make an FSSpec to hold info}
               myErr := DoOpenFile(mySpec);  {read in file's data}
               ClrAppFiles(index);           {show we've got the info}
            END;
END;

In Listing 1-17, if the files are to be opened, then DoInitFiles obtains information about them by calling the GetAppFiles procedure for each one. The GetAppFiles procedure returns the information in a record of type AppFile.

TYPE AppFile   =
   RECORD
      vRefNum:    Integer;    {working directory reference number}
      fType:      OSType;     {file type}
      versNum:    Integer;    {version number; ignored}
      fName:      Str255;     {filename}
   END;

Because the function DoOpenFile takes an FSSpec record as a parameter, DoInitFiles next converts the information returned in the myFile parameter into an FSSpec record, using FSMakeFSSpec. Then DoInitFiles calls DoOpenFile to read the file data and ClrAppFiles to let the Finder know that it has processed the information for that file.

Note

The vRefNum field of an AppFile record does not contain a volume reference number; instead it contains a working directory reference number, which encodes both the volume reference number and the parent directory ID. (That's why the second parameter passed to FSMakeFSSpec in Listing 1-17 is 0.)