All Databases Inside Mac - Basic Toolbox

About the Standard File Package and System 7.0

Your application can use the Standard File Package in system 7.0 to present a

standard user interface for naming and identifying files. The

Standard File Package displays the dialog boxes that let the user specify the

names and locations of files to be saved or opened, and it reports the user's choices to

your application. The new procedures introduced in system 7.0 allow your application

to either streamline its interaction with the Standard File Package or exercise

more control over the user interface.

The features described in the Standard File Package are available only in system

7.0 or later. Call the Gestalt function, described in the Compatibility Guidelines

, to determine whether the new features are present.

To use the information in this section you must be familiar with earlier versions of

the Standard File Package; the file system specification (FSSpec) record,

described in the

File Manager, and the new features of the system 7.0 Finder, described in the

Finder Interface .

The Standard File Package handles the interface between the user and your

application when the user saves or opens a document. It displays dialog boxes through

which the user specifies the name and location of the document to be saved or opened. It

allows your application to customize the dialog boxes and, through callback routines,

to handle user actions during the dialogs. The Standard File Package procedures

describe the user's choices through a reply record.

The Standard File Package in system 7.0 introduces:

• a pair of simplified procedures that you call to display and handle the

standard Open and Save dialog boxes

• a pair of customizable procedures that you call when you need more

control over the interaction

• a new reply record (StandardFileReply ) that identifies files and

folders with a file system specification record and that accommodates

the new Finder features

• a new layout for the default dialog boxes

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 revised

Standard File Package in system 7.0 introduces two new pairs of procedures:

• StandardPutFile and StandardGetFile, for presenting the

standard interface

• CustomPutFile and CustomGetFile, for presenting a customized

interface

Before calling any of the new Standard File Package procedures, verify that they

are available by calling the Gestalt function with a selector of

gestaltStandardFileAttr. If Gestalt sets the gestaltStandardFile58 bit in the reply, the

four new procedures are available. For a complete description of the Gestalt function,

see the Compatibility Guidelines .

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

StandardFileReply.

The reply record identifies selected files with a file system specification (FSSpec )

record. You can pass the FSSpec record directly to a set of new File Manager

functions provided with system 7.0. The reply record also contains additional fields

that support the Finder features introduced in system 7.0.

The sfGood field reports whether the reply record is valid. The value is TRUE after

the user clicks Save or Open, FALSE after the user clicks Cancel. When the user has

completed the dialog box, the other fields in the reply record are valid only if sfGood is

TRUE.

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. When the user assigns a name that duplicates that of an

existing file, the Standard File Package asks for verification by displaying a

subsidiary dialog box. If the user verifies the name, the Standard File Package sets

the sfReplacing field to TRUE and returns to your application; if the user cancels the

overwriting of the file, the Standard File Package returns to the main dialog box.

If the chosen name does not conflict with a name that already exists, the

Standard File Package sets the field to FALSE and returns. Your application can

rely on the value of this field instead of checking for and handling name conflicts itself.

The sfType field contains the file type of the selected file. (File types are described in

the Finder Interface ) Only StandardGetFile and CustomGetFile return a file

type in this field.

The sfFile field describes the selected file, folder, or volume with a file system

specification record, which contains a volume reference number, parent directory ID,

and name. (See the File Manager for a complete description of the file system

specification record.) If the selected item is an alias for another item, the

Standard File Package resolves the alias and places the file system specification

record for the target in the sfFile field when the user completes the dialog. If the

selected file is a stationery pad, the reply record describes the file itself, not a copy of

the file.

The sfScript field identifies the script in which the name of the document is to be

displayed. (This information is used by the Finder and by the

Standard File Package. See the Script Manager section of the

Worldwide Software Overview for a list of defined script codes.) A script code of

smSystemScript (-1) represents the default system script.

The sfFlags field contains the Finder flags from the Finder information record in the

catalog entry for the selected file. (See the section en titled Finder Interface for a

description of the Finder flags.) This field is returned only by StandardGetFile and

CustomGetFile. If your application supports stationery, it should check the

stationery bit in the Finder flags to determine whether to treat the selected file as

stationery. Unlike the Finder, the Standard File Package does not automatically

create a document from a stationery pad and pass your application the new document. If

the user opens a stationery document from within an application that does not support

stationery, the Standard File Package displays a dialog box warning the user that

the master copy is being opened.

The sfIsFolder field reports whether the selected item is a folder (TRUE) or a file or

volume (FALSE).

The sfIsVolume field reports whether the selected item is a volume (TRUE) or a file

or folder (FALSE).

Referenced by (4):