libmacos.tex 6.47 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
\section{\module{MacOS} ---
2
         Access to Mac OS interpreter features}
3

4 5
\declaremodule{builtin}{MacOS}
  \platform{Mac}
6
\modulesynopsis{Access to Mac OS-specific interpreter features.}
7

Jack Jansen's avatar
Jack Jansen committed
8 9

This module provides access to MacOS specific functionality in the
10
Python interpreter, such as how the interpreter eventloop functions
Jack Jansen's avatar
Jack Jansen committed
11 12
and the like. Use with care.

13
Note the capitalization of the module name; this is a historical
14
artifact.
15

16
\begin{datadesc}{runtimemodel}
17 18 19 20 21 22 23 24 25 26 27 28 29 30
Either\code{'carbon'} or \code{'macho'}.  This
signifies whether this Python uses the Mac OS X and Mac OS 9 compatible 
CarbonLib style or the Mac OS
X-only Mach-O style. In earlier versions of Python  the value could
also be \code{'ppc'} for the classic Mac OS 8 runtime model.
\end{datadesc}

\begin{datadesc}{linkmodel}
The way the interpreter has been linked. As extension modules may be
incompatible between linking models, packages could use this information to give
more decent error messages. The value is one of \code{'static'} for a
statically linked Python, \code{'framework'} for Python in a Mac OS X framework,
\code{'shared'} for Python in a standard unix shared library and
\code{'cfm'} for the Mac OS 9-compatible Python.
31
\end{datadesc}
Jack Jansen's avatar
Jack Jansen committed
32 33 34 35 36

\begin{excdesc}{Error}
This exception is raised on MacOS generated errors, either from
functions in this module or from other mac-specific modules like the
toolbox interfaces. The arguments are the integer error code (the
37
\cdata{OSErr} value) and a textual description of the error code.
38
Symbolic names for all known error codes are defined in the standard
39
module \refmodule{macerrors}.\refstmodindex{macerrors}
Jack Jansen's avatar
Jack Jansen committed
40 41
\end{excdesc}

42 43
\begin{funcdesc}{SetEventHandler}{handler}
In the inner interpreter loop Python will occasionally check for events,
44
unless disabled with \function{ScheduleParams()}. With this function you
45 46 47 48
can pass a Python event-handler function that will be called if an event
is available. The event is passed as parameter and the function should return
non-zero if the event has been fully processed, otherwise event processing
continues (by passing the event to the console window package, for instance).
Jack Jansen's avatar
Jack Jansen committed
49

50 51 52
Call \function{SetEventHandler()} without a parameter to clear the
event handler. Setting an event handler while one is already set is an
error.
53 54

Availability: MacPython-OS9.
Jack Jansen's avatar
Jack Jansen committed
55 56
\end{funcdesc}

57 58 59
\begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{,
                              besocial\optional{, interval\optional{,
                              bgyield}}}}}}
60 61 62
Influence the interpreter inner loop event handling. \var{Interval}
specifies how often (in seconds, floating point) the interpreter
should enter the event processing code. When true, \var{doint} causes
63
interrupt (command-dot) checking to be done. \var{evtmask} tells the
64
interpreter to do event processing for events in the mask (redraws,
65 66
mouseclicks to switch to other applications, etc). The \var{besocial}
flag gives other processes a chance to run. They are granted minimal
67 68
runtime when Python is in the foreground and \var{bgyield} seconds per
\var{interval} when Python runs in the background.
Jack Jansen's avatar
Jack Jansen committed
69

70 71 72
All parameters are optional, and default to the current value. The return
value of this function is a tuple with the old values of these options.
Initial defaults are that all processing is enabled, checking is done every
73
quarter second and the processor is given up for a quarter second when in the
74
background.
75 76 77

The most common use case is to call \code{SchedParams(0, 0)} to completely disable
event handling in the interpreter mainloop.
78 79

Availability: MacPython-OS9.
Jack Jansen's avatar
Jack Jansen committed
80 81 82
\end{funcdesc}

\begin{funcdesc}{HandleEvent}{ev}
83
Pass the event record \var{ev} back to the Python event loop, or
Jack Jansen's avatar
Jack Jansen committed
84
possibly to the handler for the \code{sys.stdout} window (based on the
85
compiler used to build Python). This allows Python programs that do
Jack Jansen's avatar
Jack Jansen committed
86 87
their own event handling to still have some command-period and
window-switching capability.
88 89

If you attempt to call this function from an event handler set through
90
\function{SetEventHandler()} you will get an exception.
91 92

Availability: MacPython-OS9.
Jack Jansen's avatar
Jack Jansen committed
93 94 95 96 97
\end{funcdesc}

\begin{funcdesc}{GetErrorString}{errno}
Return the textual description of MacOS error code \var{errno}.
\end{funcdesc}
98 99 100 101

\begin{funcdesc}{splash}{resid}
This function will put a splash window
on-screen, with the contents of the DLOG resource specified by
102
\var{resid}. Calling with a zero argument will remove the splash
103
screen. This function is useful if you want an applet to post a splash screen
104 105
early in initialization without first having to load numerous
extension modules.
106 107

Availability: MacPython-OS9.
108 109
\end{funcdesc}

110
\begin{funcdesc}{DebugStr}{message \optional{, object}}
111
On Mac OS 9, drop to the low-level debugger with message \var{message}. The
112
optional \var{object} argument is not used, but can easily be
113 114
inspected from the debugger. On Mac OS X the string is simply printed
to stderr.
115 116 117 118 119 120 121

Note that you should use this function with extreme care: if no
low-level debugger like MacsBug is installed this call will crash your
system. It is intended mainly for developers of Python extension
modules.
\end{funcdesc}

122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142
\begin{funcdesc}{SysBeep}{}
Ring the bell.
\end{funcdesc}

\begin{funcdesc}{GetTicks}{}
Get the number of clock ticks (1/60th of a second) since system boot.
\end{funcdesc}

\begin{funcdesc}{GetCreatorAndType}{file}
Return the file creator and file type as two four-character strings.
The \var{file} parameter can be a pathname or an \code{FSSpec} or 
\code{FSRef} object.
\end{funcdesc}

\begin{funcdesc}{SetCreatorAndType}{file, creator, type}
Set the file creator and file type.
The \var{file} parameter can be a pathname or an \code{FSSpec} or 
\code{FSRef} object. \var{creator} and \var{type} must be four character
strings.
\end{funcdesc}

143
\begin{funcdesc}{openrf}{name \optional{, mode}}
144
Open the resource fork of a file. Arguments are the same as for the
145 146
built-in function \function{open()}. The object returned has file-like
semantics, but it is not a Python file object, so there may be subtle
147 148
differences.
\end{funcdesc}
149 150 151 152 153 154 155 156 157 158 159 160

\begin{funcdesc}{WMAvailable}{}
Checks wether the current process has access to the window manager.
The method will return \code{False} if the window manager is not available,
for instance when running on Mac OS X Server or when logged in via ssh,
or when the current interpreter is not running from a fullblown application
bundle. A script runs from an application bundle either when it has been
started with \program{pythonw} in stead of \program{python} or when running 
as an applet.

On Mac OS 9 the method always returns \code{True}.
\end{funcdesc}