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{'carbon'} or \code{'macho'}.  This
  18 signifies whether this Python uses the Mac OS X and Mac OS 9 compatible
  19 CarbonLib style or the Mac OS
  20 X-only Mach-O style. In earlier versions of Python  the value could
  21 also be \code{'ppc'} for the classic Mac OS 8 runtime model.
  22 \end{datadesc}
  23
  24 \begin{datadesc}{linkmodel}
  25 The way the interpreter has been linked. As extension modules may be
  26 incompatible between linking models, packages could use this information to give
  27 more decent error messages. The value is one of \code{'static'} for a
  28 statically linked Python, \code{'framework'} for Python in a Mac OS X framework,
  29 \code{'shared'} for Python in a standard unix shared library and
  30 \code{'cfm'} for the Mac OS 9-compatible Python.
  31 \end{datadesc}
  32
  33 \begin{excdesc}{Error}
  34 This exception is raised on MacOS generated errors, either from
  35 functions in this module or from other mac-specific modules like the
  36 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}
  40 \end{excdesc}
  41
  42 \begin{funcdesc}{SetEventHandler}{handler}
  43 In the inner interpreter loop Python will occasionally check for events,
  44 unless disabled with \function{ScheduleParams()}. With this function you
  45 can pass a Python event-handler function that will be called if an event
  46 is available. The event is passed as parameter and the function should return
  47 non-zero if the event has been fully processed, otherwise event processing
  48 continues (by passing the event to the console window package, for instance).
  49
  50 Call \function{SetEventHandler()} without a parameter to clear the
  51 event handler. Setting an event handler while one is already set is an
  52 error.
  53
  54 Availability: MacPython-OS9.
  55 \end{funcdesc}
  56
  57 \begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{,
  58                               besocial\optional{, interval\optional{,
  59                               bgyield}}}}}}
  60 Influence the interpreter inner loop event handling. \var{Interval}
  61 specifies how often (in seconds, floating point) the interpreter
  62 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 mouseclicks to switch to other applications, etc). The \var{besocial}
  66 flag gives other processes a chance to run. They are granted minimal
  67 runtime when Python is in the foreground and \var{bgyield} seconds per
  68 \var{interval} when Python runs in the background.
  69
  70 All parameters are optional, and default to the current value. The return
  71 value of this function is a tuple with the old values of these options.
  72 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 The most common use case is to call \code{SchedParams(0, 0)} to completely disable
  77 event handling in the interpreter mainloop.
  78
  79 Availability: MacPython-OS9.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{HandleEvent}{ev}
  83 Pass the event record \var{ev} back to the Python event loop, or
  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
  86 their own event handling to still have some command-period and
  87 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.
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{GetErrorString}{errno}
  96 Return the textual description of MacOS error code \var{errno}.
  97 \end{funcdesc}
  98
  99 \begin{funcdesc}{splash}{resid}
 100 This function will put a splash window
 101 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 early in initialization without first having to load numerous
 105 extension modules.
 106
 107 Availability: MacPython-OS9.
 108 \end{funcdesc}
 109
 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 inspected from the debugger. On Mac OS X the string is simply printed
 114 to stderr.
 115
 116 Note that you should use this function with extreme care: if no
 117 low-level debugger like MacsBug is installed this call will crash your
 118 system. It is intended mainly for developers of Python extension
 119 modules.
 120 \end{funcdesc}
 121
 122 \begin{funcdesc}{SysBeep}{}
 123 Ring the bell.
 124 \end{funcdesc}
 125
 126 \begin{funcdesc}{GetTicks}{}
 127 Get the number of clock ticks (1/60th of a second) since system boot.
 128 \end{funcdesc}
 129
 130 \begin{funcdesc}{GetCreatorAndType}{file}
 131 Return the file creator and file type as two four-character strings.
 132 The \var{file} parameter can be a pathname or an \code{FSSpec} or
 133 \code{FSRef} object.
 134 \end{funcdesc}
 135
 136 \begin{funcdesc}{SetCreatorAndType}{file, creator, type}
 137 Set the file creator and file type.
 138 The \var{file} parameter can be a pathname or an \code{FSSpec} or
 139 \code{FSRef} object. \var{creator} and \var{type} must be four character
 140 strings.
 141 \end{funcdesc}
 142
 143 \begin{funcdesc}{openrf}{name \optional{, mode}}
 144 Open the resource fork of a file. Arguments are the same as for the
 145 built-in function \function{open()}. The object returned has file-like
 146 semantics, but it is not a Python file object, so there may be subtle
 147 differences.
 148 \end{funcdesc}
 149
 150 \begin{funcdesc}{WMAvailable}{}
 151 Checks wether the current process has access to the window manager.
 152 The method will return \code{False} if the window manager is not available,
 153 for instance when running on Mac OS X Server or when logged in via ssh,
 154 or when the current interpreter is not running from a fullblown application
 155 bundle. A script runs from an application bundle either when it has been
 156 started with \program{pythonw} in stead of \program{python} or when running
 157 as an applet.
 158
 159 On Mac OS 9 the method always returns \code{True}.
 160 \end{funcdesc}