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}
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}}
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.
\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}
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.
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)}
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:
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}
(\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
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}
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}}
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.
\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}
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.
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)}
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:
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}
(\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
projects / python / commitdiff