Misc Mac mods by Jack. Added libmacic.tex, and these patches:

libmacfs.tex	Document NewAliasMinimalFromFullPath
libmacos.tex	Document SetEventHandler and SchedParams
libmacui.tex	Document asynchronous event handling
libmailbox.tex	Removed mime-turds that somehow got in here

Doc/Makefile

@@ -112,7 +112,7 @@ LIBFILES = lib.tex \
     libuser.tex libanydbm.tex librandom.tex libsite.tex libwhichdb.tex \
     libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \
     libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \
-    libpprint.tex libcode.tex libmimify.tex libre.tex
+    libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex
 
 # Library document
 lib.dvi: $(LIBFILES)

Doc/lib.tex

@@ -195,6 +195,7 @@ to Python and how to embed it in other applications.
 \input{libmacconsole}
 \input{libmacdnr}
 \input{libmacfs}
+\input{libmacic}
 \input{libmacos}
 \input{libmacostools}
 \input{libmactcp}

Doc/lib/lib.tex

@@ -195,6 +195,7 @@ to Python and how to embed it in other applications.
 \input{libmacconsole}
 \input{libmacdnr}
 \input{libmacfs}
+\input{libmacic}
 \input{libmacos}
 \input{libmacostools}
 \input{libmactcp}

Doc/lib/libmailbox.tex

@@ -31,12 +31,10 @@ All implementations of Mailbox objects have one externally visible
 method:
 
 \begin{funcdesc}{next}{}
-Return the next message in the mailbox, as a \code{rfc822.Message} object=
-=2E
+Return the next message in the mailbox, as a \code{rfc822.Message} object.
 Depending on the mailbox implementation the \var{fp} attribute of this
-object may be a true file object or a class instance simulating a file ob=
-ject,
-taking care of things like message boundaries if multiple mail messages a=
-re
+object may be a true file object or a class instance simulating a file object,
+taking care of things like message boundaries if multiple mail messages are
 contained in a single file, etc.
 \end{funcdesc}
+

Doc/libmacfs.tex

@@ -86,6 +86,11 @@ search, \var{which} is the 4-char string specifying which folder to
 locate. Setting \var{create} causes the folder to be created if it
 does not exist. Returns a \code{(vrefnum, dirid)} tuple.
 
+\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
+Return a minimal alias record object that points to the given file, which
+must be specified as a full pathname. This is the only way to create an
+alias record pointing to a non-existing file.
+
 The constants for \var{where} and \var{which} can be obtained from the
 standard module \var{MACFS}.
 \end{funcdesc}
@@ -164,7 +169,9 @@ or transmitting to other programs.
 Resolve the alias. If the alias was created as a relative alias you
 should pass the file relative to which it is. Return the FSSpec for
 the file pointed to and a flag indicating whether the alias object
-itself was modified during the search process. 
+itself was modified during the search process. If the file does
+not exist but the path leading up to it does exist a valid fsspec
+is returned.
 \end{funcdesc}
 
 \begin{funcdesc}{GetInfo}{num}

Doc/libmacic.tex

+\section{Standard Module \sectcode{ic}}
+\bimodindex{ic}
+
+\renewcommand{\indexsubitem}{(in module ic)}
+
+This module provides access to macintosh Internet Config package,
+which stores preferences for Internet programs such as mail address,
+default homepage, etc. Also, Internet Config contains an elaborate set
+of mappings from Macintosh creator/type codes to foreign filename
+extensions plus information on how to transfer files (binary, ascii,
+etc). 
+
+There is a low-level companion module \code{icglue} which provides the
+basic ic access functionality. This low-level module is not
+documented, but the docstrings of the routines document the parameters
+and the routine names are the same as for the Pascal or C API to
+Internet Config, so the standard IC programmers documentation can be
+used if this module is needed.
+
+The \code{ic} module defines the \code{error} exception and symbolic
+names for all error codes IC can produce, see the source for details.
+
+The \code{ic} module defines the following functions:
+
+\begin{funcdesc}{IC}{\optional{signature\, ic}}
+Create an internet config object. The signature is a 4-char creator
+code of the current application (default \code{'Pyth'}) which may
+influence some of ICs settings. The optional \var{ic} argument is a
+low-level \code{icinstance} created beforehand, this may be useful if
+you want to get preferences from a different config file, etc.
+\end{funcdesc}
+
+\begin{funcdesc}{launchurl}{url \optional{\, hint}}
+\end{funcdesc}
+\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
+\end{funcdesc}
+\begin{funcdesc}{mapfile}{file}
+\end{funcdesc}
+\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
+	filename}}
+\end{funcdesc}
+\begin{funcdesc}{settypecreator}{file}
+These functions are ``shortcuts'' to the methods of the same name,
+described below.
+\end{funcdesc}
+
+
+\subsection{IC objects}
+
+IC objects have a mapping interface, hence to obtain the mail address
+you simply get \code{ic['MailAddress']}. Assignment also works, and
+changes the option in the configuration file.
+
+The module knows about various datatypes, and converts the internal IC
+representation to a ``logical'' python datastructure. Running the
+\code{ic} module standalone will run a test program that lists all
+keys and values in your IC database, this will have to server as
+documentation.
+
+If the module does not know how to represent the data it returns an
+instance of the \var{ICOpaqueData} type, with the raw data in its
+\var{data} attribute. Objects of this type are also acceptable values
+for assignment.
+
+Besides the dictionary interface IC objects have the following methods:
+
+\renewcommand{\indexsubitem}{(IC object attribute)}
+
+\begin{funcdesc}{launchurl}{url \optional{\, hint}}
+Parse the given URL, lauch the correct application and pass it the
+URL. The optional \var{hint} can be a scheme name such as
+\code{mailto:}, in which case incomplete URLs are completed with this
+scheme (otherwise incomplete URLs are invalid). 
+\end{funcdesc}
+
+\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
+Find an URL somewhere in \var{data} and return start position, end
+position and the URL. The optional \var{start} and \var{end} can be
+used to limit the search, so for instance if a user clicks in a long
+textfield you can pass the whole textfield and the click-position in
+\var{start} and this routine will return the whole URL in which the
+user clicked. \var{Hint} is again an optional scheme used to complete
+incomplete URLs.
+\end{funcdesc}
+
+\begin{funcdesc}{mapfile}{file}
+Return the mapping entry for the given \var{file}, which can be passed
+as either a filename or an \var{FSSpec} object, and which need not
+exist.
+
+The mapping entry is returned as a tuple \code{(version\, type\,
+creator\, postcreator\, flags\, extension\, appname\, postappname\,
+mimetype\, entryname)}, where \var{version} is the entry version
+number, \var{type} is the 4-char filetype, \var{creator} is the 4-char
+creator type, \var{postcreator} is the 4-char creator code of an
+optional application to post-process the file after downloading,
+\var{flags} are various bits specifying whether to transfer in binary
+or ascii and such, \var{extension} is the filename extension for this
+file type, \var{appname} is the printable name of the application to
+which this file belongs, \var{postappname} is the name of the
+postprocessing application, \var{mimetype} is the MIME type of this
+file and \var{entryname} is the name of this entry.
+\end{funcdesc}
+
+\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
+	filename}}
+Return the mapping entry for files with given 4-char \var{type} and
+\var{creator} codes. The optional \var{filename} may be specified to
+further help finding the correct entry (if the creator code is
+\code{'????'}, for instance).
+
+The mapping entry is returned in the same format as for \var{mapfile}.
+\end{funcdesc}
+
+\begin{funcdesc}{settypecreator}{file}
+Given an existing \var{file}, specified either as a filename or as an
+\var{FSSpec} record, set its creator and type correctly based on its
+extension. The finder is told about the change, so the finder icon
+will be updated quickly.
+\end{funcdesc}

Doc/libmacos.tex

@@ -20,48 +20,35 @@ Symbolic names for all known error codes are defined in the standard
 module \var{macerrors}.
 \end{excdesc}
 
-\begin{funcdesc}{SetHighLevelEventHandler}{handler}
-Pass a python function that will be called upon reception of a
-high-level event. The previous handler is returned. The handler
-function is called with the event as argument.
-
-Note that your event handler is currently only called dependably if
-your main event loop is in \var{stdwin}.
-\end{funcdesc}
-
-\begin{funcdesc}{AcceptHighLevelEvent}{}
-Read a high-level event. The return value is a tuple \code{(sender,
-refcon, data)}.
-\end{funcdesc}
-
-\begin{funcdesc}{SetScheduleTimes}{fgi\, fgy \optional{\, bgi\, bgy}}
-Controls how often the interpreter checks the event queue and how
-long it will yield the processor to other processes. \var{fgi}
-specifies after how many clicks (one click is one 60th of a second)
-the interpreter should check the event queue, and \var{fgy} specifies
-for how many clicks the CPU should be yielded when in the
-foreground. The optional \var{bgi} and \var{bgy} allow you to specify
-different values to use when python runs in the background, otherwise
-the background values will be set the the same as the foreground
-values. The function returns nothing.
-
-The default values, which are based on minimal empirical testing, are 12, 1, 6
-and 2 respectively.
+\begin{funcdesc}{SetEventHandler}{handler}
+In the inner interpreter loop Python will occasionally check for events,
+unless disabled with \var{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 SetEventHandler without parameter to clear the event handler. Setting
+an eventhandler while one is already set is an error.
 \end{funcdesc}
 
-\begin{funcdesc}{EnableAppswitch}{onoff}
-Enable or disable the python event loop, based on the value of
-\var{onoff}. The old value is returned. If the event loop is disabled
-no time is granted to other applications, checking for command-period
-is not performed and it is impossible to switch applications. This
-should only be used by programs providing their own complete event
-loop.
-
-Note that based on the compiler used to build python it is still
-possible to loose events even with the python event loop disabled. If
-you have a \code{sys.stdout} window its handler will often also look
-in the event queue. Making sure nothing is ever printed works around
-this.
+\begin{funcdesc}{SchedParams}{\optional{doint\, evtmask\, besocial\, 
+				interval\, 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). \bar{Besocial}
+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 CPU is given up for a quarter second when in the
+background.
 \end{funcdesc}
 
 \begin{funcdesc}{HandleEvent}{ev}
@@ -70,6 +57,9 @@ 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
+\code{SetEventHandler} you will get an exception.
 \end{funcdesc}
 
 \begin{funcdesc}{GetErrorString}{errno}

Doc/libmacui.tex

@@ -4,7 +4,9 @@
 
 The \code{EasyDialogs} module contains some simple dialogs for
 the Macintosh, modelled after the \code{stdwin} dialogs with similar
-names.
+names. All routines have an optional parameter \var{id} with which you
+can override the DLOG resource used for the dialog, as long as the
+item numbers correspond. See the source for details.
 
 The \code{EasyDialogs} module defines the following functions:
 
@@ -170,6 +172,29 @@ The event loop is split into many small parts, each of which can be
 overridden. The default methods take care of dispatching events to
 windows and dialogs, handling drags and resizes, Apple Events, events
 for non-FrameWork windows, etc.
+
+In general, all event handlers should return 1 if the event is fully
+handled and 0 otherwise (because the front window was not a FrameWork
+window, for instance). This is needed so that update events and such
+can be passed on to other windows like the Sioux console window.
+Calling \code{MacOS.HandleEvent} is not allowed within \var{our_dispatch}
+or its callees, since this may result in an infinite loop if the
+code is called through the python inner-loop event handler.
+\end{funcdesc}
+
+\begin{funcdesc}{asyncevents}{onoff}
+Call this method with a nonzero parameter to enable
+asynchronous event handling. This will tell the inner interpreter loop
+to call the application event handler \var{async_dispatch} whenever events
+are available. This will cause FrameWork window updates and the user
+interface to remain working during long computations, but will slow the
+interpreter down and may cause surprising results in non-reentrant code
+(such as FrameWork itself). By default \var{async_dispatch} will immedeately
+call \var{our_dispatch} but you may override this to handle only certain
+events asynchronously. Events you do not handle will be passed to Sioux
+and such.
+
+The old on/off value is returned.
 \end{funcdesc}
 
 \begin{funcdesc}{_quit}{}

Doc/libmailbox.tex

@@ -31,12 +31,10 @@ All implementations of Mailbox objects have one externally visible
 method:
 
 \begin{funcdesc}{next}{}
-Return the next message in the mailbox, as a \code{rfc822.Message} object=
-=2E
+Return the next message in the mailbox, as a \code{rfc822.Message} object.
 Depending on the mailbox implementation the \var{fp} attribute of this
-object may be a true file object or a class instance simulating a file ob=
-ject,
-taking care of things like message boundaries if multiple mail messages a=
-re
+object may be a true file object or a class instance simulating a file object,
+taking care of things like message boundaries if multiple mail messages are
 contained in a single file, etc.
 \end{funcdesc}
+

Doc/mac/libmacfs.tex

@@ -86,6 +86,11 @@ search, \var{which} is the 4-char string specifying which folder to
 locate. Setting \var{create} causes the folder to be created if it
 does not exist. Returns a \code{(vrefnum, dirid)} tuple.
 
+\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
+Return a minimal alias record object that points to the given file, which
+must be specified as a full pathname. This is the only way to create an
+alias record pointing to a non-existing file.
+
 The constants for \var{where} and \var{which} can be obtained from the
 standard module \var{MACFS}.
 \end{funcdesc}
@@ -164,7 +169,9 @@ or transmitting to other programs.
 Resolve the alias. If the alias was created as a relative alias you
 should pass the file relative to which it is. Return the FSSpec for
 the file pointed to and a flag indicating whether the alias object
-itself was modified during the search process. 
+itself was modified during the search process. If the file does
+not exist but the path leading up to it does exist a valid fsspec
+is returned.
 \end{funcdesc}
 
 \begin{funcdesc}{GetInfo}{num}

Doc/mac/libmacic.tex

+\section{Standard Module \sectcode{ic}}
+\bimodindex{ic}
+
+\renewcommand{\indexsubitem}{(in module ic)}
+
+This module provides access to macintosh Internet Config package,
+which stores preferences for Internet programs such as mail address,
+default homepage, etc. Also, Internet Config contains an elaborate set
+of mappings from Macintosh creator/type codes to foreign filename
+extensions plus information on how to transfer files (binary, ascii,
+etc). 
+
+There is a low-level companion module \code{icglue} which provides the
+basic ic access functionality. This low-level module is not
+documented, but the docstrings of the routines document the parameters
+and the routine names are the same as for the Pascal or C API to
+Internet Config, so the standard IC programmers documentation can be
+used if this module is needed.
+
+The \code{ic} module defines the \code{error} exception and symbolic
+names for all error codes IC can produce, see the source for details.
+
+The \code{ic} module defines the following functions:
+
+\begin{funcdesc}{IC}{\optional{signature\, ic}}
+Create an internet config object. The signature is a 4-char creator
+code of the current application (default \code{'Pyth'}) which may
+influence some of ICs settings. The optional \var{ic} argument is a
+low-level \code{icinstance} created beforehand, this may be useful if
+you want to get preferences from a different config file, etc.
+\end{funcdesc}
+
+\begin{funcdesc}{launchurl}{url \optional{\, hint}}
+\end{funcdesc}
+\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
+\end{funcdesc}
+\begin{funcdesc}{mapfile}{file}
+\end{funcdesc}
+\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
+	filename}}
+\end{funcdesc}
+\begin{funcdesc}{settypecreator}{file}
+These functions are ``shortcuts'' to the methods of the same name,
+described below.
+\end{funcdesc}
+
+
+\subsection{IC objects}
+
+IC objects have a mapping interface, hence to obtain the mail address
+you simply get \code{ic['MailAddress']}. Assignment also works, and
+changes the option in the configuration file.
+
+The module knows about various datatypes, and converts the internal IC
+representation to a ``logical'' python datastructure. Running the
+\code{ic} module standalone will run a test program that lists all
+keys and values in your IC database, this will have to server as
+documentation.
+
+If the module does not know how to represent the data it returns an
+instance of the \var{ICOpaqueData} type, with the raw data in its
+\var{data} attribute. Objects of this type are also acceptable values
+for assignment.
+
+Besides the dictionary interface IC objects have the following methods:
+
+\renewcommand{\indexsubitem}{(IC object attribute)}
+
+\begin{funcdesc}{launchurl}{url \optional{\, hint}}
+Parse the given URL, lauch the correct application and pass it the
+URL. The optional \var{hint} can be a scheme name such as
+\code{mailto:}, in which case incomplete URLs are completed with this
+scheme (otherwise incomplete URLs are invalid). 
+\end{funcdesc}
+
+\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
+Find an URL somewhere in \var{data} and return start position, end
+position and the URL. The optional \var{start} and \var{end} can be
+used to limit the search, so for instance if a user clicks in a long
+textfield you can pass the whole textfield and the click-position in
+\var{start} and this routine will return the whole URL in which the
+user clicked. \var{Hint} is again an optional scheme used to complete
+incomplete URLs.
+\end{funcdesc}
+
+\begin{funcdesc}{mapfile}{file}
+Return the mapping entry for the given \var{file}, which can be passed
+as either a filename or an \var{FSSpec} object, and which need not
+exist.
+
+The mapping entry is returned as a tuple \code{(version\, type\,
+creator\, postcreator\, flags\, extension\, appname\, postappname\,
+mimetype\, entryname)}, where \var{version} is the entry version
+number, \var{type} is the 4-char filetype, \var{creator} is the 4-char
+creator type, \var{postcreator} is the 4-char creator code of an
+optional application to post-process the file after downloading,
+\var{flags} are various bits specifying whether to transfer in binary
+or ascii and such, \var{extension} is the filename extension for this
+file type, \var{appname} is the printable name of the application to
+which this file belongs, \var{postappname} is the name of the
+postprocessing application, \var{mimetype} is the MIME type of this
+file and \var{entryname} is the name of this entry.
+\end{funcdesc}
+
+\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
+	filename}}
+Return the mapping entry for files with given 4-char \var{type} and
+\var{creator} codes. The optional \var{filename} may be specified to
+further help finding the correct entry (if the creator code is
+\code{'????'}, for instance).
+
+The mapping entry is returned in the same format as for \var{mapfile}.
+\end{funcdesc}
+
+\begin{funcdesc}{settypecreator}{file}
+Given an existing \var{file}, specified either as a filename or as an
+\var{FSSpec} record, set its creator and type correctly based on its
+extension. The finder is told about the change, so the finder icon
+will be updated quickly.
+\end{funcdesc}

Doc/mac/libmacos.tex

@@ -20,48 +20,35 @@ Symbolic names for all known error codes are defined in the standard
 module \var{macerrors}.
 \end{excdesc}
 
-\begin{funcdesc}{SetHighLevelEventHandler}{handler}
-Pass a python function that will be called upon reception of a
-high-level event. The previous handler is returned. The handler
-function is called with the event as argument.
-
-Note that your event handler is currently only called dependably if
-your main event loop is in \var{stdwin}.
-\end{funcdesc}
-
-\begin{funcdesc}{AcceptHighLevelEvent}{}
-Read a high-level event. The return value is a tuple \code{(sender,
-refcon, data)}.
-\end{funcdesc}
-
-\begin{funcdesc}{SetScheduleTimes}{fgi\, fgy \optional{\, bgi\, bgy}}
-Controls how often the interpreter checks the event queue and how
-long it will yield the processor to other processes. \var{fgi}
-specifies after how many clicks (one click is one 60th of a second)
-the interpreter should check the event queue, and \var{fgy} specifies
-for how many clicks the CPU should be yielded when in the
-foreground. The optional \var{bgi} and \var{bgy} allow you to specify
-different values to use when python runs in the background, otherwise
-the background values will be set the the same as the foreground
-values. The function returns nothing.
-
-The default values, which are based on minimal empirical testing, are 12, 1, 6
-and 2 respectively.
+\begin{funcdesc}{SetEventHandler}{handler}
+In the inner interpreter loop Python will occasionally check for events,
+unless disabled with \var{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 SetEventHandler without parameter to clear the event handler. Setting
+an eventhandler while one is already set is an error.
 \end{funcdesc}
 
-\begin{funcdesc}{EnableAppswitch}{onoff}
-Enable or disable the python event loop, based on the value of
-\var{onoff}. The old value is returned. If the event loop is disabled
-no time is granted to other applications, checking for command-period
-is not performed and it is impossible to switch applications. This
-should only be used by programs providing their own complete event
-loop.
-
-Note that based on the compiler used to build python it is still
-possible to loose events even with the python event loop disabled. If
-you have a \code{sys.stdout} window its handler will often also look
-in the event queue. Making sure nothing is ever printed works around
-this.
+\begin{funcdesc}{SchedParams}{\optional{doint\, evtmask\, besocial\, 
+				interval\, 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). \bar{Besocial}
+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 CPU is given up for a quarter second when in the
+background.
 \end{funcdesc}
 
 \begin{funcdesc}{HandleEvent}{ev}
@@ -70,6 +57,9 @@ 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
+\code{SetEventHandler} you will get an exception.
 \end{funcdesc}
 
 \begin{funcdesc}{GetErrorString}{errno}

Doc/mac/libmacui.tex

@@ -4,7 +4,9 @@
 
 The \code{EasyDialogs} module contains some simple dialogs for
 the Macintosh, modelled after the \code{stdwin} dialogs with similar
-names.
+names. All routines have an optional parameter \var{id} with which you
+can override the DLOG resource used for the dialog, as long as the
+item numbers correspond. See the source for details.
 
 The \code{EasyDialogs} module defines the following functions:
 
@@ -170,6 +172,29 @@ The event loop is split into many small parts, each of which can be
 overridden. The default methods take care of dispatching events to
 windows and dialogs, handling drags and resizes, Apple Events, events
 for non-FrameWork windows, etc.
+
+In general, all event handlers should return 1 if the event is fully
+handled and 0 otherwise (because the front window was not a FrameWork
+window, for instance). This is needed so that update events and such
+can be passed on to other windows like the Sioux console window.
+Calling \code{MacOS.HandleEvent} is not allowed within \var{our_dispatch}
+or its callees, since this may result in an infinite loop if the
+code is called through the python inner-loop event handler.
+\end{funcdesc}
+
+\begin{funcdesc}{asyncevents}{onoff}
+Call this method with a nonzero parameter to enable
+asynchronous event handling. This will tell the inner interpreter loop
+to call the application event handler \var{async_dispatch} whenever events
+are available. This will cause FrameWork window updates and the user
+interface to remain working during long computations, but will slow the
+interpreter down and may cause surprising results in non-reentrant code
+(such as FrameWork itself). By default \var{async_dispatch} will immedeately
+call \var{our_dispatch} but you may override this to handle only certain
+events asynchronously. Events you do not handle will be passed to Sioux
+and such.
+
+The old on/off value is returned.
 \end{funcdesc}
 
 \begin{funcdesc}{_quit}{}