Inside Macintosh: Files /: Chapter 3 - Standard File Package

Summary of the Standard File Package

Pascal Summary

Constants

CONST
   {Gestalt selector and reply}
   gestaltStandardFileAttr =  'stdf';
   gestaltStandardFile58   =  0;
   {standard dialog resource IDs}
   sfPutDialogID           =  -6043;   {Save dialog box}
   sfGetDialogID           =  -6042;   {Open dialog box}
   {items that appear in both the Open and Save dialog boxes}
   sfItemOpenButton        =  1;       {Save or Open button}
   sfItemCancelButton      =  2;       {Cancel button}
   sfItemBalloonHelp       =  3;       {Balloon Help}
   sfItemVolumeUser        =  4;       {volume icon and name}
   sfItemEjectButton       =  5;       {Eject button}
   sfItemDesktopButton     =  6;       {Desktop button}
   sfItemFileListUser      =  7;       {display list}
   sfItemPopUpMenuUser     =  8;       {directory pop-up menu}
   sfItemDividerLinePict   =  9;       {dividing line between buttons}
   {items that appear in Save dialog boxes only}
   sfItemFileNameTextEdit  =  10;      {filename field}
   sfItemPromptStaticText  =  11;      {filename prompt text area}
   sfItemNewFolderUser     =  12;      {New Folder button}
   {pseudo-items available prior to version 7.0}
   sfHookFirstCall         =  -1;      {initialize display}
   sfHookCharOffset        =  $1000;   {offset for character input}
   sfHookNullEvent         =  100;     {null event}
   sfHookRebuildList       =  101;     {redisplay list}
   sfHookFolderPopUp       =  102;     {display parent-directory menu}
   sfHookOpenFolder        =  103;     {display contents of selected }
                                       { folder or volume}
   {additional pseudo-items introduced in version 7.0}
   sfHookLastCall          =  -2;      {clean up after display}
   sfHookOpenAlias         =  104;     {resolve alias}
   sfHookGoToDesktop       =  105;     {display contents of desktop}
   sfHookGoToAliasTarget   =  106;     {select target of alias}
   sfHookGoToParent        =  107;     {display contents of parent}
   sfHookGoToNextDrive     =  108;     {display contents of next drive}
   sfHookGoToPrevDrive     =  109;     {display contents of previous drive}
   sfHookChangeSelection   =  110;     {select target of reply record}
   sfHookSetActiveOffset   =  200;     {switch active item}
   {refCon field in the window record in the dialog record}
   sfMainDialogRefCon      =  'stdf';  {main dialog box}
   sfNewFolderDialogRefCon =  'nfdr';  {New Folder dialog box}
   sfReplaceDialogRefCon   =  'rplc';  {name conflict dialog box}
   sfStatWarnDialogRefCon  =  'stat';  {stationery warning}
   sfErrorDialogRefCon     =  'err ';  {general error report}
   sfLockWarnDialogRefCon  =  'lock';  {software lock warning}
   {resource IDs and item numbers of pre-7.0 dialog boxes}
   putDlgID                =  -3999;   {Save dialog box}
   putSave                 =  1;       {Save button}
   putCancel               =  2;       {Cancel button}
   putEject                =  5;       {Eject button}
   putDrive                =  6;       {Drive button}
   putName                 =  7;       {filename field}

   getDlgID                =  -4000;   {Open dialog box}
   getOpen                 =  1;       {Open button}
   getCancel               =  3;       {Cancel button}
   getEject                =  5;       {Eject button}
   getDrive                =  6;       {Drive button}
   getNmList               =  7;       {list of names}
   getScroll               =  8;       {scroll bar}

Data Types

Standard File Reply Records

TYPE StandardFileReply  =        {enhanced standard file reply record}
   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;

   SFReply           =           {original standard file reply record}
   RECORD
      good:          Boolean;    {TRUE if user did not cancel}
      copy:          Boolean;    {reserved}
      fType:         OSType;     {file type}
      vRefNum:       Integer;    {working directory reference number}
      version:       Integer;    {reserved}
      fName:         Str63;      {filename}
   END;

Standard File Type List

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

Callback Routine Pointer Types

   DlgHookProcPtr       =  ProcPtr;    {dialog hook function}
   DlgHookYDProcPtr     =  ProcPtr;    {dialog hook function with data}
   FileFilterProcPtr    =  ProcPtr;    {file filter function}
   FileFilterYDProcPtr  =  ProcPtr;    {file filter function with data}
   ModalFilterProcPtr   =  ProcPtr;    {modal-dialog filter}
   ModalFilterYDProcPtr =  ProcPtr;    {modal-dialog filter with data}
   ActivateYDProcPtr    =  ProcPtr;    {activation procedure}

Standard File Package Routines

Saving Files

PROCEDURE StandardPutFile	(prompt: Str255; defaultName: Str255; 
				VAR reply: StandardFileReply);
PROCEDURE CustomPutFile		(prompt: Str255; defaultName: Str255; 
				VAR reply: StandardFileReply; dlgID: Integer; 
				where: Point; dlgHook: DlgHookYDProcPtr; 
				filterProc: ModalFilterYDProcPtr; 
				activeList: Ptr; 
				activateProc: ActivateYDProcPtr; 
				yourDataPtr: UNIV Ptr);
PROCEDURE SFPutFile		(where: Point; prompt: Str255; 
				origName: Str255; dlgHook: DlgHookProcPtr; 
				VAR reply: SFReply);
PROCEDURE SFPPutFile		
(where: Point; prompt: Str255; 
				origName: Str255; dlgHook: DlgHookProcPtr; 
				VAR reply: SFReply; dlgID: Integer; 
				filterProc: ModalFilterProcPtr);

Opening Files

PROCEDURE StandardGetFile	(fileFilter: FileFilterProcPtr; 
				numTypes: Integer; typeList: SFTypeList; 
				VAR reply: StandardFileReply);
PROCEDURE CustomGetFile		(fileFilter: FileFilterYDProcPtr; 
				numTypes: Integer; typeList: SFTypeList; 
				VAR reply: StandardFileReply; dlgID: Integer; 
				where: Point; dlgHook: DlgHookYDProcPtr; 
				filterProc: ModalFilterYDProcPtr; 
				activeList: Ptr; 
				activateProc: ActivateYDProcPtr; 
				yourDataPtr: UNIV Ptr);
PROCEDURE SFGetFile		(where: Point; prompt: Str255; 
				fileFilter: FileFilterProcPtr; 
				numTypes: Integer; typeList: SFTypeList; 
				dlgHook: DlgHookProcPtr; VAR reply: SFReply); 
PROCEDURE SFPGetFile		(where: Point; prompt: Str255;
				fileFilter: FileFilterProcPtr;
				numTypes: Integer; typeList: SFTypeList;
				dlgHook: DlgHookProcPtr; VAR reply: SFReply; 
				dlgID: Integer; 
				filterProc: ModalFilterProcPtr);

Application-Defined Routines

FUNCTION MyStandardFileFilter
   				(pb: CInfoPBPtr): Boolean;
FUNCTION MyCustomFileFilter	(pb: CInfoPBPtr; myDataPtr: Ptr): Boolean;
FUNCTION MyDlgHook		(item: Integer; theDialog: DialogPtr; 
				myDataPtr: Ptr): Integer;
FUNCTION MyModalFilter		(theDialog: DialogPtr; 
				VAR theEvent: EventRecord; 
				VAR itemHit: Integer): Boolean;
FUNCTION MyModalFilterYD	(theDialog: DialogPtr; 
				VAR theEvent: EventRecord; 
				VAR itemHit: Integer; myDataPtr: Ptr): Boolean;
PROCEDURE MyActivateProc	(theDialog: DialogPtr; itemNo: Integer; 
				activating: Boolean; myDataPtr: Ptr);

C Summary

Constants

/*Gestalt selector and reply*/
#define gestaltStandardFileAttr  'stdf'
#define gestaltStandardFile58    0
/*standard dialog resource IDs*/
enum {sfPutDialogID           = (-6043)}; /*Save dialog box*/
enum {sfGetDialogID           = (-6042)}; /*Open dialog box*/
/*items that appear in both the Open and Save dialog boxes/*
enum {sfItemOpenButton        = 1};    /*Save or Open button*/
enum {sfItemCancelButton      = 2};    /*Cancel button*/
enum {sfItemBalloonHelp       = 3};    /*Balloon Help*/
enum {sfItemVolumeUser        = 4};    /*volume icon and name*/
enum {sfItemEjectButton       = 5};    /*Eject button*/
enum {sfItemDesktopButton     = 6};    /*Desktop button*/
enum {sfItemFileListUser      = 7};    /*display list*/
enum {sfItemPopUpMenuUser     = 8};    /*directory pop-up menu*/
enum {sfItemDividerLinePict   = 9};    /*dividing line between buttons*/
/*items that appear in Save dialog boxes only*/
enum {sfItemFileNameTextEdit  = 10};   /*filename field*/
enum {sfItemPromptStaticText  = 11};   /*filename prompt text area*/
enum {sfItemNewFolderUser     = 12};   /*New Folder button*/
/*pseudo-items available prior to version 7.0*/
enum {sfHookFirstCall         = (-1)}; /*initialize display*/
enum {sfHookCharOffset        = 0x1000};/*offset for character input*/
enum {sfHookNullEvent         = 100};  /*null event*/
enum {sfHookRebuildList       = 101};  /*redisplay list*/
enum {sfHookFolderPopUp       = 102};  /*display parent-directory menu*/
enum {sfHookOpenFolder        = 103};  /*display contents of selected */
                                       /* folder or volume*/
/*additional pseudo-items introduced in version 7.0*/
enum {sfHookLastCall          = (-2)}; /*clean up after display*/
enum {sfHookOpenAlias         = 104};  /*resolve alias*/
enum {sfHookGoToDesktop       = 105};  /*display contents of desktop*/
enum {sfHookGoToAliasTarget   = 106};  /*select target of alias*/
enum {sfHookGoToParent        = 107};  /*display contents of parent*/
enum {sfHookGoToNextDrive     = 108};  /*display contents of next drive*/
enum {sfHookGoToPrevDrive     = 109};  /*display contents of previous drive*/
enum {sfHookChangeSelection   = 110};  /*select target of reply record*/
enum {sfHookSetActiveOffset   = 200};  /*switch active item*/
/*refCon field in the window record in the dialog record*/
#define sfMainDialogRefCon       'stdf'   /*main dialog box*/
#define sfNewFolderDialogRefCon  'nfdr'   /*New Folder dialog box*/
#define sfReplaceDialogRefCon    'rplc'   /*name conflict dialog box*/
#define sfStatWarnDialogRefCon   'stat'   /*stationery warning*/
#define sfErrorDialogRefCon      'err '   /*general error report*/
#define sfLockWarnDialogRefCon   'lock'   /*software lock warning*/
/*resource IDs and item numbers of pre-7.0 dialog boxes*/
enum {putDlgID                = -3999};   /*Save dialog box*/
enum {putSave                 = 1};       /*Save button*/
enum {putCancel               = 2};       /*Cancel button*/
enum {putEject                = 5};       /*Eject button*/
enum {putDrive                = 6};       /*Drive button*/
enum {putName                 = 7};       /*filename field*/

enum {getDlgID                = -4000};   /*Open dialog box*/
enum {getOpen                 = 1};       /*Open button*/
enum {getCancel               = 3};       /*Cancel button*/
enum {getEject                = 5};       /*Eject button*/
enum {getDrive                = 6};       /*Drive button*/
enum {getNmList               = 7};       /*list of names*/
enum {getScroll               = 8};       /*scroll bar*/

Data Types

Standard File Reply Records

struct StandardFileReply {       /*enhanced standard file reply record*/
      Boolean        sfGood;     /*TRUE if user did not cancel*/
      Boolean        sfReplacing;/*TRUE if replacing file with same name*/
      OSType         sfType;     /*file type*/
      FSSpec         sfFile;     /*selected file, folder, or volume*/
      ScriptCode     sfScript;   /*script of file, folder, or volume name*/
      short          sfFlags;    /*Finder flags of selected item*/
      Boolean        sfIsFolder; /*selected item is a folder*/
      Boolean        sfIsVolume; /*selected item is a volume*/
      long           sfReserved1;/*reserved*/
      short          sfReserved2;/*reserved*/
};

typedef struct StandardFileReply StandardFileReply;

struct SFReply {                 /*original standard file reply record*/
      Boolean        good;       /*TRUE if user did not cancel*/
      Boolean        copy;       /*reserved*/
      OSType         fType;      /*file type*/
      short          vRefNum;    /*working directory reference number*/
      short          version;    /*reserved*/
      Str63          fName;      /*filename*/
};

typedef struct SFReply SFReply;

Standard File Type List

typedef OSType SFTypeList[4];

Callback Routine Pointer Types

/*dialog hook function*/
typedef pascal short (*DlgHookProcPtr)
   		(short item, DialogPtr theDialog);
/*dialog hook function with data*/
typedef pascal short (*DlgHookYDProcPtr)
   		(short item, DialogPtr theDialog, 
		void *yourDataPtr);
/*file filter function*/
typedef pascal Boolean (*FileFilterProcPtr)
   		(ParmBlkPtr PB);
/*file filter function with data*/
typedef pascal Boolean (*FileFilterYDProcPtr)
   		(ParmBlkPtr PB, void *yourDataPtr);
/*modal-dialog filter*/
typedef pascal ProcPtr ModalFilterProcPtr;
   		(DialogPtr theDialog, EventRecord *theEvent, 
		short *itemHit);
/*modal-dialog filter with data*/
typedef pascal Boolean (*ModalFilterYDProcPtr)
   		(DialogPtr theDialog, EventRecord *theEvent, 
		short *itemHit, void *yourDataPtr);
/*activation procedure*/
typedef pascal void (*ActivateYDProcPtr)
   		(DialogPtr theDialog, 
		short itemNo, Boolean activating, 
		void *yourDataPtr);

Standard File Package Routines

Saving Files

pascal void StandardPutFile	(const Str255 prompt, const Str255 defaultName, 
				StandardFileReply *reply);
pascal void CustomPutFile	(const Str255 prompt, const Str255 defaultName, 
				StandardFileReply *reply, short dlgID, 
				Point where, DlgHookYDProcPtr dlgHook, 
				ModalFilterYDProcPtr filterProc, 
				short *activeList, 
				ActivateYDProcPtr activateProc, 
				void *yourDataPtr);
pascal void SFPutFile		(Point where, const Str255 prompt, 
				const Str255 origName, DlgHookProcPtr dlgHook, 
				SFReply *reply);
pascal void SFPPutFile		(Point where, const Str255 prompt, 
				const Str255 origName, DlgHookProcPtr dlgHook, 
				SFReply *reply, short dlgID, 
				ModalFilterProcPtr filterProc);

Opening Files

pascal void StandardGetFile	(const Str255 prompt,
				FileFilterProcPtr fileFilter, 
				short numTypes, SFTypeList typeList, 
				StandardFileReply *reply);
pascal void CustomGetFile	(FileFilterYDProcPtr fileFilter, 
				short numTypes, SFTypeList typeList, 
				StandardFileReply *reply, short dlgID, 
				Point where, DlgHookYDProcPtr dlgHook, 
				ModalFilterYDProcPtr filterProc, 
				short *activeList, 
				ActivateYDProcPtr activateProc, 
				void *yourDataPtr);
pascal void SFGetFile		(Point where, const Str255 prompt, 
				FileFilterProcPtr fileFilter, short numTypes,
				SFTypeList typeList, DlgHookProcPtr dlgHook,
				SFReply *reply);
pascal void SFPGetFile		(Point where, const Str255 prompt,
				FileFilterProcPtr fileFilter,
				short numTypes, SFTypeList typeList,
				DlgHookProcPtr dlgHook, SFReply *reply, 
				short dlgID, ModalFilterProcPtr filterProc);

Application-Defined Routines

pascal Boolean MyStandardFileFilter
   				(CInfoPBPtr pb);
pascal Boolean MyCustomFileFilter
   				(CInfoPBPtr pb, Ptr myDataPtr);
pascal short MyDlgHook		(short item, DialogPtr theDialog, 
				Ptr myDataPtr);
pascal Boolean MyModalFilter	(DialogPtr theDialog, 
				EventRecord *theEvent, short *itemHit);
pascal Boolean MyModalFilterYD
   				(DialogPtr theDialog, 
				EventRecord *theEvent, short *itemHit, 
				Ptr myDataPtr);
pascal void MyActivateProc	(DialogPtr theDialog, short itemNo, 
				Boolean activating, Ptr myDataPtr);

Assembly-Language Summary

Data Structures

New Standard File Reply Record
0 `sfGood` byte command-valid flag
1 `sfReplacing` byte replace existing file flag
2 `sfType` long file type
6 `sfFile` 70 bytes selected item
76 `sfScript` word display script
78 `sfFlags` word Finder flags from catalog
80 `sfIsFolder` byte folder flag
81 `sfIsVolume` byte volume flag
82 `sfReserved1` long reserved
86 `sfReserved2` word reserved

Old Standard File Reply Record
0 `good` byte command-valid flag
1 `copy` byte reserved
2 `fType` long file type
6 `vRefNum` word working directory reference number
8 `version` word reserved
10 `fName` 64 bytes name of file (length byte followed by up to 63 characters)

0	`good`	byte	command-valid flag
1	`copy`	byte	reserved
2	`fType`	long	file type
6	`vRefNum`	word	working directory reference number
8	`version`	word	reserved
10	`fName`	64 bytes	name of file (length byte followed by up to 63 characters)

Trap Macros

Trap Macro Requiring Routine Selector

_Pack3 
Selector Routine

$0001 SFPutFile

$0002 SFGetFile

$0003 SFPPutFile

$0004 SFPGetFile

$0005 StandardPutFile

$0006 StandardGetFile

$0007 CustomPutFile

$0008 CustomGetFile

Selector	Routine
$0001	`SFPutFile`
$0002	`SFGetFile`
$0003	`SFPPutFile`
$0004	`SFPGetFile`
$0005	`StandardPutFile`
$0006	`StandardGetFile`
$0007	`CustomPutFile`
$0008	`CustomGetFile`

Global Variables
CurDirStore long The directory ID of the current directory.
SFSaveDisk word The negative of the volume reference number of the current volume.

0	`sfGood`	byte	command-valid flag
1	`sfReplacing`	byte	replace existing file flag
2	`sfType`	long	file type
6	`sfFile`	70 bytes	selected item
76	`sfScript`	word	display script
78	`sfFlags`	word	Finder flags from catalog
80	`sfIsFolder`	byte	folder flag
81	`sfIsVolume`	byte	volume flag
82	`sfReserved1`	long	reserved
86	`sfReserved2`	word	reserved

CurDirStore	long	The directory ID of the current directory.
SFSaveDisk	word	The negative of the volume reference number of the current volume.

Summary of the Standard File Package

Pascal Summary

Constants

Data Types

Standard File Reply Records

Standard File Type List

Callback Routine Pointer Types

Standard File Package Routines

Saving Files

Opening Files

Application-Defined Routines

C Summary

Constants

Data Types

Standard File Reply Records

Standard File Type List

Callback Routine Pointer Types

Standard File Package Routines

Saving Files

Opening Files

Application-Defined Routines

Assembly-Language Summary

Data Structures

Old Standard File Reply Record 0goodbytecommand-valid flag 1copybytereserved 2fTypelongfile type 6vRefNumwordworking directory reference number 8versionwordreserved 10fName64 bytesname of file (length byte followed by up to 63 characters)

Trap Macros

Trap Macro Requiring Routine Selector

Global Variables CurDirStorelongThe directory ID of the current directory. SFSaveDiskwordThe negative of the volume reference number of the current volume.

Old Standard File Reply Record
0 `good` byte command-valid flag
1 `copy` byte reserved
2 `fType` long file type
6 `vRefNum` word working directory reference number
8 `version` word reserved
10 `fName` 64 bytes name of file (length byte followed by up to 63 characters)

Global Variables
CurDirStore long The directory ID of the current directory.
SFSaveDisk word The negative of the volume reference number of the current volume.