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