Doc/mac/libmacfs.tex

   1 \section{\module{macfs} ---
   2          Various file system services}
   3
   4 \declaremodule{standard}{macfs}
   5   \platform{Mac}
   6 \modulesynopsis{Support for FSSpec, the Alias Manager,
   7                 \program{finder} aliases, and the Standard File package.}
   8
   9 \deprecated{2.3}{The macfs module should be considered obsolete. For
  10 \class{FSSpec}, \class{FSRef} and \class{Alias} handling use the
  11 \module{Carbon.File} or \refmodule{Carbon.Folder} module. For file
  12 dialogs use the \refmodule{EasyDialogs} module.  Also, this module is
  13 known to not work correctly with UFS partitions.}
  14
  15 This module provides access to Macintosh \class{FSSpec} handling, the
  16 Alias Manager, \program{finder} aliases and the Standard File package.
  17 \index{Macintosh Alias Manager}
  18 \index{Alias Manager, Macintosh}
  19 \index{Standard File}
  20
  21 Whenever a function or method expects a \var{file} argument, this
  22 argument can be one of three things:\ (1) a full or partial Macintosh
  23 pathname, (2) an \class{FSSpec} object or (3) a 3-tuple
  24 \code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
  25 \citetitle{Inside Macintosh:\ Files}. An \class{FSSpec} can point to
  26 a non-existing file, as long as the folder containing the file exists.
  27 Under MacPython the same is true for a pathname, but not under unix-Pyton
  28 because of the way pathnames and FSRefs works. See Apple's documentation
  29 for details.
  30
  31 A description of aliases and the
  32 Standard File package can also be found there.
  33
  34 \begin{funcdesc}{FSSpec}{file}
  35 Create an \class{FSSpec} object for the specified file.
  36 \end{funcdesc}
  37
  38 \begin{funcdesc}{RawFSSpec}{data}
  39 Create an \class{FSSpec} object given the raw data for the \C{}
  40 structure for the \class{FSSpec} as a string.  This is mainly useful
  41 if you have obtained an \class{FSSpec} structure over a network.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{RawAlias}{data}
  45 Create an \class{Alias} object given the raw data for the \C{}
  46 structure for the alias as a string.  This is mainly useful if you
  47 have obtained an \class{FSSpec} structure over a network.
  48 \end{funcdesc}
  49
  50 \begin{funcdesc}{FInfo}{}
  51 Create a zero-filled \class{FInfo} object.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{ResolveAliasFile}{file}
  55 Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
  56 \var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
  57 \class{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
  58 to a folder and \var{aliased} is true if the file was an alias in the
  59 first place (otherwise the \class{FSSpec} object for the file itself
  60 is returned).
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
  64 Present the user with a standard ``open input file''
  65 dialog. Optionally, you can pass up to four 4-character file types to limit
  66 the files the user can choose from. The function returns an \class{FSSpec}
  67 object and a flag indicating that the user completed the dialog
  68 without cancelling.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
  72 Similar to \function{StandardGetFile()} but allows you to specify a
  73 prompt which will be displayed at the top of the dialog.
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
  77 Present the user with a standard ``open output file''
  78 dialog. \var{prompt} is the prompt string, and the optional
  79 \var{default} argument initializes the output file name. The function
  80 returns an \class{FSSpec} object and a flag indicating that the user
  81 completed the dialog without cancelling.
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{GetDirectory}{\optional{prompt}}
  85 Present the user with a non-standard ``select a directory'' dialog.  You
  86 have to first open the directory before clicking on the ``select current
  87 directory'' button. \var{prompt} is the prompt string which will be
  88 displayed at the top of the dialog. Return an \class{FSSpec} object and
  89 a success-indicator.
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{SetFolder}{\optional{fsspec}}
  93 Set the folder that is initially presented to the user when one of
  94 the file selection dialogs is presented. \var{fsspec} should point to
  95 a file in the folder, not the folder itself (the file need not exist,
  96 though). If no argument is passed the folder will be set to the
  97 current directory, i.e. what \function{os.getcwd()} returns.
  98
  99 Note that starting with System 7.5 the user can change Standard File
 100 behaviour with the ``general controls'' control panel, thereby making
 101 this call inoperative.
 102 \end{funcdesc}
 103
 104 \begin{funcdesc}{FindFolder}{where, which, create}
 105 Locates one of the ``special'' folders that Mac OS knows about, such as
 106 the trash or the Preferences folder. \var{where} is the disk to
 107 search, \var{which} is the 4-character string specifying which folder to
 108 locate. Setting \var{create} causes the folder to be created if it
 109 does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
 110
 111 The constants for \var{where} and \var{which} can be obtained from the
 112 standard module \var{Carbon.Folders}.
 113 \end{funcdesc}
 114
 115 \begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
 116 Return a minimal \class{alias} object that points to the given file, which
 117 must be specified as a full pathname. This is the only way to create an
 118 \class{Alias} pointing to a non-existing file.
 119
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{FindApplication}{creator}
 123 Locate the application with 4-character creator code \var{creator}. The
 124 function returns an \class{FSSpec} object pointing to the application.
 125 \end{funcdesc}
 126
 127
 128 \subsection{FSSpec Objects \label{fsspec-objects}}
 129
 130 \begin{memberdesc}[FSSpec]{data}
 131 The raw data from the FSSpec object, suitable for passing
 132 to other applications, for instance.
 133 \end{memberdesc}
 134
 135 \begin{methoddesc}[FSSpec]{as_pathname}{}
 136 Return the full pathname of the file described by the \class{FSSpec}
 137 object.
 138 \end{methoddesc}
 139
 140 \begin{methoddesc}[FSSpec]{as_tuple}{}
 141 Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
 142 the file described by the \class{FSSpec} object.
 143 \end{methoddesc}
 144
 145 \begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
 146 Create an Alias object pointing to the file described by this
 147 FSSpec. If the optional \var{file} parameter is present the alias
 148 will be relative to that file, otherwise it will be absolute.
 149 \end{methoddesc}
 150
 151 \begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
 152 Create a minimal alias pointing to this file.
 153 \end{methoddesc}
 154
 155 \begin{methoddesc}[FSSpec]{GetCreatorType}{}
 156 Return the 4-character creator and type of the file.
 157 \end{methoddesc}
 158
 159 \begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
 160 Set the 4-character creator and type of the file.
 161 \end{methoddesc}
 162
 163 \begin{methoddesc}[FSSpec]{GetFInfo}{}
 164 Return a \class{FInfo} object describing the finder info for the file.
 165 \end{methoddesc}
 166
 167 \begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
 168 Set the finder info for the file to the values given as \var{finfo}
 169 (an \class{FInfo} object).
 170 \end{methoddesc}
 171
 172 \begin{methoddesc}[FSSpec]{GetDates}{}
 173 Return a tuple with three floating point values representing the
 174 creation date, modification date and backup date of the file.
 175 \end{methoddesc}
 176
 177 \begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
 178 Set the creation, modification and backup date of the file. The values
 179 are in the standard floating point format used for times throughout
 180 Python.
 181 \end{methoddesc}
 182
 183
 184 \subsection{Alias Objects \label{alias-objects}}
 185
 186 \begin{memberdesc}[Alias]{data}
 187 The raw data for the Alias record, suitable for storing in a resource
 188 or transmitting to other programs.
 189 \end{memberdesc}
 190
 191 \begin{methoddesc}[Alias]{Resolve}{\optional{file}}
 192 Resolve the alias. If the alias was created as a relative alias you
 193 should pass the file relative to which it is. Return the FSSpec for
 194 the file pointed to and a flag indicating whether the \class{Alias} object
 195 itself was modified during the search process. If the file does
 196 not exist but the path leading up to it does exist a valid fsspec
 197 is returned.
 198 \end{methoddesc}
 199
 200 \begin{methoddesc}[Alias]{GetInfo}{num}
 201 An interface to the \C{} routine \cfunction{GetAliasInfo()}.
 202 \end{methoddesc}
 203
 204 \begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
 205 Update the alias to point to the \var{file} given. If \var{file2} is
 206 present a relative alias will be created.
 207 \end{methoddesc}
 208
 209 Note that it is currently not possible to directly manipulate a
 210 resource as an \class{Alias} object. Hence, after calling
 211 \method{Update()} or after \method{Resolve()} indicates that the alias
 212 has changed the Python program is responsible for getting the
 213 \member{data} value from the \class{Alias} object and modifying the
 214 resource.
 215
 216
 217 \subsection{FInfo Objects \label{finfo-objects}}
 218
 219 See \citetitle{Inside Macintosh: Files} for a complete description of what
 220 the various fields mean.
 221
 222 \begin{memberdesc}[FInfo]{Creator}
 223 The 4-character creator code of the file.
 224 \end{memberdesc}
 225
 226 \begin{memberdesc}[FInfo]{Type}
 227 The 4-character type code of the file.
 228 \end{memberdesc}
 229
 230 \begin{memberdesc}[FInfo]{Flags}
 231 The finder flags for the file as 16-bit integer. The bit values in
 232 \var{Flags} are defined in standard module \module{MACFS}.
 233 \end{memberdesc}
 234
 235 \begin{memberdesc}[FInfo]{Location}
 236 A Point giving the position of the file's icon in its folder.
 237 \end{memberdesc}
 238
 239 \begin{memberdesc}[FInfo]{Fldr}
 240 The folder the file is in (as an integer).
 241 \end{memberdesc}