Mercurial > cpython-lru_cache-weakref

annotate Doc/mac/libmacos.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 9e4c12673fab
children b7b012e78da3
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{MacOS} ---
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
2 Access to Mac OS interpreter features}
10334
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{builtin}{MacOS}
10334
61224459bb09 Added \platform annotations.
Fred Drake <fdrake@acm.org>
parents: 8915
diff changeset
5 \platform{Mac}
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
6 \modulesynopsis{Access to Mac OS-specific interpreter features.}
8715
c750c7a21e03 Adjusted to use the new \declaremodule \modulesynopsis \localmoduletable
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
7
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
8
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
9 This module provides access to MacOS specific functionality in the
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
10 Python interpreter, such as how the interpreter eventloop functions
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
11 and the like. Use with care.
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
12
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
13 Note the capitalization of the module name; this is a historical
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
14 artifact.
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
15
18961
eed8a8a8f622 Documented the runtimemodel attribute.
Jack Jansen <jack.jansen@cwi.nl>
parents: 18569
diff changeset
16 \begin{datadesc}{runtimemodel}
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
17 Either \code{'ppc'}, \code{'carbon'} or \code{'macho'}. This
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
18 signifies whether this Python uses the classic (InterfaceLib style)
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
19 runtime model, the Mac OS X compatible CarbonLib style or the Mac OS
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
20 X-only Mach-O style.
18961
eed8a8a8f622 Documented the runtimemodel attribute.
Jack Jansen <jack.jansen@cwi.nl>
parents: 18569
diff changeset
21 \end{datadesc}
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
22
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
23 \begin{excdesc}{Error}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
24 This exception is raised on MacOS generated errors, either from
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
25 functions in this module or from other mac-specific modules like the
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
26 toolbox interfaces. The arguments are the integer error code (the
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
27 \cdata{OSErr} value) and a textual description of the error code.
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
28 Symbolic names for all known error codes are defined in the standard
18980
9e4c12673fab Minor markup nits and slight style-guide conformance changes.
Fred Drake <fdrake@acm.org>
parents: 18961
diff changeset
29 module \refmodule{macerrors}.\refstmodindex{macerrors}
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
30 \end{excdesc}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
31
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
32 \begin{funcdesc}{SetEventHandler}{handler}
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
33 In the inner interpreter loop Python will occasionally check for events,
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
34 unless disabled with \function{ScheduleParams()}. With this function you
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
35 can pass a Python event-handler function that will be called if an event
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
36 is available. The event is passed as parameter and the function should return
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
37 non-zero if the event has been fully processed, otherwise event processing
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
38 continues (by passing the event to the console window package, for instance).
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
39
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
40 Call \function{SetEventHandler()} without a parameter to clear the
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
41 event handler. Setting an event handler while one is already set is an
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
42 error.
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
43 \end{funcdesc}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
44
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 \begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{,
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
46 besocial\optional{, interval\optional{,
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
47 bgyield}}}}}}
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
48 Influence the interpreter inner loop event handling. \var{Interval}
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
49 specifies how often (in seconds, floating point) the interpreter
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
50 should enter the event processing code. When true, \var{doint} causes
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
51 interrupt (command-dot) checking to be done. \var{evtmask} tells the
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
52 interpreter to do event processing for events in the mask (redraws,
6138
f80e763c1717 Changed description of SchedParams() in the following way:
Fred Drake <fdrake@acm.org>
parents: 6092
diff changeset
53 mouseclicks to switch to other applications, etc). The \var{besocial}
f80e763c1717 Changed description of SchedParams() in the following way:
Fred Drake <fdrake@acm.org>
parents: 6092
diff changeset
54 flag gives other processes a chance to run. They are granted minimal
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
55 runtime when Python is in the foreground and \var{bgyield} seconds per
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
56 \var{interval} when Python runs in the background.
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
57
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
58 All parameters are optional, and default to the current value. The return
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
59 value of this function is a tuple with the old values of these options.
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
60 Initial defaults are that all processing is enabled, checking is done every
18569
5e1a14d993b3 Minor changes to match the style guide.
Fred Drake <fdrake@acm.org>
parents: 10334
diff changeset
61 quarter second and the processor is given up for a quarter second when in the
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
62 background.
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
63 \end{funcdesc}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
64
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
65 \begin{funcdesc}{HandleEvent}{ev}
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
66 Pass the event record \var{ev} back to the Python event loop, or
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
67 possibly to the handler for the \code{sys.stdout} window (based on the
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 compiler used to build Python). This allows Python programs that do
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
69 their own event handling to still have some command-period and
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
70 window-switching capability.
6092
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
71
2949c0a40b7b Misc Mac mods by Jack. Added libmacic.tex, and these patches:
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
72 If you attempt to call this function from an event handler set through
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
73 \function{SetEventHandler()} you will get an exception.
2995
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
74 \end{funcdesc}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
75
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
76 \begin{funcdesc}{GetErrorString}{errno}
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
77 Return the textual description of MacOS error code \var{errno}.
1a8d6c7dd560 Documented MacOS module.
Jack Jansen <jack.jansen@cwi.nl>
parents:
diff changeset
78 \end{funcdesc}
3758
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
79
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
80 \begin{funcdesc}{splash}{resid}
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
81 This function will put a splash window
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
82 on-screen, with the contents of the DLOG resource specified by
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
83 \var{resid}. Calling with a zero argument will remove the splash
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
84 screen. This function is useful if you want an applet to post a splash screen
3758
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
85 early in initialization without first having to load numerous
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
86 extension modules.
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
87 \end{funcdesc}
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
88
6961
c5874f6f5431 Reduce warning count from partparse.py.
Fred Drake <fdrake@acm.org>
parents: 6138
diff changeset
89 \begin{funcdesc}{DebugStr}{message \optional{, object}}
4410
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
90 Drop to the low-level debugger with message \var{message}. The
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
91 optional \var{object} argument is not used, but can easily be
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
92 inspected from the debugger.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
93
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
94 Note that you should use this function with extreme care: if no
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
95 low-level debugger like MacsBug is installed this call will crash your
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
96 system. It is intended mainly for developers of Python extension
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
97 modules.
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
98 \end{funcdesc}
4cef23e1dcca Patches for Mac module docs by Jack
Guido van Rossum <guido@python.org>
parents: 3758
diff changeset
99
6961
c5874f6f5431 Reduce warning count from partparse.py.
Fred Drake <fdrake@acm.org>
parents: 6138
diff changeset
100 \begin{funcdesc}{openrf}{name \optional{, mode}}
3758
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
101 Open the resource fork of a file. Arguments are the same as for the
7833
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
102 built-in function \function{open()}. The object returned has file-like
643e9728aa49 Lots of markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
103 semantics, but it is not a Python file object, so there may be subtle
3758
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
104 differences.
b916d614e363 changes by Jack to Mac docs
Guido van Rossum <guido@python.org>
parents: 2995
diff changeset
105 \end{funcdesc}