ref: 57d690c482c7e5f57608befe7cb04797b1bff153
dir: /sys/src/cmd/python/Doc/mac/libmacfs.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}