Doc/mac/libmacos.tex

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