changes by Jack to Mac docs

8 files changed, 288 insertions, 18 deletions

diff --git a/Doc/libmac.tex b/Doc/libmac.tex
index af07142..344d300 100644
--- a/Doc/libmac.tex
+++ b/Doc/libmac.tex
@@ -2,6 +2,37 @@
 
 The modules in this chapter are available on the Apple Macintosh only.
 
+Aside from the modules described here there are also interfaces to
+various MacOS toolboxes, which are currently not extensively
+described. The toolboxes for which modules exist are:
+\code{AE} (Apple Events),
+\code{Cm} (Component Manager),
+\code{Ctl} (Control Manager),
+\code{Dlg} (Dialog Manager),
+\code{Evt} (Event Manager),
+\code{Fm} (Font Manager),
+\code{List} (List Manager),
+\code{Menu} (Moenu Manager),
+\code{Qd} (QuickDraw),
+\code{Qt} (QuickTime),
+\code{Res} (Resource Manager and Handles),
+\code{Scrap} (Scrap Manager),
+\code{Snd} (Sound Manager),
+\code{TE} (TextEdit),
+\code{Waste} (non-Apple TextEdit replacement) and
+\code{Win} (Window Manager).
+
+If applicable the module will define a number of Python objects for
+the various structures declared by the toolbox, and operations will be
+implemented as methods of the object. Other operations will be
+implemented as functions in the module. Not all operations possible in
+C will also be possible in Python (callbacks are often a problem), and
+parameters will occasionally be different in Python (input and output
+buffers, especially). All methods and functions have a \code{__doc__}
+string describing their arguments and return values, and for
+additional description you are referred to Inside Mac or similar
+works.
+
 \section{Built-in Module \sectcode{mac}}
 
 \bimodindex{mac}
@@ -12,14 +43,21 @@ It is best accessed through the more portable standard module
 
 The following functions are available in this module:
 \code{chdir},
+\code{close},
+\code{dup},
+\code{fdopen},
 \code{getcwd},
+\code{lseek},
 \code{listdir},
 \code{mkdir},
+\code{open},
+\code{read},
 \code{rename},
 \code{rmdir},
 \code{stat},
 \code{sync},
 \code{unlink},
+\code{write},
 as well as the exception \code{error}.
 
 \section{Standard Module \sectcode{macpath}}
@@ -32,9 +70,13 @@ best accessed through the more portable standard module \code{os}, as
 
 The following functions are available in this module:
 \code{normcase},
+\code{normpath},
 \code{isabs},
 \code{join},
 \code{split},
 \code{isdir},
 \code{isfile},
+\code{walk},
 \code{exists}.
+For other functions available in \code{posixpath} dummy counterparts
+are available.
diff --git a/Doc/libmacos.tex b/Doc/libmacos.tex
index 6618754..e48a0c3 100644
--- a/Doc/libmacos.tex
+++ b/Doc/libmacos.tex
@@ -72,3 +72,19 @@ window-switching capability.
 \begin{funcdesc}{GetErrorString}{errno}
 Return the textual description of MacOS error code \var{errno}.
 \end{funcdesc}
+
+\begin{funcdesc}{splash}{resid}
+This function will put a splash window
+on-screen, with the contents of the DLOG resource specified by
+\code{resid}. Calling with a zero argument will remove the splash
+screen. This function is useful if you want to post a splash screen
+early in initialization without first having to load numerous
+extension modules.
+\end{funcdesc}
+
+\begin{funcdesc}{openrf}{name \optional{\, mode}}
+Open the resource fork of a file. Arguments are the same as for the
+builtin function \code{open}. The object returned has file-like
+semantics, but it is not a python file object, so there may be subtle
+differences.
+\end{funcdesc}
diff --git a/Doc/libmactcp.tex b/Doc/libmactcp.tex
index 6c5a78b..80e19ca 100644
--- a/Doc/libmactcp.tex
+++ b/Doc/libmactcp.tex
@@ -6,10 +6,10 @@
 This module provides an interface to the Macintosh TCP/IP driver
 MacTCP\@. There is an accompanying module \code{macdnr} which provides an
 interface to the name-server (allowing you to translate hostnames to
-ip-addresses), a module \code{MACTCP} which has symbolic names for
-constants constants used by MacTCP and a wrapper module \code{socket}
-which mimics the \UNIX{} socket interface (as far as possible).  It may
-not be available in all Mac Python versions.
+ip-addresses), a module \code{MACTCPconst} which has symbolic names for
+constants constants used by MacTCP. Since the builtin module
+\code{socket} is also available on the mac it is usually easier to use
+sockets in stead of the mac-specific MacTCP API.
 
 A complete description of the MacTCP interface can be found in the
 Apple MacTCP API documentation.
diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex
index f785679..1c2df7c 100644
--- a/Doc/libmacui.tex
+++ b/Doc/libmacui.tex
@@ -66,10 +66,10 @@ handling.
 
 The \code{FrameWork} is still very much work-in-progress, and the
 documentation describes only the most important functionality, and not
-in the most logical manner at that. Examine the source for more
-esoteric needs. 
+in the most logical manner at that. Examine the source or the examples
+for more details.
 
-The \code{EasyDialogs} module defines the following functions:
+The \code{FrameWork} module defines the following functions:
 
 \renewcommand{\indexsubitem}{(in module FrameWork)}
 
@@ -117,6 +117,14 @@ which the window belongs. The window is not displayed until later.
 Creates a modeless dialog window.
 \end{funcdesc}
 
+\begin{funcdesc}{windowbounds}{width\, height}
+Return a \code{(left, top, right, bottom)} tuple suitable for creation
+of a window of given width and height. The window will be staggered
+with respect to previous windows, and an attempt is made to keep the
+whole window on-screen. The window will however always be exact the
+size given, so parts may be offscreen.
+\end{funcdesc}
+
 
 \subsection{Application objects}
 Application objects have the following methods, among others:
@@ -161,8 +169,9 @@ through the the \code{DialogWindow} object involved). Override if you
 need special handling of dialog events (keyboard shortcuts, etc).
 \end{funcdesc}
 
-\begin{funcdesc}{idle}{}
-Called by the main event loop when no events are available.
+\begin{funcdesc}{idle}{event}
+Called by the main event loop when no events are available. The
+null-event is passed (so you can look at mouse position, etc).
 \end{funcdesc}
 
 \subsection{Window Objects}
@@ -202,6 +211,74 @@ The window was activated (\code{activate==1}) or deactivated
 (\code{activate==0}). Handle things like focus highlighting, etc.
 \end{funcdesc}
 
+\subsection{ControlsWindow Object}
+
+ControlsWindow objects have the following methods besides those of
+\code{Window} objects:
+
+\renewcommand{\indexsubitem}{(ControlsWindow method)}
+
+\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event}
+Part \code{pcode} of control \code{control} was hit by the
+user. Tracking and such has already been taken care of.
+\end{funcdesc}
+
+\subsection{ScrolledWindow Object}
+
+ScrolledWindow objects are ControlsWindow objects with the following
+extra mathods:
+
+\renewcommand{\indexsubitem}{(ScrolledWindow method)}
+
+\begin{funcdesc}{scrollbars}{\optional{wantx\, wanty}}
+Create (or destroy) horizontal and vertical scrollbars. The arguments
+specify which you want (default: both). The scrollbars always have
+minimum \code{0} and maximum \code{32767}.
+\end{funcdesc}
+
+\begin{funcdesc}{getscrollbarvalues}{}
+You must supply this method. It should return a tuple \code{x, y}
+giving the current position of the scrollbars (between \code{0} and
+\code{32767}). You can return \code{None} for either to indicate the
+whole document is visible in that direction.
+\end{funcdesc}
+
+\begin{funcdesc}{updatescrollbars}{}
+Call this method when the document has changed. It will call
+\code{getscrollbarvalues} and update the scrollbars.
+\end{funcdesc}
+
+\begin{funcdesc}{scrollbar_callback}{which\, what\, value}
+Supplied by you and called after user interaction. \code{Which} will
+be \code{'x'} or \code{'y'}, \code{what} will be \code{'-'},
+\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
+\code{'set'}, \code{value} will contain the new scrollbar position.
+\end{funcdesc}
+
+\begin{funcdesc}{scalebarvalues}{absmin\, absmax\, curmin\, curmax}
+Auxiliary method to help you calculate values to return from
+\code{getscrollbarvalues}. You pass document minimum and maximum value
+and topmost (leftmost) and bottommost (rightmost) visible values and
+it returns the correct number or \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_activate}{onoff\, event}
+Takes care of dimming/highlighting scrollbars when a window becomes
+frontmost vv. If you override this method call this one at the end of
+your method.
+\end{funcdesc}
+
+\begin{funcdesc}{do_postresize}{width\, height\, window}
+Moves scrollbars to the correct position. Call this method initially
+if you override it.
+\end{funcdesc}
+
+\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event}
+Handles scrollbar interaction. If you override it call this method
+first, a nonzero return value indicates the hit was in the scrollbars
+and has been handled.
+\end{funcdesc}
+
 \subsection{DialogWindow Objects}
 
 DialogWindow objects have the following methods besides those of
diff --git a/Doc/mac/libmac.tex b/Doc/mac/libmac.tex
index af07142..344d300 100644
--- a/Doc/mac/libmac.tex
+++ b/Doc/mac/libmac.tex
@@ -2,6 +2,37 @@
 
 The modules in this chapter are available on the Apple Macintosh only.
 
+Aside from the modules described here there are also interfaces to
+various MacOS toolboxes, which are currently not extensively
+described. The toolboxes for which modules exist are:
+\code{AE} (Apple Events),
+\code{Cm} (Component Manager),
+\code{Ctl} (Control Manager),
+\code{Dlg} (Dialog Manager),
+\code{Evt} (Event Manager),
+\code{Fm} (Font Manager),
+\code{List} (List Manager),
+\code{Menu} (Moenu Manager),
+\code{Qd} (QuickDraw),
+\code{Qt} (QuickTime),
+\code{Res} (Resource Manager and Handles),
+\code{Scrap} (Scrap Manager),
+\code{Snd} (Sound Manager),
+\code{TE} (TextEdit),
+\code{Waste} (non-Apple TextEdit replacement) and
+\code{Win} (Window Manager).
+
+If applicable the module will define a number of Python objects for
+the various structures declared by the toolbox, and operations will be
+implemented as methods of the object. Other operations will be
+implemented as functions in the module. Not all operations possible in
+C will also be possible in Python (callbacks are often a problem), and
+parameters will occasionally be different in Python (input and output
+buffers, especially). All methods and functions have a \code{__doc__}
+string describing their arguments and return values, and for
+additional description you are referred to Inside Mac or similar
+works.
+
 \section{Built-in Module \sectcode{mac}}
 
 \bimodindex{mac}
@@ -12,14 +43,21 @@ It is best accessed through the more portable standard module
 
 The following functions are available in this module:
 \code{chdir},
+\code{close},
+\code{dup},
+\code{fdopen},
 \code{getcwd},
+\code{lseek},
 \code{listdir},
 \code{mkdir},
+\code{open},
+\code{read},
 \code{rename},
 \code{rmdir},
 \code{stat},
 \code{sync},
 \code{unlink},
+\code{write},
 as well as the exception \code{error}.
 
 \section{Standard Module \sectcode{macpath}}
@@ -32,9 +70,13 @@ best accessed through the more portable standard module \code{os}, as
 
 The following functions are available in this module:
 \code{normcase},
+\code{normpath},
 \code{isabs},
 \code{join},
 \code{split},
 \code{isdir},
 \code{isfile},
+\code{walk},
 \code{exists}.
+For other functions available in \code{posixpath} dummy counterparts
+are available.
diff --git a/Doc/mac/libmacos.tex b/Doc/mac/libmacos.tex
index 6618754..e48a0c3 100644
--- a/Doc/mac/libmacos.tex
+++ b/Doc/mac/libmacos.tex
@@ -72,3 +72,19 @@ window-switching capability.
 \begin{funcdesc}{GetErrorString}{errno}
 Return the textual description of MacOS error code \var{errno}.
 \end{funcdesc}
+
+\begin{funcdesc}{splash}{resid}
+This function will put a splash window
+on-screen, with the contents of the DLOG resource specified by
+\code{resid}. Calling with a zero argument will remove the splash
+screen. This function is useful if you want to post a splash screen
+early in initialization without first having to load numerous
+extension modules.
+\end{funcdesc}
+
+\begin{funcdesc}{openrf}{name \optional{\, mode}}
+Open the resource fork of a file. Arguments are the same as for the
+builtin function \code{open}. The object returned has file-like
+semantics, but it is not a python file object, so there may be subtle
+differences.
+\end{funcdesc}
diff --git a/Doc/mac/libmactcp.tex b/Doc/mac/libmactcp.tex
index 6c5a78b..80e19ca 100644
--- a/Doc/mac/libmactcp.tex
+++ b/Doc/mac/libmactcp.tex
@@ -6,10 +6,10 @@
 This module provides an interface to the Macintosh TCP/IP driver
 MacTCP\@. There is an accompanying module \code{macdnr} which provides an
 interface to the name-server (allowing you to translate hostnames to
-ip-addresses), a module \code{MACTCP} which has symbolic names for
-constants constants used by MacTCP and a wrapper module \code{socket}
-which mimics the \UNIX{} socket interface (as far as possible).  It may
-not be available in all Mac Python versions.
+ip-addresses), a module \code{MACTCPconst} which has symbolic names for
+constants constants used by MacTCP. Since the builtin module
+\code{socket} is also available on the mac it is usually easier to use
+sockets in stead of the mac-specific MacTCP API.
 
 A complete description of the MacTCP interface can be found in the
 Apple MacTCP API documentation.
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex
index f785679..1c2df7c 100644
--- a/Doc/mac/libmacui.tex
+++ b/Doc/mac/libmacui.tex
@@ -66,10 +66,10 @@ handling.
 
 The \code{FrameWork} is still very much work-in-progress, and the
 documentation describes only the most important functionality, and not
-in the most logical manner at that. Examine the source for more
-esoteric needs. 
+in the most logical manner at that. Examine the source or the examples
+for more details.
 
-The \code{EasyDialogs} module defines the following functions:
+The \code{FrameWork} module defines the following functions:
 
 \renewcommand{\indexsubitem}{(in module FrameWork)}
 
@@ -117,6 +117,14 @@ which the window belongs. The window is not displayed until later.
 Creates a modeless dialog window.
 \end{funcdesc}
 
+\begin{funcdesc}{windowbounds}{width\, height}
+Return a \code{(left, top, right, bottom)} tuple suitable for creation
+of a window of given width and height. The window will be staggered
+with respect to previous windows, and an attempt is made to keep the
+whole window on-screen. The window will however always be exact the
+size given, so parts may be offscreen.
+\end{funcdesc}
+
 
 \subsection{Application objects}
 Application objects have the following methods, among others:
@@ -161,8 +169,9 @@ through the the \code{DialogWindow} object involved). Override if you
 need special handling of dialog events (keyboard shortcuts, etc).
 \end{funcdesc}
 
-\begin{funcdesc}{idle}{}
-Called by the main event loop when no events are available.
+\begin{funcdesc}{idle}{event}
+Called by the main event loop when no events are available. The
+null-event is passed (so you can look at mouse position, etc).
 \end{funcdesc}
 
 \subsection{Window Objects}
@@ -202,6 +211,74 @@ The window was activated (\code{activate==1}) or deactivated
 (\code{activate==0}). Handle things like focus highlighting, etc.
 \end{funcdesc}
 
+\subsection{ControlsWindow Object}
+
+ControlsWindow objects have the following methods besides those of
+\code{Window} objects:
+
+\renewcommand{\indexsubitem}{(ControlsWindow method)}
+
+\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event}
+Part \code{pcode} of control \code{control} was hit by the
+user. Tracking and such has already been taken care of.
+\end{funcdesc}
+
+\subsection{ScrolledWindow Object}
+
+ScrolledWindow objects are ControlsWindow objects with the following
+extra mathods:
+
+\renewcommand{\indexsubitem}{(ScrolledWindow method)}
+
+\begin{funcdesc}{scrollbars}{\optional{wantx\, wanty}}
+Create (or destroy) horizontal and vertical scrollbars. The arguments
+specify which you want (default: both). The scrollbars always have
+minimum \code{0} and maximum \code{32767}.
+\end{funcdesc}
+
+\begin{funcdesc}{getscrollbarvalues}{}
+You must supply this method. It should return a tuple \code{x, y}
+giving the current position of the scrollbars (between \code{0} and
+\code{32767}). You can return \code{None} for either to indicate the
+whole document is visible in that direction.
+\end{funcdesc}
+
+\begin{funcdesc}{updatescrollbars}{}
+Call this method when the document has changed. It will call
+\code{getscrollbarvalues} and update the scrollbars.
+\end{funcdesc}
+
+\begin{funcdesc}{scrollbar_callback}{which\, what\, value}
+Supplied by you and called after user interaction. \code{Which} will
+be \code{'x'} or \code{'y'}, \code{what} will be \code{'-'},
+\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
+\code{'set'}, \code{value} will contain the new scrollbar position.
+\end{funcdesc}
+
+\begin{funcdesc}{scalebarvalues}{absmin\, absmax\, curmin\, curmax}
+Auxiliary method to help you calculate values to return from
+\code{getscrollbarvalues}. You pass document minimum and maximum value
+and topmost (leftmost) and bottommost (rightmost) visible values and
+it returns the correct number or \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_activate}{onoff\, event}
+Takes care of dimming/highlighting scrollbars when a window becomes
+frontmost vv. If you override this method call this one at the end of
+your method.
+\end{funcdesc}
+
+\begin{funcdesc}{do_postresize}{width\, height\, window}
+Moves scrollbars to the correct position. Call this method initially
+if you override it.
+\end{funcdesc}
+
+\begin{funcdesc}{do_controlhit}{window\, control\, pcode\, event}
+Handles scrollbar interaction. If you override it call this method
+first, a nonzero return value indicates the hit was in the scrollbars
+and has been handled.
+\end{funcdesc}
+
 \subsection{DialogWindow Objects}
 
 DialogWindow objects have the following methods besides those of