annotate Doc/mac/libmacfs.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents 376ee174ecd0
children 53fc6ec8a837
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8915
552c6b3aba3d New style section headers.
Fred Drake <fdrake@acm.org>
parents: 8715
diff changeset
1 \section{\module{macfs} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
2 Various file system services}
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
3
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7904
diff changeset
4 \declaremodule{builtin}{macfs}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
5 \platform{Mac}
9534
53325b8f8ce9 Remove bogus \@.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
6 \modulesynopsis{Support for FSSpec, the Alias Manager,
53325b8f8ce9 Remove bogus \@.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
7 \program{finder} aliases, and the Standard File package.}
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7904
diff changeset
8
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
9
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
10 This module provides access to Macintosh FSSpec handling, the Alias
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
11 Manager, \program{finder} aliases and the Standard File package.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
12 \index{Macintosh Alias Manager}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
13 \index{Alias Manager, Macintosh}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
14 \index{Standard File}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
15
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
16 Whenever a function or method expects a \var{file} argument, this
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
17 argument can be one of three things:\ (1) a full or partial Macintosh
15220
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
18 pathname, (2) an \pytype{FSSpec} object or (3) a 3-tuple
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
19 \code{(\var{wdRefNum}, \var{parID}, \var{name})} as described in
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
20 \citetitle{Inside Macintosh:\ Files}. A description of aliases and the
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
21 Standard File package can also be found there.
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
22
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 15220
diff changeset
23 \note{A module, \refmodule{macfsn}, is auto-imported to replace
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 15220
diff changeset
24 StandardFile calls in \module{macfs} with NavServices calls.}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
25
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 \begin{funcdesc}{FSSpec}{file}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
27 Create an \pytype{FSSpec} object for the specified file.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
28 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
29
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30 \begin{funcdesc}{RawFSSpec}{data}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
31 Create an \pytype{FSSpec} object given the raw data for the \C{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
32 structure for the \pytype{FSSpec} as a string. This is mainly useful
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
33 if you have obtained an \pytype{FSSpec} structure over a network.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
34 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
35
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
36 \begin{funcdesc}{RawAlias}{data}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
37 Create an \pytype{Alias} object given the raw data for the \C{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
38 structure for the alias as a string. This is mainly useful if you
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
39 have obtained an \pytype{FSSpec} structure over a network.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
40 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
41
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
42 \begin{funcdesc}{FInfo}{}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
43 Create a zero-filled \pytype{FInfo} object.
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
44 \end{funcdesc}
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
45
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
46 \begin{funcdesc}{ResolveAliasFile}{file}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
47 Resolve an alias file. Returns a 3-tuple \code{(\var{fsspec},
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
48 \var{isfolder}, \var{aliased})} where \var{fsspec} is the resulting
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
49 \pytype{FSSpec} object, \var{isfolder} is true if \var{fsspec} points
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
50 to a folder and \var{aliased} is true if the file was an alias in the
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
51 first place (otherwise the \pytype{FSSpec} object for the file itself
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
52 is returned).
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
53 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
54
14761
c566ac9c52d7 Fix some minor nits about the use of \optional in parameter lists.
Fred Drake <fdrake@acm.org>
parents: 11462
diff changeset
55 \begin{funcdesc}{StandardGetFile}{\optional{type, \moreargs}}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
56 Present the user with a standard ``open input file''
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
57 dialog. Optionally, you can pass up to four 4-character file types to limit
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
58 the files the user can choose from. The function returns an \pytype{FSSpec}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
59 object and a flag indicating that the user completed the dialog
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
60 without cancelling.
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
61 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
62
14761
c566ac9c52d7 Fix some minor nits about the use of \optional in parameter lists.
Fred Drake <fdrake@acm.org>
parents: 11462
diff changeset
63 \begin{funcdesc}{PromptGetFile}{prompt\optional{, type, \moreargs}}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
64 Similar to \function{StandardGetFile()} but allows you to specify a
15220
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
65 prompt which will be displayed at the top of the dialog.
2994
ac0152f63bdd Documented PromptGetFile and optional prompt to GetDirectory.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2941
diff changeset
66 \end{funcdesc}
ac0152f63bdd Documented PromptGetFile and optional prompt to GetDirectory.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2941
diff changeset
67
14761
c566ac9c52d7 Fix some minor nits about the use of \optional in parameter lists.
Fred Drake <fdrake@acm.org>
parents: 11462
diff changeset
68 \begin{funcdesc}{StandardPutFile}{prompt\optional{, default}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
69 Present the user with a standard ``open output file''
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
70 dialog. \var{prompt} is the prompt string, and the optional
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
71 \var{default} argument initializes the output file name. The function
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
72 returns an \pytype{FSSpec} object and a flag indicating that the user
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
73 completed the dialog without cancelling.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
74 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
75
2994
ac0152f63bdd Documented PromptGetFile and optional prompt to GetDirectory.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2941
diff changeset
76 \begin{funcdesc}{GetDirectory}{\optional{prompt}}
15220
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
77 Present the user with a non-standard ``select a directory'' dialog. You
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
78 have to first open the directory before clicking on the ``select current
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
79 directory'' button. \var{prompt} is the prompt string which will be
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
80 displayed at the top of the dialog. Return an \pytype{FSSpec} object and
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
81 a success-indicator.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
82 \end{funcdesc}
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
83
3857
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
84 \begin{funcdesc}{SetFolder}{\optional{fsspec}}
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
85 Set the folder that is initially presented to the user when one of
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
86 the file selection dialogs is presented. \var{fsspec} should point to
3857
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
87 a file in the folder, not the folder itself (the file need not exist,
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
88 though). If no argument is passed the folder will be set to the
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
89 current directory, i.e. what \function{os.getcwd()} returns.
3857
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
90
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
91 Note that starting with system 7.5 the user can change Standard File
15220
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
92 behaviour with the ``general controls'' control panel, thereby making
3857
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
93 this call inoperative.
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
94 \end{funcdesc}
83a95bf70867 Added SetFolder
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
95
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
96 \begin{funcdesc}{FindFolder}{where, which, create}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
97 Locates one of the ``special'' folders that MacOS knows about, such as
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
98 the trash or the Preferences folder. \var{where} is the disk to
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
99 search, \var{which} is the 4-character string specifying which folder to
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2994
diff changeset
100 locate. Setting \var{create} causes the folder to be created if it
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
101 does not exist. Returns a \code{(\var{vrefnum}, \var{dirid})} tuple.
6137
40abf23e168b Added missing "\end{funcdesc}" after FindFolder documentation.
Fred Drake <fdrake@acm.org>
parents: 6092
diff changeset
102 \end{funcdesc}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2994
diff changeset
103
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
104 \begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
105 Return a minimal \pytype{alias} object that points to the given file, which
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
106 must be specified as a full pathname. This is the only way to create an
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
107 \pytype{Alias} pointing to a non-existing file.
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
108
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2994
diff changeset
109 The constants for \var{where} and \var{which} can be obtained from the
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2994
diff changeset
110 standard module \var{MACFS}.
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
111 \end{funcdesc}
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
112
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
113 \begin{funcdesc}{FindApplication}{creator}
15220
3e7016c79daa A bunch of nits fix and some additional information added by Chris
Fred Drake <fdrake@acm.org>
parents: 14761
diff changeset
114 Locate the application with 4-character creator code \var{creator}. The
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
115 function returns an \pytype{FSSpec} object pointing to the application.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
116 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
117
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
118
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
119 \subsection{FSSpec objects \label{fsspec-objects}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
120
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
121 \begin{memberdesc}[FSSpec]{data}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
122 The raw data from the FSSpec object, suitable for passing
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
123 to other applications, for instance.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
124 \end{memberdesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
125
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
126 \begin{methoddesc}[FSSpec]{as_pathname}{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
127 Return the full pathname of the file described by the \pytype{FSSpec}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
128 object.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
129 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
130
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
131 \begin{methoddesc}[FSSpec]{as_tuple}{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
132 Return the \code{(\var{wdRefNum}, \var{parID}, \var{name})} tuple of
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
133 the file described by the \pytype{FSSpec} object.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
134 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
135
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
136 \begin{methoddesc}[FSSpec]{NewAlias}{\optional{file}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
137 Create an Alias object pointing to the file described by this
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
138 FSSpec. If the optional \var{file} parameter is present the alias
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
139 will be relative to that file, otherwise it will be absolute.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
140 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
141
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
142 \begin{methoddesc}[FSSpec]{NewAliasMinimal}{}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
143 Create a minimal alias pointing to this file.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
144 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
145
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
146 \begin{methoddesc}[FSSpec]{GetCreatorType}{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
147 Return the 4-character creator and type of the file.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
148 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
149
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
150 \begin{methoddesc}[FSSpec]{SetCreatorType}{creator, type}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
151 Set the 4-character creator and type of the file.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
152 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
153
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
154 \begin{methoddesc}[FSSpec]{GetFInfo}{}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
155 Return a \pytype{FInfo} object describing the finder info for the file.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
156 \end{methoddesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
157
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
158 \begin{methoddesc}[FSSpec]{SetFInfo}{finfo}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
159 Set the finder info for the file to the values given as \var{finfo}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
160 (an \pytype{FInfo} object).
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
161 \end{methoddesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
162
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
163 \begin{methoddesc}[FSSpec]{GetDates}{}
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
164 Return a tuple with three floating point values representing the
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
165 creation date, modification date and backup date of the file.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
166 \end{methoddesc}
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
167
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
168 \begin{methoddesc}[FSSpec]{SetDates}{crdate, moddate, backupdate}
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
169 Set the creation, modification and backup date of the file. The values
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
170 are in the standard floating point format used for times throughout
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
171 Python.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
172 \end{methoddesc}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
173
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3857
diff changeset
174
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
175 \subsection{Alias Objects \label{alias-objects}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
176
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
177 \begin{memberdesc}[Alias]{data}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
178 The raw data for the Alias record, suitable for storing in a resource
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
179 or transmitting to other programs.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
180 \end{memberdesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
181
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
182 \begin{methoddesc}[Alias]{Resolve}{\optional{file}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
183 Resolve the alias. If the alias was created as a relative alias you
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
184 should pass the file relative to which it is. Return the FSSpec for
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
185 the file pointed to and a flag indicating whether the \pytype{Alias} object
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
186 itself was modified during the search process. If the file does
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
187 not exist but the path leading up to it does exist a valid fsspec
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
188 is returned.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
189 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
190
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
191 \begin{methoddesc}[Alias]{GetInfo}{num}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
192 An interface to the \C{} routine \cfunction{GetAliasInfo()}.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
193 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
194
14761
c566ac9c52d7 Fix some minor nits about the use of \optional in parameter lists.
Fred Drake <fdrake@acm.org>
parents: 11462
diff changeset
195 \begin{methoddesc}[Alias]{Update}{file\optional{, file2}}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
196 Update the alias to point to the \var{file} given. If \var{file2} is
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
197 present a relative alias will be created.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
198 \end{methoddesc}
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
199
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
200 Note that it is currently not possible to directly manipulate a
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
201 resource as an \pytype{Alias} object. Hence, after calling
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
202 \method{Update()} or after \method{Resolve()} indicates that the alias
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
203 has changed the Python program is responsible for getting the
7900
1efee503259e Markup nit.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
204 \member{data} value from the \pytype{Alias} object and modifying the
1efee503259e Markup nit.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
205 resource.
2452
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
206
9efd408fc9f6 Three down, two to go...
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
207
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 9534
diff changeset
208 \subsection{FInfo Objects \label{finfo-objects}}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
209
11462
95a9833b000e Use \citetitle as appropriate.
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
210 See \citetitle{Inside Macintosh: Files} for a complete description of what
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
211 the various fields mean.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
212
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
213 \begin{memberdesc}[FInfo]{Creator}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
214 The 4-character creator code of the file.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
215 \end{memberdesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
216
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
217 \begin{memberdesc}[FInfo]{Type}
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
218 The 4-character type code of the file.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
219 \end{memberdesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
220
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
221 \begin{memberdesc}[FInfo]{Flags}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2994
diff changeset
222 The finder flags for the file as 16-bit integer. The bit values in
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
223 \var{Flags} are defined in standard module \module{MACFS}.
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
224 \end{memberdesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
225
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
226 \begin{memberdesc}[FInfo]{Location}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
227 A Point giving the position of the file's icon in its folder.
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
228 \end{memberdesc}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
229
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
230 \begin{memberdesc}[FInfo]{Fldr}
2941
97f7cfabe07e Documented FindFolder, GetFInfo, SetFInfo and the FInfo object.
Jack Jansen <jack.jansen@cwi.nl>
parents: 2576
diff changeset
231 The folder the file is in (as an integer).
7866
b69fa9d142ca Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
232 \end{memberdesc}