Inside Macintosh: Macintosh Toolbox Essentials /: Chapter 7 - Finder Interface

Summary of the Finder Interface

Pascal Summary

Constants

CONST {Gestalt selectors}
      gestaltFindFolderAttr         = 'fold';   {selector for FindFolder}

      {interpreting Gestalt selector responses}
      gestaltFindFolderPresent      = 0;        {if this bit is set, }
                                                { FindFolder is present}
      {for custom icons}
      kCustomIconResource           = -16455;   {resource ID for }
                                                { custom icon}
      {for Finder flags}
      fHasBundle                    = 8192;     {set if file has 'BNDL'}
      fInvisible                    = 16384;    {set if icon is invisible}
      kIsOnDesk                     = $1;       {unused and reserved in }
                                                { System 7}
      kColor                        = $E;       {three bits of color coding}
      kIsShared                     = $40;      {file can be executed by }
                                                { multiple users }
                                                { simultaneously}
      kHasBeenInited                 = $100;    {file info is in desktop }
                                                { database}
      kHasCustomIcon                 = $400;    {file or directory has a }
                                                { customized icon}
      kIsStationery                  = $800;    {file is a stationery pad}
      kNameLocked                    = $1000;   {file or directory can't }
                                                { be renamed from Finder, }
                                                { and icon can't be changed}
      kHasBundle                     = $2000;   {file has a bundle resource}
      kIsInvisible                   = $4000;   {file or directory is }
                                                { invisible from Finder & }
                                                { from Standard File }
                                                { Package dialog boxes}
      kIsAlias                       = $8000;   {file is an alias file}
      
      {for FindFolder}
      kOnSystemDisk                 = $8000;    {use vRefNum for the }
                                                { boot disk}
      kCreateFolder                 = TRUE;     {create folder if it }
                                                { doesn't exist}
      kDontCreateFolder             = FALSE;    {don't create folder}
      
      {for special folder types}
      kSystemFolderType             = 'macs';   {System Folder}
      kDesktopFolderType            = 'desk';   {Desktop Folder}
      kTrashFolderType              = 'trsh';   {single-user Trash}
      kWhereToEmptyTrashFolderType  = 'empt';   {shared Trash on network}
      kPrintMonitorDocsFolderType   = 'prnt';   {PrintMonitor Documents}
      kStartupFolderType            = 'strt';   {Startup Items}
      kFontsFolderType              = 'font';   {Fonts}
      kAppleMenuFolderType          = 'amnu';   {Apple Menu Items}
      kControlPanelFolderType       = 'ctrl';   {Control Panels}
      kExtensionFolderType          = 'extn';   {Extensions}
      kPreferencesFolderType        = 'pref';   {Preferences}
      kTemporaryFolderType          = 'temp';   {Temporary Items}
      {alias types}
      kContainerFolderAliasType     = 'fdrp';   {folder alias}
      kContainerTrashAliasType      = 'trsh';   {Trash alias}
      kContainerHardDiskAliasType   = 'hdsk';   {hard disk alias}
      kContainerFloppyAliasType     = 'flpy';   {floppy disk alias}
      kContainerServerAliasType     = 'srvr';   {server alias}
      kApplicationAliasType         = 'adrp';   {application alias}
      kContainerAliasType           = 'drop';   {all other containers}
      kSystemFolderAliasType        = 'fasy';   {System Folder alias}
      kAppleMenuFolderAliasType     = 'faam';   {Apple Menu Items folder }
                                                { alias}
      kStartupFolderAliasType       = 'fast';   {Startup Items folder alias}
      kPrintMonitorDocsFolderAliasType
                                    = 'fapn';   {PrintMonitor Documents }
                                                { folder alias}
      kPreferencesFolderAliasType   = 'fapf';   {Preferences folder alias}
      kControlPanelFolderAliasType  = 'fact';   {Control Panels folder alias}
      kExtensionFolderAliasType     = 'faex';   {Extensions folder alias}
      kExportedFolderAliasType      = 'faet';   {export folder alias}
      kDropFolderAliasType          = 'fadr';   {drop folder alias}
      kSharedFolderAliasType        = 'fash';   {shared folder alias}
      kMountedFolderAliasType       = 'famn';   {mounted folder alias}

Data Types

TYPE  {Finder information records in the volume catalog file}
      FInfo =
      RECORD
         fdType:           OSType;        {file type}
         fdCreator:        OSType;        {file creator}
         fdFlags:          Integer;       {Finder flags}
         fdLocation:       Point;         {file's location in window}
         fdFldr:           Integer;       {directory that contains file}
      END;

      FXInfo =
      RECORD
         fdIconID:         Integer;       {icon ID}
         fdUnused:         ARRAY[1..3] OF Integer; 
                                          {unused but reserved 6 bytes}
         fdScript:         SignedByte;    {script flag and code}
         fdXFlags:         SignedByte;    {reserved}
         fdComment:        Integer;       {comment ID}
         fdPutAway:        LongInt;       {home directory ID}
      END;

      DInfo =
      RECORD
         frRect:        Rect;             {folder's window rectangle}
         frFlags:       Integer;          {flags}
         frLocation:    Point;            {folder's location in window}
         frView:        Integer;          {folder's view}
      END;

      DXInfo =
      RECORD
         frScroll:      Point;            {scroll position}
         frOpenChain:   LongInt;          {dir ID chain of open folders}
         frScript:      SignedByte;       {script flag and code}
         frXFlags:      SignedByte;       {reserved}
         frComment:     Integer;          {comment ID}
         frPutAway:     LongInt;          {directory ID}
      END;

Routines

Resolving Alias Files

FUNCTION ResolveAliasFile(VAR theSpec: FSSpec; 
resolveAliasChains: Boolean; 
VAR targetIsFolder: Boolean; 
VAR wasAliased: Boolean): OSErr;

Finding Directories

FUNCTION FindFolder(vRefNum: Integer; folderType: OSType; 
createFolder: Boolean; 
VAR foundVRefNum: Integer; 
VAR foundDirID: LongInt): OSErr;

C Summary

Constants

enum {
      /*Gestalt selectors*/
      #define gestaltFindFolderAttr  'fold'     /*selector for FindFolder*/

      /*interpreting Gestalt selector responses*/
      gestaltFindFolderPresent      = 0         /*if this bit is set, */
                                                /* FindFolder is present*/
};
      /*for custom icons*/
#define kCustomIconResource          -16455     /*resource ID for */
                                                /* custom icon*/

      /*Finder flags*/
#define  kIsOnDesk                  0x1         /*unused and reserved in */
                                                /* System 7*/
#define  kColor                     0xE         /*3 bits of color coding*/
#define  kIsShared                  0x40        /*file can be executed by */
                                                /* multiple users */
                                                /* simultaneously*/
#define  kHasBeenInited             0x100       /*file info is in desktop */
                                                /* database*/
#define  kHasCustomIcon             0x400       /*file or directory has a */
                                                /* customized icon*/
#define  kIsStationary              0x800       /*file is a stationery pad*/
#define  kNameLocked                0x1000      /*file or directory can't */
                                                /* be renamed from the */
                                                /* Finder, and icon can't */
                                                /* be changed*/
#define  kHasBundle                 0x2000      /*file has a bundle */
                                                /* resource*/
#define  kIsInvisible               0x4000      /*file or directory is */
                                                /* invisible from Finder */
                                                /* & from Standard File */
                                                /* Package dialog boxes*/
#define  kIsAlias                   0x8000      /*file is an alias file*/

enum {
      /*for Finder flags*/
      fHasBundle                    = 8192,     /*set if file has 'BNDL'*/
      fInvisible                    = 16384     /*set if icon is invisible*/
};    
enum {   
      /*for FindFolder*/
      kOnSystemDisk                 = 0x8000    /*use vRefNum for the */
                                                /* boot disk*/
      #define kCreateFolder            true     /*create folder if it */
                                                /* doesn't exist*/
      #define kDontCreateFolder        false    /*don't create folder*/
      
      /*for special folder types*/
      #define kSystemFolderType      'macs'     /*System Folder*/
      #define kDesktopFolderType     'desk'     /*Desktop Folder*/
      #define kTrashFolderType       'trsh'     /*single-user Trash*/
      #define kWhereToEmptyTrashFolderType
                                     'empt'     /*shared Trash*/
      #define kPrintMonitorDocsFolderType 
                                     'prnt'     /*PrintMonitor Documents*/
      #define kStartupFolderType     'strt'     /*Startup Items*/
      #define kFontsFolderType       'font'     /*Fonts*/
      #define kAppleMenuFolderType   'amnu'     /*Apple Menu Items*/
      #define kControlPanelFolderType 'ctrl'    /*Control Panels*/
      #define kExtensionFolderType   'extn'     /*Extensions*/
      #define kPreferencesFolderType 'pref'     /*Preferences*/
      #define kTemporaryFolderType   'temp'     /*Temporary Items*/
};    
      /*for alias types*/
#define kContainerFolderAliasType    'fdrp'     /*folder alias*/
#define kContainerTrashAliasType     'trsh'     /*Trash alias*/
#define kContainerHardDiskAliasType  'hdsk'     /*hard disk alias*/
#define kContainerFloppyAliasType    'flpy'     /*floppy disk alias*/
#define kContainerServerAliasType    'srvr'     /*server alias*/
#define kApplicationAliasType        'adrp'     /*application alias*/
#define kContainerAliasType          'drop'     /*all other containers*/
#define kSystemFolderAliasType       'fasy'     /*System Folder alias*/
#define kAppleMenuFolderAliasType    'faam'     /*Apple Menu Items folder */
                                                /* alias*/
#define kStartupFolderAliasType      'fast'     /*Startup Items folder */
                                                /* alias*/
#define kPrintMonitorDocsFolderAliasType
                                     'fapn'     /*PrintMonitor Documents */
                                                /* folder alias*/
#define kPreferencesFolderAliasType  'fapf'     /*Preferences folder alias*/
#define kControlPanelFolderAliasType 'fact'     /*Control Panels fldr alias*/
#define kExtensionFolderAliasType    'faex'     /*Extensions folder alias*/
#define kExportedFolderAliasType     'faet'     /*export folder alias*/
#define kDropFolderAliasType         'fadr'     /*drop folder alias*/
#define kSharedFolderAliasType       'fash'     /*shared folder alias*/
#define kMountedFolderAliasType      'famn'     /*mounted folder alias*/

Data Types

struct FInfo {       /*Finder information records in the catalog file*/
      OSType            fdType;        /*file type*/
      OSType            fdCreator;     /*file creator*/
      unsigned short    fdFlags;       /*Finder flags*/
      Point             fdLocation;    /*file's location in window*/
      short             fdFldr;        /*directory that contains file*/
};

struct FXInfo {
      short             fdIconID;      /*icon ID*/
      short             fdUnused[3];   /*unused but reserved 6 bytes*/
      char              fdScript;      /*script flag and code*/
      char              fdXFlags;      /*reserved*/
      short             fdComment;     /*comment ID*/
      long              fdPutAway;     /*home directory ID*/
};
struct DInfo {
      Rect              frRect;        /*folder's window rectangle*/
      unsigned short    frFlags;       /*flags*/
      Point             frLocation;    /*folder's location in window*/
      short             frView;        /*folder's view*/
};

struct DXInfo {
      Point          frScroll;         /*scroll position*/
      long           frOpenChain;      /*directory ID chain of open folders*/
      char           frScript;         /*script flag and code*/
      char           frXFlags;         /*reserved*/
      short          frComment;        /*comment ID*/
      long           frPutAway;        /*directory ID*/
};

Routines

Resolving Alias Files

pascal OSErr ResolveAliasFile 
   (FSSpec *theSpec, Boolean resolveAliasChains,
Boolean *targetIsFolder, Boolean *wasAliased);

Finding Directories

pascal OSErr FindFolder(short vRefNum, OSType folderType, 
Boolean createFolder, short *foundVRefNum,
long *foundDirID);

`Assembly-Language Summary`

Data Structures

FInfo Data Structure
0 `fdType` long file type
4 `fdCreator` long file creator
8 `fdFlags` word Finder flags
10 `fdLocation` long file's location in window
14 `fdFldr` word directory that contains file

FXInfo Data Structure
0 `fdIconID` word icon ID
2 `fdUnused` 6 bytes reserved
8 `fdScript` 1 byte script flag and code
9 `fdXFlags` 1 byte reserved
10 `fdComment` word comment ID
12 `fdPutAway` long home directory ID

DInfo Data Structure
0 `frRect` 8 bytes folder's window rectangle
8 `frFlags` word flags
10 `frLocation` long folder's location in window
14 `frView` word folder's view

DXInfo Data Structure
0 `frScroll` long scroll position
4 `frOpenChain` long directory ID chain of open folders
8 `frScript` 1 byte script flag and code
9 `frXFlags` 1 byte reserved
10 `frComment` word comment ID
12 `frPutAway` long directory ID

Result Codes
noErr 0 No error
nsvErr -35 Volume not found
fnfErr -43 For `FindFolder`: Type not found in `'fld#'` resource, or disk doesn't have System Folder support or System Folder in volume header, or disk does not have desktop database support for Desktop Folder--in all cases, folder not found
For `ResolveAliasFile`: Target not found, but volume and parent
directory found and `theSpec` parameter contains a valid file system specification record
dupFNErr -48 File found instead of folder
dirNFErr -120 Parent directory not found

0	`fdType`	long	file type
4	`fdCreator`	long	file creator
8	`fdFlags`	word	Finder flags
10	`fdLocation`	long	file's location in window
14	`fdFldr`	word	directory that contains file

0	`fdIconID`	word	icon ID
2	`fdUnused`	6 bytes	reserved
8	`fdScript`	1 byte	script flag and code
9	`fdXFlags`	1 byte	reserved
10	`fdComment`	word	comment ID
12	`fdPutAway`	long	home directory ID

0	`frRect`	8 bytes	folder's window rectangle
8	`frFlags`	word	flags
10	`frLocation`	long	folder's location in window
14	`frView`	word	folder's view

0	`frScroll`	long	scroll position
4	`frOpenChain`	long	directory ID chain of open folders
8	`frScript`	1 byte	script flag and code
9	`frXFlags`	1 byte	reserved
10	`frComment`	word	comment ID
12	`frPutAway`	long	directory ID

noErr	0	No error
nsvErr	-35	Volume not found
fnfErr	-43	For `FindFolder`: Type not found in `'fld#'` resource, or disk doesn't have System Folder support or System Folder in volume header, or disk does not have desktop database support for Desktop Folder--in all cases, folder not found For `ResolveAliasFile`: Target not found, but volume and parent directory found and `theSpec` parameter contains a valid file system specification record
dupFNErr	-48	File found instead of folder
dirNFErr	-120	Parent directory not found

Summary of the Finder Interface

Pascal Summary

Constants

Data Types

Routines

Resolving Alias Files

Finding Directories

C Summary

Constants

Data Types

Routines

Resolving Alias Files

Finding Directories

Assembly-Language Summary

Data Structures

FInfo Data Structure 0 fdTypelongfile type 4 fdCreatorlongfile creator 8 fdFlagswordFinder flags 10 fdLocationlongfile's location in window 14 fdFldrworddirectory that contains file

FXInfo Data Structure 0 fdIconIDwordicon ID 2 fdUnused6 bytesreserved 8 fdScript1 bytescript flag and code 9 fdXFlags1 bytereserved 10 fdCommentwordcomment ID 12 fdPutAwaylonghome directory ID

DInfo Data Structure 0 frRect8 bytesfolder's window rectangle 8 frFlagswordflags 10 frLocationlongfolder's location in window 14 frViewwordfolder's view

DXInfo Data Structure 0 frScrolllongscroll position 4 frOpenChainlongdirectory ID chain of open folders 8 frScript1 bytescript flag and code 9 frXFlags1 bytereserved 10 frCommentwordcomment ID 12 frPutAwaylongdirectory ID

`Assembly-Language Summary`

FInfo Data Structure
0 `fdType` long file type
4 `fdCreator` long file creator
8 `fdFlags` word Finder flags
10 `fdLocation` long file's location in window
14 `fdFldr` word directory that contains file

FXInfo Data Structure
0 `fdIconID` word icon ID
2 `fdUnused` 6 bytes reserved
8 `fdScript` 1 byte script flag and code
9 `fdXFlags` 1 byte reserved
10 `fdComment` word comment ID
12 `fdPutAway` long home directory ID

DInfo Data Structure
0 `frRect` 8 bytes folder's window rectangle
8 `frFlags` word flags
10 `frLocation` long folder's location in window
14 `frView` word folder's view

DXInfo Data Structure
0 `frScroll` long scroll position
4 `frOpenChain` long directory ID chain of open folders
8 `frScript` 1 byte script flag and code
9 `frXFlags` 1 byte reserved
10 `frComment` word comment ID
12 `frPutAway` long directory ID