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