cpython/Doc/mac/libmacos.tex

109 lines
4.6 KiB
TeX
Raw Normal View History

1998-08-10 15:40:22 -03:00
\section{\module{MacOS} ---
Access to Mac OS interpreter features}
1999-03-02 12:37:17 -04:00
\declaremodule{builtin}{MacOS}
\platform{Mac}
\modulesynopsis{Access to Mac OS-specific interpreter features.}
1995-08-14 10:40:05 -03:00
This module provides access to MacOS specific functionality in the
Python interpreter, such as how the interpreter eventloop functions
1995-08-14 10:40:05 -03:00
and the like. Use with care.
Note the capitalization of the module name; this is a historical
artifact.
2001-08-03 10:19:56 -03:00
\begin{datadesc}{runtimemodel}
Either \code{'ppc'}, \code{'carbon'} or \code{'macho'}. This
signifies whether this Python uses the classic (InterfaceLib style)
runtime model, the Mac OS X compatible CarbonLib style or the Mac OS
X-only Mach-O style.
2001-08-03 10:19:56 -03:00
\end{datadesc}
1995-08-14 10:40:05 -03:00
\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
\cdata{OSErr} value) and a textual description of the error code.
1996-10-15 11:37:31 -03:00
Symbolic names for all known error codes are defined in the standard
module \refmodule{macerrors}.\refstmodindex{macerrors}
1995-08-14 10:40:05 -03:00
\end{excdesc}
\begin{funcdesc}{SetEventHandler}{handler}
In the inner interpreter loop Python will occasionally check for events,
unless disabled with \function{ScheduleParams()}. With this function you
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).
1995-08-14 10:40:05 -03:00
Call \function{SetEventHandler()} without a parameter to clear the
event handler. Setting an event handler while one is already set is an
error.
1995-08-14 10:40:05 -03:00
\end{funcdesc}
\begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{,
besocial\optional{, interval\optional{,
bgyield}}}}}}
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
interrupt (command-dot) checking to be done. \var{evtmask} tells the
interpreter to do event processing for events in the mask (redraws,
mouseclicks to switch to other applications, etc). The \var{besocial}
flag gives other processes a chance to run. They are granted minimal
runtime when Python is in the foreground and \var{bgyield} seconds per
\var{interval} when Python runs in the background.
1995-08-14 10:40:05 -03:00
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
quarter second and the processor is given up for a quarter second when in the
background.
The most common use case is to call \code{SchedParams(0, 0)} to completely disable
event handling in the interpreter mainloop.
1995-08-14 10:40:05 -03:00
\end{funcdesc}
\begin{funcdesc}{HandleEvent}{ev}
Pass the event record \var{ev} back to the Python event loop, or
1995-08-14 10:40:05 -03:00
possibly to the handler for the \code{sys.stdout} window (based on the
compiler used to build Python). This allows Python programs that do
1995-08-14 10:40:05 -03:00
their own event handling to still have some command-period and
window-switching capability.
If you attempt to call this function from an event handler set through
\function{SetEventHandler()} you will get an exception.
1995-08-14 10:40:05 -03:00
\end{funcdesc}
\begin{funcdesc}{GetErrorString}{errno}
Return the textual description of MacOS error code \var{errno}.
\end{funcdesc}
1996-07-20 23:20:58 -03:00
\begin{funcdesc}{splash}{resid}
This function will put a splash window
on-screen, with the contents of the DLOG resource specified by
\var{resid}. Calling with a zero argument will remove the splash
1996-10-15 11:37:31 -03:00
screen. This function is useful if you want an applet to post a splash screen
1996-07-20 23:20:58 -03:00
early in initialization without first having to load numerous
extension modules.
\end{funcdesc}
\begin{funcdesc}{DebugStr}{message \optional{, object}}
1996-10-15 11:37:31 -03:00
Drop to the low-level debugger with message \var{message}. The
optional \var{object} argument is not used, but can easily be
inspected from the debugger.
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}
\begin{funcdesc}{openrf}{name \optional{, mode}}
1996-07-20 23:20:58 -03:00
Open the resource fork of a file. Arguments are the same as for the
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
1996-07-20 23:20:58 -03:00
differences.
\end{funcdesc}