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
diff --git a/Doc/Makefile b/Doc/Makefile
index 01bed3b..e058689 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -112,7 +112,7 @@
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)
diff --git a/Doc/lib.tex b/Doc/lib.tex
index 442de74..b2d596f 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -195,6 +195,7 @@
\input{libmacconsole}
\input{libmacdnr}
\input{libmacfs}
+\input{libmacic}
\input{libmacos}
\input{libmacostools}
\input{libmactcp}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 442de74..b2d596f 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -195,6 +195,7 @@
\input{libmacconsole}
\input{libmacdnr}
\input{libmacfs}
+\input{libmacic}
\input{libmacos}
\input{libmacostools}
\input{libmactcp}
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex
index 31618b2..8db4c91 100644
--- a/Doc/lib/libmailbox.tex
+++ b/Doc/lib/libmailbox.tex
@@ -31,12 +31,10 @@
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}
+
diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex
index 6f63a47..0ce4ff1 100644
--- a/Doc/libmacfs.tex
+++ b/Doc/libmacfs.tex
@@ -86,6 +86,11 @@
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 @@
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}
diff --git a/Doc/libmacic.tex b/Doc/libmacic.tex
new file mode 100644
index 0000000..fd16002
--- /dev/null
+++ b/Doc/libmacic.tex
@@ -0,0 +1,120 @@
+\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}
diff --git a/Doc/libmacos.tex b/Doc/libmacos.tex
index 6975380..c8f52fe 100644
--- a/Doc/libmacos.tex
+++ b/Doc/libmacos.tex
@@ -20,48 +20,35 @@
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.
+\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).
-Note that your event handler is currently only called dependably if
-your main event loop is in \var{stdwin}.
+Call SetEventHandler without parameter to clear the event handler. Setting
+an eventhandler while one is already set is an error.
\end{funcdesc}
-\begin{funcdesc}{AcceptHighLevelEvent}{}
-Read a high-level event. The return value is a tuple \code{(sender,
-refcon, data)}.
-\end{funcdesc}
+\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.
-\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.
-\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.
+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 @@
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}
diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex
index d519bf5..8e42e6a 100644
--- a/Doc/libmacui.tex
+++ b/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 @@
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}{}
diff --git a/Doc/libmailbox.tex b/Doc/libmailbox.tex
index 31618b2..8db4c91 100644
--- a/Doc/libmailbox.tex
+++ b/Doc/libmailbox.tex
@@ -31,12 +31,10 @@
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}
+
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index 6f63a47..0ce4ff1 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -86,6 +86,11 @@
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 @@
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}
diff --git a/Doc/mac/libmacic.tex b/Doc/mac/libmacic.tex
new file mode 100644
index 0000000..fd16002
--- /dev/null
+++ b/Doc/mac/libmacic.tex
@@ -0,0 +1,120 @@
+\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}
diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex
index 6975380..c8f52fe 100644
--- a/Doc/mac/libmacos.tex
+++ b/Doc/mac/libmacos.tex
@@ -20,48 +20,35 @@
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.
+\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).
-Note that your event handler is currently only called dependably if
-your main event loop is in \var{stdwin}.
+Call SetEventHandler without parameter to clear the event handler. Setting
+an eventhandler while one is already set is an error.
\end{funcdesc}
-\begin{funcdesc}{AcceptHighLevelEvent}{}
-Read a high-level event. The return value is a tuple \code{(sender,
-refcon, data)}.
-\end{funcdesc}
+\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.
-\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.
-\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.
+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 @@
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}
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex
index d519bf5..8e42e6a 100644
--- a/Doc/mac/libmacui.tex
+++ b/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 @@
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}{}