Doc/libmacfs.tex

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