cpython/Doc/mac/libmacfs.tex

239 lines
8.8 KiB
TeX
Raw Normal View History

1998-08-10 15:40:22 -03:00
\section{\module{macfs} ---
1999-03-02 12:37:17 -04:00
Various file system services}
1999-03-02 12:37:17 -04:00
\declaremodule{builtin}{macfs}
\platform{Mac}
1998-11-25 16:07:35 -04:00
\modulesynopsis{Support for FSSpec, the Alias Manager,
\program{finder} aliases, and the Standard File package.}
1995-02-28 11:46:09 -04:00
This module provides access to Macintosh FSSpec handling, the Alias
1998-04-04 02:23:02 -04:00
Manager, \program{finder} aliases and the Standard File package.
\index{Macintosh Alias Manager}
\index{Alias Manager, Macintosh}
\index{Standard File}
1995-02-28 11:46:09 -04:00
Whenever a function or method expects a \var{file} argument, this
1995-03-13 06:03:32 -04:00
argument can be one of three things:\ (1) a full or partial Macintosh
pathname, (2) an \pytype{FSSpec} object or (3) a 3-tuple
\code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
\citetitle{Inside Macintosh:\ Files}. An \pytype{FSSpec} can point to
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
Standard File package can also be found there.
\note{A module, \refmodule{macfsn}, is auto-imported to replace
StandardFile calls in \module{macfs} with NavServices calls.}
1995-02-28 11:46:09 -04:00
\begin{funcdesc}{FSSpec}{file}
1998-04-04 02:23:02 -04:00
Create an \pytype{FSSpec} object for the specified file.
1995-02-28 11:46:09 -04:00
\end{funcdesc}
\begin{funcdesc}{RawFSSpec}{data}
1998-04-04 02:23:02 -04:00
Create an \pytype{FSSpec} object given the raw data for the \C{}
structure for the \pytype{FSSpec} as a string. This is mainly useful
if you have obtained an \pytype{FSSpec} structure over a network.
1995-02-28 11:46:09 -04:00
\end{funcdesc}
\begin{funcdesc}{RawAlias}{data}
1998-04-04 02:23:02 -04:00
Create an \pytype{Alias} object given the raw data for the \C{}
structure for the alias as a string. This is mainly useful if you
have obtained an \pytype{FSSpec} structure over a network.
1995-02-28 11:46:09 -04:00
\end{funcdesc}
\begin{funcdesc}{FInfo}{}
1998-04-04 02:23:02 -04:00
Create a zero-filled \pytype{FInfo} object.
\end{funcdesc}
1995-02-28 11:46:09 -04:00
\begin{funcdesc}{ResolveAliasFile}{file}
1998-04-04 02:23:02 -04:00
Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
\pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
to a folder and \var{aliased} is true if the file was an alias in the
first place (otherwise the \pytype{FSSpec} object for the file itself
is returned).
1995-02-28 11:46:09 -04:00
\end{funcdesc}
\begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
1995-03-13 06:03:32 -04:00
Present the user with a standard ``open input file''
1998-04-04 02:23:02 -04:00
dialog. Optionally, you can pass up to four 4-character file types to limit
the files the user can choose from. The function returns an \pytype{FSSpec}
1995-02-28 11:46:09 -04:00
object and a flag indicating that the user completed the dialog
without cancelling.
\end{funcdesc}
\begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
1998-04-04 02:23:02 -04:00
Similar to \function{StandardGetFile()} but allows you to specify a
prompt which will be displayed at the top of the dialog.
\end{funcdesc}
\begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
1995-02-28 11:46:09 -04:00
Present the user with a standard ``open output file''
dialog. \var{prompt} is the prompt string, and the optional
1995-03-13 06:03:32 -04:00
\var{default} argument initializes the output file name. The function
1998-04-04 02:23:02 -04:00
returns an \pytype{FSSpec} object and a flag indicating that the user
completed the dialog without cancelling.
1995-02-28 11:46:09 -04:00
\end{funcdesc}
\begin{funcdesc}{GetDirectory}{\optional{prompt}}
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
displayed at the top of the dialog. Return an \pytype{FSSpec} object and
a success-indicator.
1995-02-28 11:46:09 -04:00
\end{funcdesc}
1996-07-30 15:22:31 -03:00
\begin{funcdesc}{SetFolder}{\optional{fsspec}}
Set the folder that is initially presented to the user when one of
1998-04-04 02:23:02 -04:00
the file selection dialogs is presented. \var{fsspec} should point to
1996-07-30 15:22:31 -03:00
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
1998-04-04 02:23:02 -04:00
current directory, i.e. what \function{os.getcwd()} returns.
1996-07-30 15:22:31 -03:00
Note that starting with system 7.5 the user can change Standard File
behaviour with the ``general controls'' control panel, thereby making
1996-07-30 15:22:31 -03:00
this call inoperative.
\end{funcdesc}
\begin{funcdesc}{FindFolder}{where, which, create}
Locates one of the ``special'' folders that MacOS knows about, such as
1998-04-04 02:23:02 -04:00
the trash or the Preferences folder. \var{where} is the disk to
search, \var{which} is the 4-character string specifying which folder to
locate. Setting \var{create} causes the folder to be created if it
1998-04-04 02:23:02 -04:00
does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
\end{funcdesc}
\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
1998-04-04 02:23:02 -04:00
Return a minimal \pytype{alias} object that points to the given file, which
must be specified as a full pathname. This is the only way to create an
1998-04-04 02:23:02 -04:00
\pytype{Alias} pointing to a non-existing file.
The constants for \var{where} and \var{which} can be obtained from the
standard module \var{MACFS}.
\end{funcdesc}
1996-10-15 11:37:31 -03:00
\begin{funcdesc}{FindApplication}{creator}
Locate the application with 4-character creator code \var{creator}. The
1998-04-04 02:23:02 -04:00
function returns an \pytype{FSSpec} object pointing to the application.
1996-10-15 11:37:31 -03:00
\end{funcdesc}
1999-03-02 12:37:17 -04:00
2002-01-17 00:44:34 -04:00
\subsection{FSSpec Objects \label{fsspec-objects}}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FSSpec]{data}
1995-02-28 11:46:09 -04:00
The raw data from the FSSpec object, suitable for passing
to other applications, for instance.
1998-04-04 02:23:02 -04:00
\end{memberdesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{as_pathname}{}
Return the full pathname of the file described by the \pytype{FSSpec}
object.
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{as_tuple}{}
Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
the file described by the \pytype{FSSpec} object.
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
1995-02-28 11:46:09 -04:00
Create an Alias object pointing to the file described by this
1995-03-13 06:03:32 -04:00
FSSpec. If the optional \var{file} parameter is present the alias
1995-02-28 11:46:09 -04:00
will be relative to that file, otherwise it will be absolute.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
1995-02-28 11:46:09 -04:00
Create a minimal alias pointing to this file.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{GetCreatorType}{}
Return the 4-character creator and type of the file.
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
Set the 4-character creator and type of the file.
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{GetFInfo}{}
Return a \pytype{FInfo} object describing the finder info for the file.
\end{methoddesc}
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
Set the finder info for the file to the values given as \var{finfo}
(an \pytype{FInfo} object).
\end{methoddesc}
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{GetDates}{}
1996-10-15 11:37:31 -03:00
Return a tuple with three floating point values representing the
creation date, modification date and backup date of the file.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1996-10-15 11:37:31 -03:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
1996-10-15 11:37:31 -03:00
Set the creation, modification and backup date of the file. The values
are in the standard floating point format used for times throughout
Python.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1996-10-15 11:37:31 -03:00
1999-03-02 12:37:17 -04:00
\subsection{Alias Objects \label{alias-objects}}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[Alias]{data}
1995-02-28 11:46:09 -04:00
The raw data for the Alias record, suitable for storing in a resource
or transmitting to other programs.
1998-04-04 02:23:02 -04:00
\end{memberdesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[Alias]{Resolve}{\optional{file}}
1995-02-28 11:46:09 -04:00
Resolve the alias. If the alias was created as a relative alias you
1995-03-13 06:03:32 -04:00
should pass the file relative to which it is. Return the FSSpec for
1998-04-04 02:23:02 -04:00
the file pointed to and a flag indicating whether the \pytype{Alias} object
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.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
\begin{methoddesc}[Alias]{GetInfo}{num}
An interface to the \C{} routine \cfunction{GetAliasInfo()}.
\end{methoddesc}
1995-02-28 11:46:09 -04:00
\begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
1995-02-28 11:46:09 -04:00
Update the alias to point to the \var{file} given. If \var{file2} is
present a relative alias will be created.
1998-04-04 02:23:02 -04:00
\end{methoddesc}
1995-02-28 11:46:09 -04:00
1998-04-04 02:23:02 -04:00
Note that it is currently not possible to directly manipulate a
resource as an \pytype{Alias} object. Hence, after calling
\method{Update()} or after \method{Resolve()} indicates that the alias
has changed the Python program is responsible for getting the
1998-04-07 17:04:27 -03:00
\member{data} value from the \pytype{Alias} object and modifying the
resource.
1995-02-28 11:46:09 -04:00
1999-03-02 12:37:17 -04:00
\subsection{FInfo Objects \label{finfo-objects}}
1999-11-10 12:13:25 -04:00
See \citetitle{Inside Macintosh: Files} for a complete description of what
1998-04-04 02:23:02 -04:00
the various fields mean.
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FInfo]{Creator}
The 4-character creator code of the file.
\end{memberdesc}
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FInfo]{Type}
The 4-character type code of the file.
\end{memberdesc}
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FInfo]{Flags}
The finder flags for the file as 16-bit integer. The bit values in
1998-04-04 02:23:02 -04:00
\var{Flags} are defined in standard module \module{MACFS}.
\end{memberdesc}
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FInfo]{Location}
A Point giving the position of the file's icon in its folder.
1998-04-04 02:23:02 -04:00
\end{memberdesc}
1998-04-04 02:23:02 -04:00
\begin{memberdesc}[FInfo]{Fldr}
The folder the file is in (as an integer).
1998-04-04 02:23:02 -04:00
\end{memberdesc}