diff options
Diffstat (limited to 'Doc/mac/libmacfs.tex')
| -rw-r--r-- | Doc/mac/libmacfs.tex | 62 |
1 files changed, 32 insertions, 30 deletions
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex index fcb342c..a548fef 100644 --- a/Doc/mac/libmacfs.tex +++ b/Doc/mac/libmacfs.tex @@ -1,11 +1,15 @@ \section{\module{macfs} --- Various file system services} -\declaremodule{builtin}{macfs} +\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 +Carbon.File or Carbon.Folder module. For file dialogs use the +\module{EasyDialogs} module.} This module provides access to Macintosh FSSpec handling, the Alias Manager, \program{finder} aliases and the Standard File package. @@ -15,9 +19,9 @@ Manager, \program{finder} aliases and the Standard File package. 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 \pytype{FSSpec} object or (3) a 3-tuple +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 \pytype{FSSpec} can point to +\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-Pyton because of the way pathnames and FSRefs works. See Apple's documentation @@ -26,42 +30,39 @@ 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.} - \begin{funcdesc}{FSSpec}{file} -Create an \pytype{FSSpec} object for the specified file. +Create an \class{FSSpec} object for the specified file. \end{funcdesc} \begin{funcdesc}{RawFSSpec}{data} -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. +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 \pytype{Alias} object given the raw data for the \C{} +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 \pytype{FSSpec} structure over a network. +have obtained an \class{FSSpec} structure over a network. \end{funcdesc} \begin{funcdesc}{FInfo}{} -Create a zero-filled \pytype{FInfo} object. +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 -\pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points +\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 \pytype{FSSpec} object for the file itself +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 \pytype{FSSpec} +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} @@ -75,7 +76,7 @@ prompt which will be displayed at the top of the dialog. 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 \pytype{FSSpec} object and a flag indicating that the user +returns an \class{FSSpec} object and a flag indicating that the user completed the dialog without cancelling. \end{funcdesc} @@ -83,7 +84,7 @@ completed the dialog without cancelling. 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 +displayed at the top of the dialog. Return an \class{FSSpec} object and a success-indicator. \end{funcdesc} @@ -105,20 +106,21 @@ 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 \pytype{alias} object that points to the given file, which +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 -\pytype{Alias} pointing to a non-existing file. +\class{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} \begin{funcdesc}{FindApplication}{creator} Locate the application with 4-character creator code \var{creator}. The -function returns an \pytype{FSSpec} object pointing to the application. +function returns an \class{FSSpec} object pointing to the application. \end{funcdesc} @@ -130,13 +132,13 @@ to other applications, for instance. \end{memberdesc} \begin{methoddesc}[FSSpec]{as_pathname}{} -Return the full pathname of the file described by the \pytype{FSSpec} +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 \pytype{FSSpec} object. +the file described by the \class{FSSpec} object. \end{methoddesc} \begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}} @@ -158,12 +160,12 @@ Set the 4-character creator and type of the file. \end{methoddesc} \begin{methoddesc}[FSSpec]{GetFInfo}{} -Return a \pytype{FInfo} object describing the finder info for the file. +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 \pytype{FInfo} object). +(an \class{FInfo} object). \end{methoddesc} \begin{methoddesc}[FSSpec]{GetDates}{} @@ -188,7 +190,7 @@ or transmitting to other programs. \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 \pytype{Alias} object +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. @@ -204,10 +206,10 @@ present a relative alias will be created. \end{methoddesc} Note that it is currently not possible to directly manipulate a -resource as an \pytype{Alias} object. Hence, after calling +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 \pytype{Alias} object and modifying the +\member{data} value from the \class{Alias} object and modifying the resource. |