libmacfs.tex 8.99 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
\section{\module{macfs} ---
2
         Various file system services}
3

4
\declaremodule{standard}{macfs}
5
  \platform{Mac}
Fred Drake's avatar
Fred Drake committed
6 7
\modulesynopsis{Support for FSSpec, the Alias Manager,
                \program{finder} aliases, and the Standard File package.}
8

9 10
\deprecated{2.3}{The macfs module should be considered obsolete. For
\class{FSSpec}, \class{FSRef} and \class{Alias} handling use the
Fred Drake's avatar
Fred Drake committed
11
\module{Carbon.File} or \refmodule{Carbon.Folder} module. For file
12 13
dialogs use the \refmodule{EasyDialogs} module.  Also, this module is
known to not work correctly with UFS partitions.}
Jack Jansen's avatar
Jack Jansen committed
14

Fred Drake's avatar
Fred Drake committed
15 16
This module provides access to Macintosh \class{FSSpec} handling, the
Alias Manager, \program{finder} aliases and the Standard File package.
Fred Drake's avatar
Fred Drake committed
17 18 19
\index{Macintosh Alias Manager}
\index{Alias Manager, Macintosh}
\index{Standard File}
Jack Jansen's avatar
Jack Jansen committed
20 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 27 28 29 30 31
a non-existing file, as long as the folder containing the file exists.
Under MacPython the same is true for a pathname, but not under unix-Pyton
because of the way pathnames and FSRefs works. See Apple's documentation
for details.

A description of aliases and the
32 33
Standard File package can also be found there.

Jack Jansen's avatar
Jack Jansen committed
34
\begin{funcdesc}{FSSpec}{file}
35
Create an \class{FSSpec} object for the specified file.
Jack Jansen's avatar
Jack Jansen committed
36 37 38
\end{funcdesc}

\begin{funcdesc}{RawFSSpec}{data}
39 40 41
Create an \class{FSSpec} object given the raw data for the \C{}
structure for the \class{FSSpec} as a string.  This is mainly useful
if you have obtained an \class{FSSpec} structure over a network.
Jack Jansen's avatar
Jack Jansen committed
42 43 44
\end{funcdesc}

\begin{funcdesc}{RawAlias}{data}
45
Create an \class{Alias} object given the raw data for the \C{}
Fred Drake's avatar
Fred Drake committed
46
structure for the alias as a string.  This is mainly useful if you
47
have obtained an \class{FSSpec} structure over a network.
Jack Jansen's avatar
Jack Jansen committed
48 49
\end{funcdesc}

50
\begin{funcdesc}{FInfo}{}
51
Create a zero-filled \class{FInfo} object.
52 53
\end{funcdesc}

Jack Jansen's avatar
Jack Jansen committed
54
\begin{funcdesc}{ResolveAliasFile}{file}
Fred Drake's avatar
Fred Drake committed
55 56
Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
57
\class{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
Fred Drake's avatar
Fred Drake committed
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
Fred Drake's avatar
Fred Drake committed
60
is returned).
Jack Jansen's avatar
Jack Jansen committed
61 62
\end{funcdesc}

63
\begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
64
Present the user with a standard ``open input file''
Fred Drake's avatar
Fred Drake committed
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}
Jack Jansen's avatar
Jack Jansen committed
67 68 69 70
object and a flag indicating that the user completed the dialog
without cancelling.
\end{funcdesc}

71
\begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
Fred Drake's avatar
Fred Drake committed
72
Similar to \function{StandardGetFile()} but allows you to specify a
73
prompt which will be displayed at the top of the dialog.
74 75
\end{funcdesc}

76
\begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
Jack Jansen's avatar
Jack Jansen committed
77 78
Present the user with a standard ``open output file''
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
Fred Drake's avatar
Fred Drake committed
81
completed the dialog without cancelling.
Jack Jansen's avatar
Jack Jansen committed
82 83
\end{funcdesc}

84
\begin{funcdesc}{GetDirectory}{\optional{prompt}}
85 86 87
Present the user with a non-standard ``select a directory'' dialog.  You
have to first open the directory before clicking on the ``select current
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.
Jack Jansen's avatar
Jack Jansen committed
90 91
\end{funcdesc}

Guido van Rossum's avatar
Guido van Rossum committed
92 93
\begin{funcdesc}{SetFolder}{\optional{fsspec}}
Set the folder that is initially presented to the user when one of
Fred Drake's avatar
Fred Drake committed
94
the file selection dialogs is presented. \var{fsspec} should point to
Guido van Rossum's avatar
Guido van Rossum committed
95 96
a file in the folder, not the folder itself (the file need not exist,
though). If no argument is passed the folder will be set to the
Fred Drake's avatar
Fred Drake committed
97
current directory, i.e. what \function{os.getcwd()} returns.
Guido van Rossum's avatar
Guido van Rossum committed
98

Fred Drake's avatar
Fred Drake committed
99
Note that starting with System 7.5 the user can change Standard File
100
behaviour with the ``general controls'' control panel, thereby making
Guido van Rossum's avatar
Guido van Rossum committed
101 102 103
this call inoperative.
\end{funcdesc}

104
\begin{funcdesc}{FindFolder}{where, which, create}
Fred Drake's avatar
Fred Drake committed
105
Locates one of the ``special'' folders that Mac OS knows about, such as
Fred Drake's avatar
Fred Drake committed
106 107
the trash or the Preferences folder. \var{where} is the disk to
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
Fred Drake's avatar
Fred Drake committed
109
does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
110 111 112

The constants for \var{where} and \var{which} can be obtained from the
standard module \var{Carbon.Folders}.
113
\end{funcdesc}
114

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.
119

120 121
\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 126
\end{funcdesc}

127

Fred Drake's avatar
Fred Drake committed
128
\subsection{FSSpec Objects \label{fsspec-objects}}
Jack Jansen's avatar
Jack Jansen committed
129

Fred Drake's avatar
Fred Drake committed
130
\begin{memberdesc}[FSSpec]{data}
Jack Jansen's avatar
Jack Jansen committed
131 132
The raw data from the FSSpec object, suitable for passing
to other applications, for instance.
Fred Drake's avatar
Fred Drake committed
133
\end{memberdesc}
Jack Jansen's avatar
Jack Jansen committed
134

Fred Drake's avatar
Fred Drake committed
135
\begin{methoddesc}[FSSpec]{as_pathname}{}
136
Return the full pathname of the file described by the \class{FSSpec}
Fred Drake's avatar
Fred Drake committed
137 138
object.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
139

Fred Drake's avatar
Fred Drake committed
140 141
\begin{methoddesc}[FSSpec]{as_tuple}{}
Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
142
the file described by the \class{FSSpec} object.
Fred Drake's avatar
Fred Drake committed
143
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
144

Fred Drake's avatar
Fred Drake committed
145
\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
Jack Jansen's avatar
Jack Jansen committed
146
Create an Alias object pointing to the file described by this
147
FSSpec. If the optional \var{file} parameter is present the alias
Jack Jansen's avatar
Jack Jansen committed
148
will be relative to that file, otherwise it will be absolute.
Fred Drake's avatar
Fred Drake committed
149
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
150

Fred Drake's avatar
Fred Drake committed
151
\begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
Jack Jansen's avatar
Jack Jansen committed
152
Create a minimal alias pointing to this file.
Fred Drake's avatar
Fred Drake committed
153
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
154

Fred Drake's avatar
Fred Drake committed
155 156 157
\begin{methoddesc}[FSSpec]{GetCreatorType}{}
Return the 4-character creator and type of the file.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
158

Fred Drake's avatar
Fred Drake committed
159 160 161
\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
Set the 4-character creator and type of the file.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
162

Fred Drake's avatar
Fred Drake committed
163
\begin{methoddesc}[FSSpec]{GetFInfo}{}
164
Return a \class{FInfo} object describing the finder info for the file.
Fred Drake's avatar
Fred Drake committed
165
\end{methoddesc}
166

Fred Drake's avatar
Fred Drake committed
167 168
\begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
Set the finder info for the file to the values given as \var{finfo}
169
(an \class{FInfo} object).
Fred Drake's avatar
Fred Drake committed
170
\end{methoddesc}
171

Fred Drake's avatar
Fred Drake committed
172
\begin{methoddesc}[FSSpec]{GetDates}{}
173 174
Return a tuple with three floating point values representing the
creation date, modification date and backup date of the file.
Fred Drake's avatar
Fred Drake committed
175
\end{methoddesc}
176

Fred Drake's avatar
Fred Drake committed
177
\begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
178 179 180
Set the creation, modification and backup date of the file. The values
are in the standard floating point format used for times throughout
Python.
Fred Drake's avatar
Fred Drake committed
181 182
\end{methoddesc}

183

184
\subsection{Alias Objects \label{alias-objects}}
Jack Jansen's avatar
Jack Jansen committed
185

Fred Drake's avatar
Fred Drake committed
186
\begin{memberdesc}[Alias]{data}
Jack Jansen's avatar
Jack Jansen committed
187 188
The raw data for the Alias record, suitable for storing in a resource
or transmitting to other programs.
Fred Drake's avatar
Fred Drake committed
189
\end{memberdesc}
Jack Jansen's avatar
Jack Jansen committed
190

Fred Drake's avatar
Fred Drake committed
191
\begin{methoddesc}[Alias]{Resolve}{\optional{file}}
Jack Jansen's avatar
Jack Jansen committed
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 196 197
itself was modified during the search process. If the file does
not exist but the path leading up to it does exist a valid fsspec
is returned.
Fred Drake's avatar
Fred Drake committed
198
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
199

Fred Drake's avatar
Fred Drake committed
200 201 202
\begin{methoddesc}[Alias]{GetInfo}{num}
An interface to the \C{} routine \cfunction{GetAliasInfo()}.
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
203

204
\begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
Jack Jansen's avatar
Jack Jansen committed
205 206
Update the alias to point to the \var{file} given. If \var{file2} is
present a relative alias will be created.
Fred Drake's avatar
Fred Drake committed
207
\end{methoddesc}
Jack Jansen's avatar
Jack Jansen committed
208

Fred Drake's avatar
Fred Drake committed
209
Note that it is currently not possible to directly manipulate a
210
resource as an \class{Alias} object. Hence, after calling
Fred Drake's avatar
Fred Drake committed
211 212
\method{Update()} or after \method{Resolve()} indicates that the alias
has changed the Python program is responsible for getting the
213
\member{data} value from the \class{Alias} object and modifying the
Fred Drake's avatar
Fred Drake committed
214
resource.
Jack Jansen's avatar
Jack Jansen committed
215 216


217
\subsection{FInfo Objects \label{finfo-objects}}
218

219
See \citetitle{Inside Macintosh: Files} for a complete description of what
Fred Drake's avatar
Fred Drake committed
220
the various fields mean.
221

Fred Drake's avatar
Fred Drake committed
222 223 224
\begin{memberdesc}[FInfo]{Creator}
The 4-character creator code of the file.
\end{memberdesc}
225

Fred Drake's avatar
Fred Drake committed
226 227 228
\begin{memberdesc}[FInfo]{Type}
The 4-character type code of the file.
\end{memberdesc}
229

Fred Drake's avatar
Fred Drake committed
230
\begin{memberdesc}[FInfo]{Flags}
231
The finder flags for the file as 16-bit integer. The bit values in
Fred Drake's avatar
Fred Drake committed
232 233
\var{Flags} are defined in standard module \module{MACFS}.
\end{memberdesc}
234

Fred Drake's avatar
Fred Drake committed
235
\begin{memberdesc}[FInfo]{Location}
236
A Point giving the position of the file's icon in its folder.
Fred Drake's avatar
Fred Drake committed
237
\end{memberdesc}
238

Fred Drake's avatar
Fred Drake committed
239
\begin{memberdesc}[FInfo]{Fldr}
240
The folder the file is in (as an integer).
Fred Drake's avatar
Fred Drake committed
241
\end{memberdesc}