Doc/mac/libmacfs.tex

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