All Databases Inside Mac - Basic Toolbox

SFPutFile

Initiate a standard Save/Save As... dialog

#include <StandardFile.h> Standard File Package

void SFPutFile(where, prompt, origName, dlgHook, reply );

Point where ; coordinates for topLeft of dialog window

Str255 prompt ; e.g.,"\pSave Current Document as:

Str255 origName ; default filename displayed in input box

ProcPtr dlgHook ; NIL= standard; else=addr of custom routine

SFReply *reply ; address of structure; receives return info

This is the normal way to ask the user for a filename to be used in a "Save

As..." dialog (or a "Save" dialog for an un titled document). It presents a dialog

window and handles events until the user enters or accepts a filename or

cancels the operation.

where is a screen location, expressed in global ( screen) coordinates. The

top-left corner of the dialog window is positioned at this point.

prompt is the address of a length-prefixed Pascal-style string containing

text to be displayed above the filename input area.

origName is the address of a length-prefixed Pascal-style string containing

the default filename to be displayed in the input box. It should be the

name of the current document or an empty string ("\p").

dlgHook is the address of a custom procedure that handles the dialog. Use

dlgHook =NIL to use the standard dialog.

reply is the address of a variable-length SFReply structure. On entry, its

contents are ignored. Upon return, it contains the results of the

dialog, including the user-input filename.

Returns: none

Notes: This is a high-level function that handles all the user interaction needed

for obtaining a volume reference, working directory, and filename to use in

storing a file. The standard dialog window is a 304 x 104 rectangle. It

looks like:

The user can move through the directory hierarchy via the drop-down

directory button and can edit the filename using standard TextEdit

operations. Double-clicking a directory name in the file list will make that

directory the working directory and its files and directories will be

displayed.

Upon return, the SFReply data structure will contain the following

information:

Name Size Type Description

good 1 Boolean FALSE=Cancel; TRUE=Save or Open

copy 1 Boolean (not used)

fType 2 OSType File type (no meaning in SFPutFile)

vRefNum 2 short Volume or working directory number

version 2 short (not used any more, always 0)

fName 64 char length-prefixed filename; actual name

will be <= 31 characters.

Custom Standard File Dialogs

Many applications customize the standard file dialog display and

interaction. For instance, you may wish to provide better filename editing

facilities or provide radio buttons to limit selection options. Such

applications typically use SFPPutFile since it is more flexible. However,

SFPutFile does allow customization using the following techniques:

To change the way the dialog box looks, create a custom dialog template in

your resource file that has a resource ID of putDlgID (-3999). Your dialog

must contain all the standard file dialog items, but the location and

appearance may be different.

Note: creating such a duplicate can confuse Desk Accessories. It's better

to use SFPPutFile, which lets you specify an application resource as the

dialog record.

For advanced customization, pass the address of a dialog handling function

as the dlgHook parameter. This routine will receive two parameters and is

expected to return a short item number value (or 0 if you have processed

the item yourself). For example:

pascal short mySaveDialog( item , theDialog )

short item ; Ì/* ID of dialog item affected */

DialogPtr theDialog ; /* addr of DialogRecord structure */

SFPutFile calls ModalDialog and upon return, passes the two

parameters to the custom function. The custom function should process (or

ignore) the event and return control to SFPutFile, passing back the

number of the dialog item affected by the call. If you return one of the

following, standard file will handle the user's selection in the standard way:

getOpen = 1; /* open button */

getCancel = 3; /* cancel button */

getEject = 5;

getDrive = 6;

getNmList = 7;

getScroll = 8;

Referenced by (40):