242 lines
9.0 KiB
TeX
242 lines
9.0 KiB
TeX
\section{\module{macfs} ---
|
|
Various file system services}
|
|
|
|
\declaremodule{standard}{macfs}
|
|
\platform{Mac}
|
|
\modulesynopsis{Support for FSSpec, the Alias Manager,
|
|
\program{finder} aliases, and the Standard File package.}
|
|
|
|
\deprecated{2.3}{The macfs module should be considered obsolete. For
|
|
\class{FSSpec}, \class{FSRef} and \class{Alias} handling use the
|
|
\module{Carbon.File} or \refmodule{Carbon.Folder} module. For file
|
|
dialogs use the \refmodule{EasyDialogs} module. Also, this module is
|
|
known to not work correctly with UFS partitions.}
|
|
|
|
This module provides access to Macintosh \class{FSSpec} handling, the
|
|
Alias Manager, \program{finder} aliases and the Standard File package.
|
|
\index{Macintosh Alias Manager}
|
|
\index{Alias Manager, Macintosh}
|
|
\index{Standard File}
|
|
|
|
Whenever a function or method expects a \var{file} argument, this
|
|
argument can be one of three things:\ (1) a full or partial Macintosh
|
|
pathname, (2) an \class{FSSpec} object or (3) a 3-tuple
|
|
\code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
|
|
\citetitle{Inside Macintosh:\ Files}. An \class{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-Python
|
|
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.
|
|
|
|
\begin{funcdesc}{FSSpec}{file}
|
|
Create an \class{FSSpec} object for the specified file.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{RawFSSpec}{data}
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{RawAlias}{data}
|
|
Create an \class{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 \class{FSSpec} structure over a network.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{FInfo}{}
|
|
Create a zero-filled \class{FInfo} object.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ResolveAliasFile}{file}
|
|
Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
|
|
\var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
|
|
\class{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 \class{FSSpec} object for the file itself
|
|
is returned).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
|
|
Present the user with a standard ``open input file''
|
|
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 \class{FSSpec}
|
|
object and a flag indicating that the user completed the dialog
|
|
without cancelling.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
|
|
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}}
|
|
Present the user with a standard ``open output file''
|
|
dialog. \var{prompt} is the prompt string, and the optional
|
|
\var{default} argument initializes the output file name. The function
|
|
returns an \class{FSSpec} object and a flag indicating that the user
|
|
completed the dialog without cancelling.
|
|
\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 \class{FSSpec} object and
|
|
a success-indicator.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{SetFolder}{\optional{fsspec}}
|
|
Set the folder that is initially presented to the user when one of
|
|
the file selection dialogs is presented. \var{fsspec} should point to
|
|
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
|
|
current directory, i.e. what \function{os.getcwd()} returns.
|
|
|
|
Note that starting with System 7.5 the user can change Standard File
|
|
behaviour with the ``general controls'' control panel, thereby making
|
|
this call inoperative.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{FindFolder}{where, which, create}
|
|
Locates one of the ``special'' folders that Mac OS knows about, such as
|
|
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
|
|
does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
|
|
|
|
The constants for \var{where} and \var{which} can be obtained from the
|
|
standard module \var{Carbon.Folders}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
|
|
Return a minimal \class{alias} object that points to the given file, which
|
|
must be specified as a full pathname. This is the only way to create an
|
|
\class{Alias} pointing to a non-existing file.
|
|
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{FindApplication}{creator}
|
|
Locate the application with 4-character creator code \var{creator}. The
|
|
function returns an \class{FSSpec} object pointing to the application.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{FSSpec Objects \label{fsspec-objects}}
|
|
|
|
\begin{memberdesc}[FSSpec]{data}
|
|
The raw data from the FSSpec object, suitable for passing
|
|
to other applications, for instance.
|
|
\end{memberdesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{as_pathname}{}
|
|
Return the full pathname of the file described by the \class{FSSpec}
|
|
object.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{as_tuple}{}
|
|
Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
|
|
the file described by the \class{FSSpec} object.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
|
|
Create an Alias object pointing to the file described by this
|
|
FSSpec. If the optional \var{file} parameter is present the alias
|
|
will be relative to that file, otherwise it will be absolute.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
|
|
Create a minimal alias pointing to this file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{GetCreatorType}{}
|
|
Return the 4-character creator and type of the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
|
|
Set the 4-character creator and type of the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{GetFInfo}{}
|
|
Return a \class{FInfo} object describing the finder info for the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
|
|
Set the finder info for the file to the values given as \var{finfo}
|
|
(an \class{FInfo} object).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{GetDates}{}
|
|
Return a tuple with three floating point values representing the
|
|
creation date, modification date and backup date of the file.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
|
|
Set the creation, modification and backup date of the file. The values
|
|
are in the standard floating point format used for times throughout
|
|
Python.
|
|
\end{methoddesc}
|
|
|
|
|
|
\subsection{Alias Objects \label{alias-objects}}
|
|
|
|
\begin{memberdesc}[Alias]{data}
|
|
The raw data for the Alias record, suitable for storing in a resource
|
|
or transmitting to other programs.
|
|
\end{memberdesc}
|
|
|
|
\begin{methoddesc}[Alias]{Resolve}{\optional{file}}
|
|
Resolve the alias. If the alias was created as a relative alias you
|
|
should pass the file relative to which it is. Return the FSSpec for
|
|
the file pointed to and a flag indicating whether the \class{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.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Alias]{GetInfo}{num}
|
|
An interface to the \C{} routine \cfunction{GetAliasInfo()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
|
|
Update the alias to point to the \var{file} given. If \var{file2} is
|
|
present a relative alias will be created.
|
|
\end{methoddesc}
|
|
|
|
Note that it is currently not possible to directly manipulate a
|
|
resource as an \class{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
|
|
\member{data} value from the \class{Alias} object and modifying the
|
|
resource.
|
|
|
|
|
|
\subsection{FInfo Objects \label{finfo-objects}}
|
|
|
|
See \citetitle{Inside Macintosh: Files} for a complete description of what
|
|
the various fields mean.
|
|
|
|
\begin{memberdesc}[FInfo]{Creator}
|
|
The 4-character creator code of the file.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[FInfo]{Type}
|
|
The 4-character type code of the file.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[FInfo]{Flags}
|
|
The finder flags for the file as 16-bit integer. The bit values in
|
|
\var{Flags} are defined in standard module \module{MACFS}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[FInfo]{Location}
|
|
A Point giving the position of the file's icon in its folder.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[FInfo]{Fldr}
|
|
The folder the file is in (as an integer).
|
|
\end{memberdesc}
|