| \section{\module{MacOS} --- |
| Access to Mac OS interpreter features} |
| |
| \declaremodule{builtin}{MacOS} |
| \platform{Mac} |
| \modulesynopsis{Access to Mac OS-specific interpreter features.} |
| |
| |
| This module provides access to MacOS specific functionality in the |
| Python interpreter, such as how the interpreter eventloop functions |
| and the like. Use with care. |
| |
| Note the capitalization of the module name; this is a historical |
| artifact. |
| |
| \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. |
| \end{datadesc} |
| |
| \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. |
| Symbolic names for all known error codes are defined in the standard |
| module \refmodule{macerrors}.\refstmodindex{macerrors} |
| \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). |
| |
| Call \function{SetEventHandler()} without a parameter to clear the |
| event handler. Setting an event handler while one is already set is an |
| error. |
| \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. |
| |
| 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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{HandleEvent}{ev} |
| Pass the event record \var{ev} back to the Python event loop, or |
| possibly to the handler for the \code{sys.stdout} window (based on the |
| compiler used to build Python). This allows Python programs that do |
| 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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{GetErrorString}{errno} |
| Return the textual description of MacOS error code \var{errno}. |
| \end{funcdesc} |
| |
| \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 |
| screen. This function is useful if you want an applet to post a splash screen |
| early in initialization without first having to load numerous |
| extension modules. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{DebugStr}{message \optional{, object}} |
| 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}} |
| 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 |
| differences. |
| \end{funcdesc} |