Legacy Document

Inside Macintosh: Files /

Chapter 3 - Standard File Package / Standard File Package Reference

Standard File Package Routines / Saving Files

CustomPutFile

Use the CustomPutFile procedure when your application requires more control over
the Save dialog box than is possible using StandardPutFile.

PROCEDURE CustomPutFile (prompt: Str255; defaultName: Str255; 
                           VAR reply: StandardFileReply; 
                           dlgID: Integer; where: Point; 
                           dlgHook: DlgHookYDProcPtr; 
                           filterProc: ModalFilterYDProcPtr;
                           activeList: Ptr; 
                           activateProc: ActivateYDProcPtr;
                           yourDataPtr: UNIV Ptr);

prompt

The prompt message to be displayed over the text field.

defaultName

The initial name of the file.

reply

The reply record, which CustomPutFile fills in before returning.

dlgID

The resource ID of a customized dialog template. To use the standard template, set this parameter to 0.

where

The upper-left corner of the dialog box, in global coordinates. If you
specify the point (-1,-1), CustomPutFile automatically centers the
dialog box on the screen.

dlgHook

A pointer to your dialog hook function, which handles item selections received from the Dialog Manager. Specify a value of NIL if you have not added any items to the dialog box and want the standard items handled
in the standard ways. See "Writing a Dialog Hook Function" on page 3-21 for a description of the dialog hook function.

filterProc

A pointer to your modal-dialog filter function, which determines how the ModalDialog procedure filters events when called by the CustomPutFile procedure. Specify a value of NIL if you are not supplying your own function. See "Writing a Modal-Dialog Filter Function" on page 3-28 for a description of the modal-dialog filter function.

activeList

A pointer to a list of all dialog items that can be activated--that is, can be
the target of keyboard input. If you supply an activeList parameter of NIL, CustomPutFile uses the default targets (the filename field and the
list of files and folders). If you have added any fields that can accept keyboard input, you must modify the list. The list is stored as an array of 16-bit integers. The first integer is the number of items in the list. The remaining integers are the item numbers of all possible keyboard targets,
in the order that they are activated by the Tab key.

activateProc

A pointer to your activation procedure, which controls the highlighting of dialog items that are defined by your application and that can receive keyboard input. See "Writing an Activation Procedure" on page 3-30 for a description of the activation procedure.

yourDataPtr

Any 4-byte value; usually, a pointer to optional data supplied by your application. When CustomPutFile calls any of your callback routines,
it adds this parameter, making the data available to your callback routines. If you are not supplying any data of your own, you can specify
a value of NIL.

DESCRIPTION

The CustomPutFile procedure is an alternative to StandardPutFile when you want to display a customized Save dialog box or handle the default dialog box in a customized way. During the dialog, CustomPutFile gets and handles events (possibly with the assistance of application-defined callback routines) until the user completes the interaction, either by selecting a name and authorizing the save operation or by canceling the save operation. The CustomPutFile procedure returns the user's input in a record of type StandardFileReply.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for CustomPutFile are

Trap macro	Selector
_Pack3	$0007

SPECIAL CONSIDERATIONS

The CustomPutFile procedure is not available in all versions of system software.
Use the Gestalt function to determine whether CustomPutFile is available before calling it.

Because CustomPutFile may move memory, you should not call it at interrupt time.