Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{MacOS}} |
| 2 | \bimodindex{MacOS} |
| 3 | |
| 4 | \renewcommand{\indexsubitem}{(in module MacOS)} |
| 5 | |
| 6 | This module provides access to MacOS specific functionality in the |
| 7 | python interpreter, such as how the interpreter eventloop functions |
| 8 | and the like. Use with care. |
| 9 | |
| 10 | Note the capitalisation of the module name, this is a historical |
| 11 | artefact. |
| 12 | |
| 13 | \begin{excdesc}{Error} |
| 14 | This exception is raised on MacOS generated errors, either from |
| 15 | functions in this module or from other mac-specific modules like the |
| 16 | toolbox interfaces. The arguments are the integer error code (the |
| 17 | \var{OSErr} value) and a textual description of the error code. |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 18 | Symbolic names for all known error codes are defined in the standard |
| 19 | module \var{macerrors}. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 20 | \end{excdesc} |
| 21 | |
| 22 | \begin{funcdesc}{SetHighLevelEventHandler}{handler} |
| 23 | Pass a python function that will be called upon reception of a |
| 24 | high-level event. The previous handler is returned. The handler |
| 25 | function is called with the event as argument. |
| 26 | |
| 27 | Note that your event handler is currently only called dependably if |
| 28 | your main event loop is in \var{stdwin}. |
| 29 | \end{funcdesc} |
| 30 | |
| 31 | \begin{funcdesc}{AcceptHighLevelEvent}{} |
| 32 | Read a high-level event. The return value is a tuple \code{(sender, |
| 33 | refcon, data)}. |
| 34 | \end{funcdesc} |
| 35 | |
| 36 | \begin{funcdesc}{SetScheduleTimes}{fgi\, fgy \optional{\, bgi\, bgy}} |
| 37 | Controls how often the interpreter checks the event queue and how |
| 38 | long it will yield the processor to other processes. \var{fgi} |
| 39 | specifies after how many clicks (one click is one 60th of a second) |
| 40 | the interpreter should check the event queue, and \var{fgy} specifies |
| 41 | for how many clicks the CPU should be yielded when in the |
| 42 | foreground. The optional \var{bgi} and \var{bgy} allow you to specify |
| 43 | different values to use when python runs in the background, otherwise |
| 44 | the background values will be set the the same as the foreground |
| 45 | values. The function returns nothing. |
| 46 | |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 47 | The default values, which are based on minimal empirical testing, are 12, 1, 6 |
| 48 | and 2 respectively. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 49 | \end{funcdesc} |
| 50 | |
| 51 | \begin{funcdesc}{EnableAppswitch}{onoff} |
| 52 | Enable or disable the python event loop, based on the value of |
| 53 | \var{onoff}. The old value is returned. If the event loop is disabled |
| 54 | no time is granted to other applications, checking for command-period |
| 55 | is not performed and it is impossible to switch applications. This |
| 56 | should only be used by programs providing their own complete event |
| 57 | loop. |
| 58 | |
| 59 | Note that based on the compiler used to build python it is still |
| 60 | possible to loose events even with the python event loop disabled. If |
| 61 | you have a \code{sys.stdout} window its handler will often also look |
| 62 | in the event queue. Making sure nothing is ever printed works around |
| 63 | this. |
| 64 | \end{funcdesc} |
| 65 | |
| 66 | \begin{funcdesc}{HandleEvent}{ev} |
| 67 | Pass the event record \code{ev} back to the python event loop, or |
| 68 | possibly to the handler for the \code{sys.stdout} window (based on the |
| 69 | compiler used to build python). This allows python programs that do |
| 70 | their own event handling to still have some command-period and |
| 71 | window-switching capability. |
| 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{GetErrorString}{errno} |
| 75 | Return the textual description of MacOS error code \var{errno}. |
| 76 | \end{funcdesc} |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 77 | |
| 78 | \begin{funcdesc}{splash}{resid} |
| 79 | This function will put a splash window |
| 80 | on-screen, with the contents of the DLOG resource specified by |
| 81 | \code{resid}. Calling with a zero argument will remove the splash |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 82 | screen. This function is useful if you want an applet to post a splash screen |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 83 | early in initialization without first having to load numerous |
| 84 | extension modules. |
| 85 | \end{funcdesc} |
| 86 | |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 87 | \begin{funcdesc}{DebugStr}{message \optional{\, object}} |
| 88 | Drop to the low-level debugger with message \var{message}. The |
| 89 | optional \var{object} argument is not used, but can easily be |
| 90 | inspected from the debugger. |
| 91 | |
| 92 | Note that you should use this function with extreme care: if no |
| 93 | low-level debugger like MacsBug is installed this call will crash your |
| 94 | system. It is intended mainly for developers of Python extension |
| 95 | modules. |
| 96 | \end{funcdesc} |
| 97 | |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 98 | \begin{funcdesc}{openrf}{name \optional{\, mode}} |
| 99 | Open the resource fork of a file. Arguments are the same as for the |
| 100 | builtin function \code{open}. The object returned has file-like |
| 101 | semantics, but it is not a python file object, so there may be subtle |
| 102 | differences. |
| 103 | \end{funcdesc} |