Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{macfs}} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 2 | \bimodindex{macfs} |
| 3 | |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 4 | \renewcommand{\indexsubitem}{(in module macfs)} |
| 5 | |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 6 | This module provides access to macintosh FSSpec handling, the Alias |
| 7 | Manager, finder aliases and the Standard File package. |
| 8 | |
| 9 | Whenever a function or method expects a \var{file} argument, this |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 10 | argument can be one of three things:\ (1) a full or partial Macintosh |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 11 | pathname, (2) an FSSpec object or (3) a 3-tuple \code{(wdRefNum, |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 12 | parID, name)} as described in Inside Mac VI\@. A description of aliases |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 13 | and the standard file package can also be found there. |
| 14 | |
| 15 | \begin{funcdesc}{FSSpec}{file} |
| 16 | Create an FSSpec object for the specified file. |
| 17 | \end{funcdesc} |
| 18 | |
| 19 | \begin{funcdesc}{RawFSSpec}{data} |
| 20 | Create an FSSpec object given the raw data for the C structure for the |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 21 | FSSpec as a string. This is mainly useful if you have obtained an |
| 22 | FSSpec structure over a network. |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 23 | \end{funcdesc} |
| 24 | |
| 25 | \begin{funcdesc}{RawAlias}{data} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 26 | Create an Alias object given the raw data for the C structure for the |
| 27 | alias as a string. This is mainly useful if you have obtained an |
| 28 | FSSpec structure over a network. |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 29 | \end{funcdesc} |
| 30 | |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 31 | \begin{funcdesc}{FInfo}{} |
| 32 | Create a zero-filled FInfo object. |
| 33 | \end{funcdesc} |
| 34 | |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 35 | \begin{funcdesc}{ResolveAliasFile}{file} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 36 | Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec}, \var{isfolder}, |
| 37 | \var{aliased})} where \var{fsspec} is the resulting FSSpec object, |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 38 | \var{isfolder} is true if \var{fsspec} points to a folder and |
| 39 | \var{aliased} is true if the file was an alias in the first place |
| 40 | (otherwise the FSSpec object for the file itself is returned). |
| 41 | \end{funcdesc} |
| 42 | |
| 43 | \begin{funcdesc}{StandardGetFile}{\optional{type\, ...}} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 44 | Present the user with a standard ``open input file'' |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 45 | dialog. Optionally, you can pass up to four 4-char file types to limit |
| 46 | the files the user can choose from. The function returns an FSSpec |
| 47 | object and a flag indicating that the user completed the dialog |
| 48 | without cancelling. |
| 49 | \end{funcdesc} |
| 50 | |
Jack Jansen | 0e13374 | 1995-08-14 13:39:16 +0000 | [diff] [blame] | 51 | \begin{funcdesc}{PromptGetFile}{prompt\optional{\, type\, ...}} |
| 52 | Similar to \var{StandardGetFile} but allows you to specify a prompt. |
| 53 | \end{funcdesc} |
| 54 | |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 55 | \begin{funcdesc}{StandardPutFile}{prompt\, \optional{default}} |
| 56 | Present the user with a standard ``open output file'' |
| 57 | dialog. \var{prompt} is the prompt string, and the optional |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 58 | \var{default} argument initializes the output file name. The function |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 59 | returns an FSSpec object and a flag indicating that the user completed |
| 60 | the dialog without cancelling. |
| 61 | \end{funcdesc} |
| 62 | |
Jack Jansen | 0e13374 | 1995-08-14 13:39:16 +0000 | [diff] [blame] | 63 | \begin{funcdesc}{GetDirectory}{\optional{prompt}} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 64 | Present the user with a non-standard ``select a directory'' |
Jack Jansen | 0e13374 | 1995-08-14 13:39:16 +0000 | [diff] [blame] | 65 | dialog. \var{prompt} is the prompt string, and the optional. |
| 66 | Return an FSSpec object and a success-indicator. |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 67 | \end{funcdesc} |
| 68 | |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 69 | \begin{funcdesc}{FindFolder}{where\, which\, create} |
| 70 | Locates one of the ``special'' folders that MacOS knows about, such as |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame^] | 71 | the trash or the Preferences folder. \var{Where} is the disk to |
| 72 | search, \var{which} is the 4-char string specifying which folder to |
| 73 | locate. Setting \var{create} causes the folder to be created if it |
| 74 | does not exist. Returns a \code{(vrefnum, dirid)} tuple. |
| 75 | |
| 76 | The constants for \var{where} and \var{which} can be obtained from the |
| 77 | standard module \var{MACFS}. |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 78 | \end{funcdesc} |
| 79 | |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 80 | \subsection{FSSpec objects} |
| 81 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 82 | \renewcommand{\indexsubitem}{(FSSpec object attribute)} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 83 | \begin{datadesc}{data} |
| 84 | The raw data from the FSSpec object, suitable for passing |
| 85 | to other applications, for instance. |
| 86 | \end{datadesc} |
| 87 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 88 | \renewcommand{\indexsubitem}{(FSSpec object method)} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 89 | \begin{funcdesc}{as_pathname}{} |
| 90 | Return the full pathname of the file described by the FSSpec object. |
| 91 | \end{funcdesc} |
| 92 | |
| 93 | \begin{funcdesc}{as_tuple}{} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 94 | Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of the file described |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 95 | by the FSSpec object. |
| 96 | \end{funcdesc} |
| 97 | |
| 98 | \begin{funcdesc}{NewAlias}{\optional{file}} |
| 99 | Create an Alias object pointing to the file described by this |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 100 | FSSpec. If the optional \var{file} parameter is present the alias |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 101 | will be relative to that file, otherwise it will be absolute. |
| 102 | \end{funcdesc} |
| 103 | |
| 104 | \begin{funcdesc}{NewAliasMinimal}{} |
| 105 | Create a minimal alias pointing to this file. |
| 106 | \end{funcdesc} |
| 107 | |
| 108 | \begin{funcdesc}{GetCreatorType}{} |
| 109 | Return the 4-char creator and type of the file. |
| 110 | \end{funcdesc} |
| 111 | |
| 112 | \begin{funcdesc}{SetCreatorType}{creator\, type} |
| 113 | Set the 4-char creator and type of the file. |
| 114 | \end{funcdesc} |
| 115 | |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 116 | \begin{funcdesc}{GetFInfo}{} |
| 117 | Return a FInfo object describing the finder info for the file. |
| 118 | \end{funcdesc} |
| 119 | |
| 120 | \begin{funcdesc}{SetFInfo}{finfo} |
| 121 | Set the finder info for the file to the values specified in the |
| 122 | \var{finfo} object. |
| 123 | \end{funcdesc} |
| 124 | |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 125 | \subsection{alias objects} |
| 126 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 127 | \renewcommand{\indexsubitem}{(alias object attribute)} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 128 | \begin{datadesc}{data} |
| 129 | The raw data for the Alias record, suitable for storing in a resource |
| 130 | or transmitting to other programs. |
| 131 | \end{datadesc} |
| 132 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 133 | \renewcommand{\indexsubitem}{(alias object method)} |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 134 | \begin{funcdesc}{Resolve}{\optional{file}} |
| 135 | Resolve the alias. If the alias was created as a relative alias you |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 136 | should pass the file relative to which it is. Return the FSSpec for |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 137 | the file pointed to and a flag indicating whether the alias object |
| 138 | itself was modified during the search process. |
| 139 | \end{funcdesc} |
| 140 | |
| 141 | \begin{funcdesc}{GetInfo}{num} |
| 142 | An interface to the C routine \code{GetAliasInfo()}. |
| 143 | \end{funcdesc} |
| 144 | |
| 145 | \begin{funcdesc}{Update}{file\, \optional{file2}} |
| 146 | Update the alias to point to the \var{file} given. If \var{file2} is |
| 147 | present a relative alias will be created. |
| 148 | \end{funcdesc} |
| 149 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 150 | Note that it is currently not possible to directly manipulate a resource |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 151 | as an alias object. Hence, after calling \var{Update} or after |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 152 | \var{Resolve} indicates that the alias has changed the Python program |
Jack Jansen | e4be9be | 1995-02-28 15:46:09 +0000 | [diff] [blame] | 153 | is responsible for getting the \var{data} from the alias object and |
| 154 | modifying the resource. |
| 155 | |
| 156 | |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 157 | \subsection{FInfo objects} |
| 158 | |
| 159 | See Inside Mac for a complete description of what the various fields |
| 160 | mean. |
| 161 | |
| 162 | \renewcommand{\indexsubitem}{(FInfo object attribute)} |
| 163 | \begin{datadesc}{Creator} |
| 164 | The 4-char creator code of the file. |
| 165 | \end{datadesc} |
| 166 | |
| 167 | \begin{datadesc}{Type} |
| 168 | The 4-char type code of the file. |
| 169 | \end{datadesc} |
| 170 | |
| 171 | \begin{datadesc}{Flags} |
Jack Jansen | da53c52 | 1995-10-10 14:43:20 +0000 | [diff] [blame^] | 172 | The finder flags for the file as 16-bit integer. The bit values in |
| 173 | \var{Flags} are defined in standard module \var{MACFS}. |
Jack Jansen | e164bd8 | 1995-08-10 11:53:14 +0000 | [diff] [blame] | 174 | \end{datadesc} |
| 175 | |
| 176 | \begin{datadesc}{Location} |
| 177 | A Point giving the position of the file's icon in its folder. |
| 178 | \end{datadesc} |
| 179 | |
| 180 | \begin{datadesc}{Fldr} |
| 181 | The folder the file is in (as an integer). |
| 182 | \end{datadesc} |