Doc/mac/libmacfs.tex

   1 \section{Built-in Module \sectcode{macfs}}
   2 \bimodindex{macfs}
   3
   4 \renewcommand{\indexsubitem}{(in module macfs)}
   5
   6 This module provides access to macintosh FSSpec handling, the Alias
   7 Manager, finder aliases and the Standard File package.
   8
   9 Whenever a function or method expects a \var{file} argument, this
  10 argument can be one of three things:\ (1) a full or partial Macintosh
  11 pathname, (2) an FSSpec object or (3) a 3-tuple \code{(wdRefNum,
  12 parID, name)} as described in Inside Mac VI\@. A description of aliases
  13 and the standard file package can also be found there.
  14
  15 \begin{funcdesc}{FSSpec}{file}
  16 Create an FSSpec object for the specified file.
  17 \end{funcdesc}
  18
  19 \begin{funcdesc}{RawFSSpec}{data}
  20 Create an FSSpec object given the raw data for the C structure for the
  21 FSSpec as a string.  This is mainly useful if you have obtained an
  22 FSSpec structure over a network.
  23 \end{funcdesc}
  24
  25 \begin{funcdesc}{RawAlias}{data}
  26 Create an Alias object given the raw data for the C structure for the
  27 alias as a string.  This is mainly useful if you have obtained an
  28 FSSpec structure over a network.
  29 \end{funcdesc}
  30
  31 \begin{funcdesc}{FInfo}{}
  32 Create a zero-filled FInfo object.
  33 \end{funcdesc}
  34
  35 \begin{funcdesc}{ResolveAliasFile}{file}
  36 Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, \var{isfolder},
  37 \var{aliased})} where \var{fsspec} is the resulting FSSpec object,
  38 \var{isfolder} is true if \var{fsspec} points to a folder and
  39 \var{aliased} is true if the file was an alias in the first place
  40 (otherwise the FSSpec object for the file itself is returned).
  41 \end{funcdesc}
  42
  43 \begin{funcdesc}{StandardGetFile}{\optional{type\, ...}}
  44 Present the user with a standard ``open input file''
  45 dialog. Optionally, you can pass up to four 4-char file types to limit
  46 the files the user can choose from. The function returns an FSSpec
  47 object and a flag indicating that the user completed the dialog
  48 without cancelling.
  49 \end{funcdesc}
  50
  51 \begin{funcdesc}{PromptGetFile}{prompt\optional{\, type\, ...}}
  52 Similar to \var{StandardGetFile} but allows you to specify a prompt.
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{StandardPutFile}{prompt\, \optional{default}}
  56 Present the user with a standard ``open output file''
  57 dialog. \var{prompt} is the prompt string, and the optional
  58 \var{default} argument initializes the output file name. The function
  59 returns an FSSpec object and a flag indicating that the user completed
  60 the dialog without cancelling.
  61 \end{funcdesc}
  62
  63 \begin{funcdesc}{GetDirectory}{\optional{prompt}}
  64 Present the user with a non-standard ``select a directory''
  65 dialog. \var{prompt} is the prompt string, and the optional.
  66 Return an FSSpec object and a success-indicator.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{FindFolder}{where\, which\, create}
  70 Locates one of the ``special'' folders that MacOS knows about, such as
  71 the trash or the Preferences folder. \var{Where} is the disk to
  72 search, \var{which} is the 4-char string specifying which folder to
  73 locate. Setting \var{create} causes the folder to be created if it
  74 does not exist. Returns a \code{(vrefnum, dirid)} tuple.
  75
  76 The constants for \var{where} and \var{which} can be obtained from the
  77 standard module \var{MACFS}.
  78 \end{funcdesc}
  79
  80 \subsection{FSSpec objects}
  81
  82 \renewcommand{\indexsubitem}{(FSSpec object attribute)}
  83 \begin{datadesc}{data}
  84 The raw data from the FSSpec object, suitable for passing
  85 to other applications, for instance.
  86 \end{datadesc}
  87
  88 \renewcommand{\indexsubitem}{(FSSpec object method)}
  89 \begin{funcdesc}{as_pathname}{}
  90 Return the full pathname of the file described by the FSSpec object.
  91 \end{funcdesc}
  92
  93 \begin{funcdesc}{as_tuple}{}
  94 Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of the file described
  95 by the FSSpec object.
  96 \end{funcdesc}
  97
  98 \begin{funcdesc}{NewAlias}{\optional{file}}
  99 Create an Alias object pointing to the file described by this
 100 FSSpec. If the optional \var{file} parameter is present the alias
 101 will be relative to that file, otherwise it will be absolute.
 102 \end{funcdesc}
 103
 104 \begin{funcdesc}{NewAliasMinimal}{}
 105 Create a minimal alias pointing to this file.
 106 \end{funcdesc}
 107
 108 \begin{funcdesc}{GetCreatorType}{}
 109 Return the 4-char creator and type of the file.
 110 \end{funcdesc}
 111
 112 \begin{funcdesc}{SetCreatorType}{creator\, type}
 113 Set the 4-char creator and type of the file.
 114 \end{funcdesc}
 115
 116 \begin{funcdesc}{GetFInfo}{}
 117 Return a FInfo object describing the finder info for the file.
 118 \end{funcdesc}
 119
 120 \begin{funcdesc}{SetFInfo}{finfo}
 121 Set the finder info for the file to the values specified in the
 122 \var{finfo} object.
 123 \end{funcdesc}
 124
 125 \subsection{alias objects}
 126
 127 \renewcommand{\indexsubitem}{(alias object attribute)}
 128 \begin{datadesc}{data}
 129 The raw data for the Alias record, suitable for storing in a resource
 130 or transmitting to other programs.
 131 \end{datadesc}
 132
 133 \renewcommand{\indexsubitem}{(alias object method)}
 134 \begin{funcdesc}{Resolve}{\optional{file}}
 135 Resolve the alias. If the alias was created as a relative alias you
 136 should pass the file relative to which it is. Return the FSSpec for
 137 the file pointed to and a flag indicating whether the alias object
 138 itself was modified during the search process.
 139 \end{funcdesc}
 140
 141 \begin{funcdesc}{GetInfo}{num}
 142 An interface to the C routine \code{GetAliasInfo()}.
 143 \end{funcdesc}
 144
 145 \begin{funcdesc}{Update}{file\, \optional{file2}}
 146 Update the alias to point to the \var{file} given. If \var{file2} is
 147 present a relative alias will be created.
 148 \end{funcdesc}
 149
 150 Note that it is currently not possible to directly manipulate a resource
 151 as an alias object. Hence, after calling \var{Update} or after
 152 \var{Resolve} indicates that the alias has changed the Python program
 153 is responsible for getting the \var{data} from the alias object and
 154 modifying the resource.
 155
 156
 157 \subsection{FInfo objects}
 158
 159 See Inside Mac for a complete description of what the various fields
 160 mean.
 161
 162 \renewcommand{\indexsubitem}{(FInfo object attribute)}
 163 \begin{datadesc}{Creator}
 164 The 4-char creator code of the file.
 165 \end{datadesc}
 166
 167 \begin{datadesc}{Type}
 168 The 4-char type code of the file.
 169 \end{datadesc}
 170
 171 \begin{datadesc}{Flags}
 172 The finder flags for the file as 16-bit integer. The bit values in
 173 \var{Flags} are defined in standard module \var{MACFS}.
 174 \end{datadesc}
 175
 176 \begin{datadesc}{Location}
 177 A Point giving the position of the file's icon in its folder.
 178 \end{datadesc}
 179
 180 \begin{datadesc}{Fldr}
 181 The folder the file is in (as an integer).
 182 \end{datadesc}