Doc/mac/libmacfs.tex

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