Doc/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.
  22 \end{funcdesc}
  23
  24 \begin{funcdesc}{RawAlias}{data}
  25 Create an Alias object given the raw data for the alias.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{ResolveAliasFile}{file}
  29 Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, \var{isfolder},
  30 \var{aliased})} where \var{fsspec} is the resulting FSSpec object,
  31 \var{isfolder} is true if \var{fsspec} points to a folder and
  32 \var{aliased} is true if the file was an alias in the first place
  33 (otherwise the FSSpec object for the file itself is returned).
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{StandardGetFile}{\optional{type\, ...}}
  37 Present the user with a standard ``open input file''
  38 dialog. Optionally, you can pass up to four 4-char file types to limit
  39 the files the user can choose from. The function returns an FSSpec
  40 object and a flag indicating that the user completed the dialog
  41 without cancelling.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{StandardPutFile}{prompt\, \optional{default}}
  45 Present the user with a standard ``open output file''
  46 dialog. \var{prompt} is the prompt string, and the optional
  47 \var{default} argument initializes the output file name. The function
  48 returns an FSSpec object and a flag indicating that the user completed
  49 the dialog without cancelling.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{GetDirectory}{}
  53 Present the user with a non-standard ``select a directory''
  54 dialog. Return an FSSpec object and a success-indicator.
  55 \end{funcdesc}
  56
  57 \subsection{FSSpec objects}
  58
  59 \renewcommand{\indexsubitem}{(FSSpec object method)}
  60 \begin{datadesc}{data}
  61 The raw data from the FSSpec object, suitable for passing
  62 to other applications, for instance.
  63 \end{datadesc}
  64
  65 \begin{funcdesc}{as_pathname}{}
  66 Return the full pathname of the file described by the FSSpec object.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{as_tuple}{}
  70 Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of the file described
  71 by the FSSpec object.
  72 \end{funcdesc}
  73
  74 \begin{funcdesc}{NewAlias}{\optional{file}}
  75 Create an Alias object pointing to the file described by this
  76 FSSpec. If the optional \var{file} parameter is present the alias
  77 will be relative to that file, otherwise it will be absolute.
  78 \end{funcdesc}
  79
  80 \begin{funcdesc}{NewAliasMinimal}{}
  81 Create a minimal alias pointing to this file.
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{GetCreatorType}{}
  85 Return the 4-char creator and type of the file.
  86 \end{funcdesc}
  87
  88 \begin{funcdesc}{SetCreatorType}{creator\, type}
  89 Set the 4-char creator and type of the file.
  90 \end{funcdesc}
  91
  92 \subsection{alias objects}
  93
  94 \renewcommand{\indexsubitem}{(alias object method)}
  95 \begin{datadesc}{data}
  96 The raw data for the Alias record, suitable for storing in a resource
  97 or transmitting to other programs.
  98 \end{datadesc}
  99
 100 \begin{funcdesc}{Resolve}{\optional{file}}
 101 Resolve the alias. If the alias was created as a relative alias you
 102 should pass the file relative to which it is. Return the FSSpec for
 103 the file pointed to and a flag indicating whether the alias object
 104 itself was modified during the search process.
 105 \end{funcdesc}
 106
 107 \begin{funcdesc}{GetInfo}{num}
 108 An interface to the C routine \code{GetAliasInfo()}.
 109 \end{funcdesc}
 110
 111 \begin{funcdesc}{Update}{file\, \optional{file2}}
 112 Update the alias to point to the \var{file} given. If \var{file2} is
 113 present a relative alias will be created.
 114 \end{funcdesc}
 115
 116 Note that it is currently not possible to directly manipulate a resource
 117 as an alias object. Hence, after calling \var{Update} or after
 118 \var{Resolve} indicates that the alias has changed the Python program
 119 is responsible for getting the \var{data} from the alias object and
 120 modifying the resource.
 121
 122