Fred Drake | c817e27 | 1998-08-10 18:40:22 +0000 | [diff] [blame] | 1 | \section{\module{MacOS} --- |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 2 | Access to Mac OS interpreter features} |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 3 | |
Fred Drake | fe7f3bc | 1998-07-23 17:55:31 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{MacOS} |
Fred Drake | f6863c1 | 1999-03-02 16:37:17 +0000 | [diff] [blame] | 5 | \platform{Mac} |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 6 | \modulesynopsis{Access to Mac OS-specific interpreter features.} |
Fred Drake | fe7f3bc | 1998-07-23 17:55:31 +0000 | [diff] [blame] | 7 | |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 8 | |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 9 | This module provides access to MacOS specific functionality in the |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 10 | Python interpreter, such as how the interpreter eventloop functions |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 11 | and the like. Use with care. |
| 12 | |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 13 | Note the capitalization of the module name; this is a historical |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 14 | artifact. |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 15 | |
Jack Jansen | cb60dae | 2001-08-03 13:19:56 +0000 | [diff] [blame] | 16 | \begin{datadesc}{runtimemodel} |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 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. |
Jack Jansen | cb60dae | 2001-08-03 13:19:56 +0000 | [diff] [blame] | 21 | \end{datadesc} |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 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 |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 27 | \cdata{OSErr} value) and a textual description of the error code. |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 28 | Symbolic names for all known error codes are defined in the standard |
Fred Drake | 30cf118 | 2001-08-03 17:11:33 +0000 | [diff] [blame] | 29 | module \refmodule{macerrors}.\refstmodindex{macerrors} |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 30 | \end{excdesc} |
| 31 | |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 32 | \begin{funcdesc}{SetEventHandler}{handler} |
| 33 | In the inner interpreter loop Python will occasionally check for events, |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 34 | unless disabled with \function{ScheduleParams()}. With this function you |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 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). |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 39 | |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 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. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 43 | \end{funcdesc} |
| 44 | |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 45 | \begin{funcdesc}{SchedParams}{\optional{doint\optional{, evtmask\optional{, |
| 46 | besocial\optional{, interval\optional{, |
| 47 | bgyield}}}}}} |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 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 |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 51 | interrupt (command-dot) checking to be done. \var{evtmask} tells the |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 52 | interpreter to do event processing for events in the mask (redraws, |
Fred Drake | 289f97d | 1997-08-22 13:51:31 +0000 | [diff] [blame] | 53 | mouseclicks to switch to other applications, etc). The \var{besocial} |
| 54 | flag gives other processes a chance to run. They are granted minimal |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 55 | runtime when Python is in the foreground and \var{bgyield} seconds per |
| 56 | \var{interval} when Python runs in the background. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 57 | |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 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 |
Fred Drake | 17f690f | 2001-07-14 02:14:42 +0000 | [diff] [blame] | 61 | quarter second and the processor is given up for a quarter second when in the |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 62 | background. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 63 | \end{funcdesc} |
| 64 | |
| 65 | \begin{funcdesc}{HandleEvent}{ev} |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 66 | Pass the event record \var{ev} back to the Python event loop, or |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 67 | possibly to the handler for the \code{sys.stdout} window (based on the |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 68 | compiler used to build Python). This allows Python programs that do |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 69 | their own event handling to still have some command-period and |
| 70 | window-switching capability. |
Guido van Rossum | e229d86 | 1997-08-18 15:14:26 +0000 | [diff] [blame] | 71 | |
| 72 | If you attempt to call this function from an event handler set through |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 73 | \function{SetEventHandler()} you will get an exception. |
Jack Jansen | ebed45f | 1995-08-14 13:40:05 +0000 | [diff] [blame] | 74 | \end{funcdesc} |
| 75 | |
| 76 | \begin{funcdesc}{GetErrorString}{errno} |
| 77 | Return the textual description of MacOS error code \var{errno}. |
| 78 | \end{funcdesc} |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 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 |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 83 | \var{resid}. Calling with a zero argument will remove the splash |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 84 | 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] | 85 | early in initialization without first having to load numerous |
| 86 | extension modules. |
| 87 | \end{funcdesc} |
| 88 | |
Fred Drake | 671fe9d | 1997-12-29 18:53:31 +0000 | [diff] [blame] | 89 | \begin{funcdesc}{DebugStr}{message \optional{, object}} |
Guido van Rossum | 7e42cab | 1996-10-15 14:37:31 +0000 | [diff] [blame] | 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 | |
Fred Drake | 671fe9d | 1997-12-29 18:53:31 +0000 | [diff] [blame] | 100 | \begin{funcdesc}{openrf}{name \optional{, mode}} |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 101 | Open the resource fork of a file. Arguments are the same as for the |
Fred Drake | 6188592 | 1998-04-03 07:16:46 +0000 | [diff] [blame] | 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 |
Guido van Rossum | 66774a9 | 1996-07-21 02:20:58 +0000 | [diff] [blame] | 104 | differences. |
| 105 | \end{funcdesc} |