Inside Macintosh: Files /

Chapter 3 - Standard File Package

Using the Standard File Package

You use the Standard File Package to handle the user interface when the user must specify a file to be saved or opened. You typically call the Standard File Package after
the user chooses Save, Save As, or Open from the File menu.

When saving a document, you call one of the PutFile procedures; when opening a document, you call one of the GetFile procedures. The Standard File Package in version 7.0 introduces two pairs of enhanced procedures:

• StandardPutFile and StandardGetFile, for presenting the standard interface
• CustomPutFile and CustomGetFile, for presenting a customized interface

Before calling the enhanced Standard File Package procedures, verify that they are available by calling the Gestalt function with the gestaltStandardFileAttr selector. If Gestalt sets the gestaltStandardFile58 bit in the reply, the four enhanced procedures are available.

If the enhanced procedures are not available, you need to use the original Standard File Package procedures that are available in all system software versions:

• SFPutFile and SFGetFile, for presenting the standard interface
• SFPPutFile and SFPGetFile, for presenting a customized interface

This section focuses on the enhanced procedures introduced in system software
version 7.0. If you need to use the original procedures, see "Using the Original Procedures" on page 3-40. You can adapt most of the techniques shown in this section
for use with the original procedures. In general, however, the original procedures are slightly harder to use and somewhat less powerful than their enhanced counterparts.

All the enhanced procedures return the results of the dialog boxes in a new reply record, StandardFileReply.

TYPE StandardFileReply =
   RECORD
      sfGood:        Boolean;    {TRUE if user did not cancel}
      sfReplacing:   Boolean;    {TRUE if replacing file with same name}
      sfType:        OSType;     {file type}
      sfFile:        FSSpec;     {selected file, folder, or volume}
      sfScript:      ScriptCode; {script of file, folder, or volume name}
      sfFlags:       Integer;    {Finder flags of selected item}
      sfIsFolder:    Boolean;    {selected item is a folder}
      sfIsVolume:    Boolean;    {selected item is a volume}
      sfReserved1:   LongInt;    {reserved}
      sfReserved2:   Integer;    {reserved}
   END;

The reply record identifies selected files with a file system specification (FSSpec) record. You can pass the FSSpec record directly to the File Manager functions that recognize FSSpec records, such as FSpOpenDF or FSpCreate. The reply record also contains additional fields that support the Finder features introduced in system software
version 7.0.

The sfGood field reports whether the reply record is valid--that is, whether your application can use the information in the other fields. The field is set to TRUE after the user clicks Save or Open, and to FALSE after the user clicks Cancel.

Your application needs to look primarily at the sfFile and sfReplacing fields when the sfGood field contains TRUE. The sfFile field contains a file system specification record that describes the selected file or folder. If the selected file is a stationery pad, the reply record describes the file itself, not a copy of the file.

The sfReplacing field reports whether a file to be saved replaces an existing file
of the same name. This field is valid only after a call to the StandardPutFile or CustomPutFile procedure. Your application can rely on the value of this field instead of checking for and handling name conflicts itself.

Note

See "Enhanced Standard File Reply Record" on page 3-42 for a complete description of the fields of the StandardFileReply record.

The Standard File Package fills in the reply record and returns when the user completes one of its dialog boxes--either by selecting a file and clicking Save or Open, or by clicking Cancel. Your application checks the values in the reply record to see what action to take, if any. If the selected item is an alias for another item, the Standard File Package resolves the alias and places a file system specification record for the target in the sfFile field when the user completes the dialog box. (See the chapter "Finder Interface" of Inside Macintosh: Macintosh Toolbox Essentials for a description of aliases.)

---

Subtopics

Presenting the Standard User Interface

Customizing the User Interface

Setting the Current Directory

Selecting a Directory

Selecting a Volume

Using the Original Procedures