Inside Macintosh: Files /

Chapter 3 - Standard File Package / Using the Standard File Package

Presenting the Standard User Interface

You can use the standard dialog boxes provided by the Standard File Package to prompt the user for the name of a file to open or a filename and location to use when saving a document. Use StandardGetFile to present the standard interface when opening a file and StandardPutFile to present the standard interface when saving a file.

Listing 3-1 illustrates how your application can use StandardGetFile to elicit a file specification after the user chooses Open from the File menu.

Listing 3-1 Handling the Open menu command

FUNCTION DoOpenCmd: OSErr;
VAR
   myReply:    StandardFileReply;   {Standard File reply record}
   myTypes:    SFTypeList;          {types of files to display}
   myErr:      OSErr;
BEGIN
   myTypes[0] := 'TEXT';            {display text files only}
   StandardGetFile(NIL, 1, myTypes, myReply);
   IF myReply.sfGood THEN
      myErr := DoOpenFile(myReply.sfFile)
   ELSE
      myErr := UsrCanceledErr;
   DoOpenCmd := myErr;
END;

If the user dismisses the dialog box by clicking the Open button, the reply record field myReply.sfGood is set to TRUE; in that case, the function defined in Listing 3-1 calls the application-defined function DoOpenFile, passing it the file system specification record contained in the reply record. For a sample definition of the DoOpenFile function, see the chapter "Introduction to File Management" in this book.

The third parameter to StandardGetFile is a list of file types that are to appear in the list of files and folders; the second parameter is the number of items in that list of file types. The list of file types is of type SFTypeList.

TYPE  SFTypeList  =  ARRAY[0..3] OF OSType;

If you need to display more than four types of files, you can define a new data type that is large enough to hold all the types you need. For example, you can define the data type MyTypeList to hold ten file types:

TYPE  MyTypeList  =  ARRAY[0..9] OF OSType;
      MyTListPtr  =  ^MyTypeList;

Listing 3-2 shows how to call StandardGetFile using an expanded type list.

Listing 3-2 Specifying more than four file types

FUNCTION DoOpenCmd: OSErr;
VAR
   myReply:    StandardFileReply;   {Standard File reply record}
   myTypes:    MyTypeList;          {types of files to display}
   myErr:      OSErr;
BEGIN
   myTypes[0] := 'TEXT';            {first file type to display}
   {Put other assignments here.}
   myTypes[9] := 'RTFT';            {tenth file type to display}
   StandardGetFile(NIL, 1, MyTListPtr(myTypes)^, myReply);
   IF myReply.sfGood THEN
      myErr := DoOpenFile(myReply.sfFile)

   ELSE
      myErr := UsrCanceledErr;
   DoOpenCmd := myErr;
END;

Note

To display all file types in the dialog box, pass -1 as the second parameter. Invisible files and folders are not shown in the dialog box unless you pass -1 in that parameter. If you pass -1 as the second parameter when calling CustomGetFile, the dialog box also lists folders; this is not true when you call StandardGetFile.

The first parameter passed to StandardGetFile is the address of a file filter function,
a function that helps determine which files appear in the list of files to open. (In
Listing 3-1, this address is NIL, indicating that all files of the specified type are to be listed.) See "Writing a File Filter Function" on page 3-20 for details on defining a filter function for use with StandardGetFile.