Mercurial > cpython-lru_cache-weakref

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

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 372149779240
children dbc0f2f11414
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{macostools} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
2 Convenience routines for file manipulation}
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
3
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{macostools}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
5 \platform{Mac}
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6 \modulesynopsis{Convenience routines for file manipulation.}
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
7
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
8
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
9 This module contains some convenience routines for file-manipulation
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
10 on the Macintosh.
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
11
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
12 The \module{macostools} module defines the following functions:
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
13
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
14
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
15 \begin{funcdesc}{copy}{src, dst\optional{, createpath\optional{, copytimes}}}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
16 Copy file \var{src} to \var{dst}. The files can be specified as
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
17 pathnames or \pytype{FSSpec} objects. If \var{createpath} is non-zero
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
18 \var{dst} must be a pathname and the folders leading to the
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
19 destination are created if necessary. The method copies data and
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
20 resource fork and some finder information (creator, type, flags) and
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
21 optionally the creation, modification and backup times (default is to
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
22 copy them). Custom icons, comments and icon position are not copied.
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
23 \end{funcdesc}
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
24
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7393
diff changeset
25 \begin{funcdesc}{copytree}{src, dst}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 Recursively copy a file tree from \var{src} to \var{dst}, creating
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
27 folders as needed. \var{src} and \var{dst} should be specified as
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
28 pathnames.
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
29 \end{funcdesc}
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7393
diff changeset
31 \begin{funcdesc}{mkalias}{src, dst}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
32 Create a finder alias \var{dst} pointing to \var{src}. Both may be
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
33 specified as pathnames or \pytype{FSSpec} objects.
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
34 \end{funcdesc}
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
35
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
36 \begin{funcdesc}{touched}{dst}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
37 Tell the finder that some bits of finder-information such as creator
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
38 or type for file \var{dst} has changed. The file can be specified by
15226
487b3502a45b Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
39 pathname or fsspec. This call should tell the finder to redraw the
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
40 files icon.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
41 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
42
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
43 \begin{datadesc}{BUFSIZ}
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
44 The buffer size for \code{copy}, default 1 megabyte.
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
45 \end{datadesc}
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
46
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
47 Note that the process of creating finder aliases is not specified in
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
48 the Apple documentation. Hence, aliases created with \function{mkalias()}
3194
05aeb91e3b90 Documented MACFS, macostools, EasyDialogs and FrameWork modules.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
49 could conceivably have incompatible behaviour in some cases.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
50
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
51
8915
552c6b3aba3d New style section headers.
Fred Drake <fdrake@acm.org>
parents: 8715
diff changeset
52 \section{\module{findertools} ---
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
53 The \program{finder}'s Apple Events interface}
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
54
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
55 \declaremodule{standard}{findertools}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
56 \platform{Mac}
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
57 \modulesynopsis{Wrappers around the \program{finder}'s Apple Events interface.}
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
58
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
59
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
60 This module contains routines that give Python programs access to some
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
61 functionality provided by the finder. They are implemented as wrappers
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
62 around the AppleEvent\index{AppleEvents} interface to the finder.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
63
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
64 All file and folder parameters can be specified either as full
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
65 pathnames or as \pytype{FSSpec} objects.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
66
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
67 The \module{findertools} module defines the following functions:
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
68
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
69
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
70 \begin{funcdesc}{launch}{file}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
71 Tell the finder to launch \var{file}. What launching means depends on the file:
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
72 applications are started, folders are opened and documents are opened
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
73 in the correct application.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
74 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
75
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
76 \begin{funcdesc}{Print}{file}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
77 Tell the finder to print a file (again specified by full pathname or
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
78 \pytype{FSSpec}). The behaviour is identical to selecting the file and using
15226
487b3502a45b Chris Barker <cbarker@jps.net>:
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
79 the print command in the finder's file menu.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
80 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
81
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
82 \begin{funcdesc}{copy}{file, destdir}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
83 Tell the finder to copy a file or folder \var{file} to folder
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
84 \var{destdir}. The function returns an \pytype{Alias} object pointing to
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
85 the new file.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
86 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
87
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
88 \begin{funcdesc}{move}{file, destdir}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
89 Tell the finder to move a file or folder \var{file} to folder
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
90 \var{destdir}. The function returns an \pytype{Alias} object pointing to
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
91 the new file.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
92 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
93
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
94 \begin{funcdesc}{sleep}{}
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
95 Tell the finder to put the Macintosh to sleep, if your machine
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
96 supports it.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
97 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
98
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
99 \begin{funcdesc}{restart}{}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
100 Tell the finder to perform an orderly restart of the machine.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
101 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
102
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
103 \begin{funcdesc}{shutdown}{}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
104 Tell the finder to perform an orderly shutdown of the machine.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3194
diff changeset
105 \end{funcdesc}