Documented MACFS, macostools, EasyDialogs and FrameWork modules.

9 files changed, 504 insertions, 15 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index 9dafd35..50b4782 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -111,7 +111,8 @@ libhtmllib.tex libhttplib.tex \
 libimageop.tex libimgfile.tex libintro.tex \
 libjpeg.tex \
 libmac.tex libmacconsole.tex libmacdnr.tex \
-	libmacfs.tex libmacos.tex libmactcp.tex libmacspeech.tex \
+	libmacfs.tex libmacos.tex libmacostools.tex libmactcp.tex \
+	libmacspeech.tex libmacui.tex \
 	libmain.tex libmarshal.tex libmath.tex \
 	libmd5.tex libmimetools.tex libmisc.tex \
 	libmm.tex libmpz.tex \
diff --git a/Doc/lib.tex b/Doc/lib.tex
index 049b0ce..f8a957f 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -160,8 +160,10 @@ to Python and how to embed it in other applications.
 \input{libmacdnr}
 \input{libmacfs}
 \input{libmacos}
+\input{libmacostools}
 \input{libmactcp}
 \input{libmacspeech}
+\input{libmacui}
 
 \input{libstdwin}		% STDWIN ONLY
 
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 049b0ce..f8a957f 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -160,8 +160,10 @@ to Python and how to embed it in other applications.
 \input{libmacdnr}
 \input{libmacfs}
 \input{libmacos}
+\input{libmacostools}
 \input{libmactcp}
 \input{libmacspeech}
+\input{libmacui}
 
 \input{libstdwin}		% STDWIN ONLY
 
diff --git a/Doc/libmacfs.tex b/Doc/libmacfs.tex
index fd7ac3f..254ed25 100644
--- a/Doc/libmacfs.tex
+++ b/Doc/libmacfs.tex
@@ -68,12 +68,13 @@ Return an FSSpec object and a success-indicator.
 
 \begin{funcdesc}{FindFolder}{where\, which\, create}
 Locates one of the ``special'' folders that MacOS knows about, such as
-the trash or the Preferences folder. \var{Where} is the disk to search
-(\code{0x8000} for the boot disk), \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. See Inside Mac VI for a complete description, including
-4-char names.
+the trash or the Preferences folder. \var{Where} is the disk to
+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.
+
+The constants for \var{where} and \var{which} can be obtained from the
+standard module \var{MACFS}.
 \end{funcdesc}
 
 \subsection{FSSpec objects}
@@ -168,7 +169,8 @@ The 4-char type code of the file.
 \end{datadesc}
 
 \begin{datadesc}{Flags}
-The finder flags for the file as 16-bit integer.
+The finder flags for the file as 16-bit integer. The bit values in
+\var{Flags} are defined in standard module \var{MACFS}.
 \end{datadesc}
 
 \begin{datadesc}{Location}
diff --git a/Doc/libmacostools.tex b/Doc/libmacostools.tex
new file mode 100644
index 0000000..1e60983
--- /dev/null
+++ b/Doc/libmacostools.tex
@@ -0,0 +1,39 @@
+
+\section{Standard module \sectcode{macostools}}
+\stmodindex{macostools}
+
+This module contains some convenience routines for file-manipulation
+on the Macintosh.
+
+The \code{macostools} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macostools)}
+
+\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}}
+Copy file \var{src} to \var{dst}. The files can be specified as
+pathnames or \code{FSSpec} objects. If \var{createpath} is non-zero
+\var{dst} must be a pathname and the folders leading to the
+destination are created if necessary.
+The method copies data and resource fork and some finder information
+(creator, type and flags). Custom icons, comments and icon position
+are not copied.
+\end{funcdesc}
+
+\begin{funcdesc}{copytree}{src\, dst}
+Recursively copy a file tree from \var{src} to \var{dst}, creating
+folders as needed. \var{Src} and \var{dst} should be specified as
+pathnames.
+\end{funcdesc}
+
+\begin{funcdesc}{mkalias}{src\, dst}
+Create a finder alias \var{dst} pointing to \var{src}. Both may be
+specified as pathnames or \var{FSSpec} objects.
+\end{funcdesc}
+
+\begin{datadesc}{BUFSIZ}
+The buffer size for \code{copy}, default 1 megabyte.
+\end{datadesc}
+
+Note that the process of creating finder aliases is not specified in
+the Apple documentation. Hence, aliases created with \code{mkalias}
+could conceivably have incompatible behaviour in some cases.
diff --git a/Doc/libmacui.tex b/Doc/libmacui.tex
new file mode 100644
index 0000000..08f0236
--- /dev/null
+++ b/Doc/libmacui.tex
@@ -0,0 +1,201 @@
+\section{Standard module \sectcode{EasyDialogs}}
+\stmodindex{EasyDialogs}
+
+The \code{EasyDialogs} module contains some simple dialogs for
+the Macintosh, modelled after the \code{stdwin} dialogs with similar
+names.
+
+The \code{EasyDialogs} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module EasyDialogs)}
+
+\begin{funcdesc}{Message}{str}
+A modal dialog with the message text \var{str}, which should be at
+most 255 characters long, is displayed. Control is returned when the
+user clicks ``OK''.
+\end{funcdesc}
+
+\begin{funcdesc}{AskString}{prompt\optional{\, default}}
+Ask the user to input a string value, in a modal dialog. \var{Prompt}
+is the promt message, the optional \var{default} arg is the initial
+value for the string. All strings can be at most 255 bytes
+long. \var{AskString} returns the string entered or \code{None} in
+case the user cancelled.
+\end{funcdesc}
+
+\begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}}
+Present a dialog with text \var{question} and three buttons labelled
+``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for
+no and \code{-1} for cancel. The default return value chosen by
+hitting return is \code{0}. This can be changed with the optional
+\var{default} argument.
+\end{funcdesc}
+
+Note that \code{EasyDialogs} does not currently use the notification
+manager. This means that displaying dialogs while the program is in
+the background will need to unexpected results and possibly crashes.
+
+
+\section{Standard module \sectcode{FrameWork}}
+\stmodindex{FrameWork}
+
+The \code{FrameWork} module contains classes that together provide a
+framework for an interactive Macintosh application. The programmer
+builds an application by creating subclasses that override various
+methods of the bases classes, thereby implementing the functionality
+wanted. Overriding functionality can often be done on various
+different levels, i.e. to handle clicks in a single dialog window in a
+non-standard way it is not necessary to override the complete event
+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. 
+
+The \code{EasyDialogs} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module FrameWork)}
+
+\begin{funcdesc}{Application}{}
+An object representing the complete application. See below for a
+description of the methods. The default \code{__init__} routine
+creates an empty window dictionary and a menu bar with an apple menu.
+\end{funcdesc}
+
+\begin{funcdesc}{MenuBar}{}
+An object representing the menubar. This object is usually not created
+by the user.
+\end{funcdesc}
+
+\begin{funcdesc}{Menu}{bar\, title\optional{\, after}}
+An object representing a menu. Upon creation you pass the
+\code{MenuBar} the menu appears in, the \var{title} string and a
+position (1-based) \var{after} where the menu should appear (default:
+at the end).
+\end{funcdesc}
+
+\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}}
+Create a menu item object. The arguments are the menu to crate the
+item it, the item title string and optionally the keyboard shortcut
+and a callback routine. The callback is called with the arguments
+menu-id, item number within menu (1-based), current front window and
+the event record.
+\end{funcdesc}
+
+\begin{funcdesc}{Separator}{menu}
+Add a separator to the end of a menu.
+\end{funcdesc}
+
+\begin{funcdesc}{SubMenu}{menu\, label}
+Create a submenu named \var{label} under menu \var{menu}. The menu
+object is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{Window}{parent}
+Creates a (modeless) window. \var{Parent} is the application object to
+which the window belongs. The window is not displayed until later.
+\end{funcdesc}
+
+\begin{funcdesc}{DialogWindow}{parent}
+Creates a modeless dialog window.
+\end{funcdesc}
+
+
+\subsection{Application objects}
+Application objects have the following methods, among others:
+
+\renewcommand{\indexsubitem}{(Application method)}
+
+\begin{funcdesc}{makeusermenus}{}
+Override this method if you need menus in your application. Append the
+menus to \code{self.menubar}.
+\end{funcdesc}
+
+\begin{funcdesc}{getabouttext}{}
+Override this method to return a text string describing your
+application. Alternatively, override the \code{do_about} method for
+more elaborate about messages.
+\end{funcdesc}
+
+\begin{funcdesc}{mainloop}{\optional{mask\, wait}}
+This routine is the main event loop, call it to set your application
+rolling. \var{Mask} is the mask of events you want to handle,
+\var{wait} is the number of ticks you want to leave to other
+concurrent application (default 0, which is probably not a good
+idea). This method does not return until \code{self} is raised.
+
+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.
+\end{funcdesc}
+
+\begin{funcdesc}{do_char}{c\, event}
+The user typed character \var{c}. The complete details of the event
+can be found in the \var{event} structure. This method can also be
+provided in a \code{Window} object, which overrides the
+application-wide handler if the window is frontmost.
+\end{funcdesc}
+
+\begin{funcdesc}{do_dialogevent}{event}
+Called early in the event loop to handle modeless dialog events. The
+default method simply dispatches the event to the relevant dialog (not
+through the the \code{DialogWindow} object involved). Override if you
+need special handling of dialog events (keyboard shortcuts, etc).
+\end{funcdesc}
+
+\subsection{Window Objects}
+
+Window objects have the following methods, among others:
+
+\renewcommand{\indexsubitem}{(Window method)}
+
+\begin{funcdesc}{open}{}
+Override this method to open a window. Store the MacOS window-id in
+\code{self.wid} and call \code{self.do_postopen} to register the
+window with the parent application.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Override this method to do any special processing on window
+close. Call \code{self.do_postclose} to cleanup the parent state.
+\end{funcdesc}
+
+\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid}
+Called after the window is resized. Override if more needs to be done
+than calling \code{InvalRect}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_contentclick}{local\, modifiers\, event}
+The user clicked in the content part of a window. The arguments are
+the coordinates (window-relative), the key modifiers and the raw
+event.
+\end{funcdesc}
+
+\begin{funcdesc}{do_update}{macoswindowid\, event}
+An update event for the window was received. Redraw the window.
+\end{funcdesc}
+
+\begin{funcdesc}{do_activate}{activate\, event}
+The window was activated (\code{activate==1}) or deactivated
+(\code{activate==0}). Handle things like focus highlighting, etc.
+\end{funcdesc}
+
+\subsection{DialogWindow Objects}
+
+DialogWindow objects have the following methods besides those of
+\code{Window} objects:
+
+\renewcommand{\indexsubitem}{(DialogWindow method)}
+
+\begin{funcdesc}{open}{resid}
+Create the dialog window, from the DLOG resource with id
+\var{resid}. The dialog object is stored in \code{self.wid}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_itemhit}{item\, event}
+Item number \var{item} was hit. You are responsible for redrawing
+toggle buttons, etc.
+\end{funcdesc}
+
diff --git a/Doc/mac/libmacfs.tex b/Doc/mac/libmacfs.tex
index fd7ac3f..254ed25 100644
--- a/Doc/mac/libmacfs.tex
+++ b/Doc/mac/libmacfs.tex
@@ -68,12 +68,13 @@ Return an FSSpec object and a success-indicator.
 
 \begin{funcdesc}{FindFolder}{where\, which\, create}
 Locates one of the ``special'' folders that MacOS knows about, such as
-the trash or the Preferences folder. \var{Where} is the disk to search
-(\code{0x8000} for the boot disk), \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. See Inside Mac VI for a complete description, including
-4-char names.
+the trash or the Preferences folder. \var{Where} is the disk to
+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.
+
+The constants for \var{where} and \var{which} can be obtained from the
+standard module \var{MACFS}.
 \end{funcdesc}
 
 \subsection{FSSpec objects}
@@ -168,7 +169,8 @@ The 4-char type code of the file.
 \end{datadesc}
 
 \begin{datadesc}{Flags}
-The finder flags for the file as 16-bit integer.
+The finder flags for the file as 16-bit integer. The bit values in
+\var{Flags} are defined in standard module \var{MACFS}.
 \end{datadesc}
 
 \begin{datadesc}{Location}
diff --git a/Doc/mac/libmacostools.tex b/Doc/mac/libmacostools.tex
new file mode 100644
index 0000000..1e60983
--- /dev/null
+++ b/Doc/mac/libmacostools.tex
@@ -0,0 +1,39 @@
+
+\section{Standard module \sectcode{macostools}}
+\stmodindex{macostools}
+
+This module contains some convenience routines for file-manipulation
+on the Macintosh.
+
+The \code{macostools} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module macostools)}
+
+\begin{funcdesc}{copy}{src\, dst\optional{\, createpath}}
+Copy file \var{src} to \var{dst}. The files can be specified as
+pathnames or \code{FSSpec} objects. If \var{createpath} is non-zero
+\var{dst} must be a pathname and the folders leading to the
+destination are created if necessary.
+The method copies data and resource fork and some finder information
+(creator, type and flags). Custom icons, comments and icon position
+are not copied.
+\end{funcdesc}
+
+\begin{funcdesc}{copytree}{src\, dst}
+Recursively copy a file tree from \var{src} to \var{dst}, creating
+folders as needed. \var{Src} and \var{dst} should be specified as
+pathnames.
+\end{funcdesc}
+
+\begin{funcdesc}{mkalias}{src\, dst}
+Create a finder alias \var{dst} pointing to \var{src}. Both may be
+specified as pathnames or \var{FSSpec} objects.
+\end{funcdesc}
+
+\begin{datadesc}{BUFSIZ}
+The buffer size for \code{copy}, default 1 megabyte.
+\end{datadesc}
+
+Note that the process of creating finder aliases is not specified in
+the Apple documentation. Hence, aliases created with \code{mkalias}
+could conceivably have incompatible behaviour in some cases.
diff --git a/Doc/mac/libmacui.tex b/Doc/mac/libmacui.tex
new file mode 100644
index 0000000..08f0236
--- /dev/null
+++ b/Doc/mac/libmacui.tex
@@ -0,0 +1,201 @@
+\section{Standard module \sectcode{EasyDialogs}}
+\stmodindex{EasyDialogs}
+
+The \code{EasyDialogs} module contains some simple dialogs for
+the Macintosh, modelled after the \code{stdwin} dialogs with similar
+names.
+
+The \code{EasyDialogs} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module EasyDialogs)}
+
+\begin{funcdesc}{Message}{str}
+A modal dialog with the message text \var{str}, which should be at
+most 255 characters long, is displayed. Control is returned when the
+user clicks ``OK''.
+\end{funcdesc}
+
+\begin{funcdesc}{AskString}{prompt\optional{\, default}}
+Ask the user to input a string value, in a modal dialog. \var{Prompt}
+is the promt message, the optional \var{default} arg is the initial
+value for the string. All strings can be at most 255 bytes
+long. \var{AskString} returns the string entered or \code{None} in
+case the user cancelled.
+\end{funcdesc}
+
+\begin{funcdesc}{AskYesNoCancel}{question\optional{\, default}}
+Present a dialog with text \var{question} and three buttons labelled
+``yes'', ``no'' and ``cancel''. Return \code{1} for yes, \code{0} for
+no and \code{-1} for cancel. The default return value chosen by
+hitting return is \code{0}. This can be changed with the optional
+\var{default} argument.
+\end{funcdesc}
+
+Note that \code{EasyDialogs} does not currently use the notification
+manager. This means that displaying dialogs while the program is in
+the background will need to unexpected results and possibly crashes.
+
+
+\section{Standard module \sectcode{FrameWork}}
+\stmodindex{FrameWork}
+
+The \code{FrameWork} module contains classes that together provide a
+framework for an interactive Macintosh application. The programmer
+builds an application by creating subclasses that override various
+methods of the bases classes, thereby implementing the functionality
+wanted. Overriding functionality can often be done on various
+different levels, i.e. to handle clicks in a single dialog window in a
+non-standard way it is not necessary to override the complete event
+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. 
+
+The \code{EasyDialogs} module defines the following functions:
+
+\renewcommand{\indexsubitem}{(in module FrameWork)}
+
+\begin{funcdesc}{Application}{}
+An object representing the complete application. See below for a
+description of the methods. The default \code{__init__} routine
+creates an empty window dictionary and a menu bar with an apple menu.
+\end{funcdesc}
+
+\begin{funcdesc}{MenuBar}{}
+An object representing the menubar. This object is usually not created
+by the user.
+\end{funcdesc}
+
+\begin{funcdesc}{Menu}{bar\, title\optional{\, after}}
+An object representing a menu. Upon creation you pass the
+\code{MenuBar} the menu appears in, the \var{title} string and a
+position (1-based) \var{after} where the menu should appear (default:
+at the end).
+\end{funcdesc}
+
+\begin{funcdesc}{MenuItem}{menu\, title\optional{\, shortcut\, callback}}
+Create a menu item object. The arguments are the menu to crate the
+item it, the item title string and optionally the keyboard shortcut
+and a callback routine. The callback is called with the arguments
+menu-id, item number within menu (1-based), current front window and
+the event record.
+\end{funcdesc}
+
+\begin{funcdesc}{Separator}{menu}
+Add a separator to the end of a menu.
+\end{funcdesc}
+
+\begin{funcdesc}{SubMenu}{menu\, label}
+Create a submenu named \var{label} under menu \var{menu}. The menu
+object is returned.
+\end{funcdesc}
+
+\begin{funcdesc}{Window}{parent}
+Creates a (modeless) window. \var{Parent} is the application object to
+which the window belongs. The window is not displayed until later.
+\end{funcdesc}
+
+\begin{funcdesc}{DialogWindow}{parent}
+Creates a modeless dialog window.
+\end{funcdesc}
+
+
+\subsection{Application objects}
+Application objects have the following methods, among others:
+
+\renewcommand{\indexsubitem}{(Application method)}
+
+\begin{funcdesc}{makeusermenus}{}
+Override this method if you need menus in your application. Append the
+menus to \code{self.menubar}.
+\end{funcdesc}
+
+\begin{funcdesc}{getabouttext}{}
+Override this method to return a text string describing your
+application. Alternatively, override the \code{do_about} method for
+more elaborate about messages.
+\end{funcdesc}
+
+\begin{funcdesc}{mainloop}{\optional{mask\, wait}}
+This routine is the main event loop, call it to set your application
+rolling. \var{Mask} is the mask of events you want to handle,
+\var{wait} is the number of ticks you want to leave to other
+concurrent application (default 0, which is probably not a good
+idea). This method does not return until \code{self} is raised.
+
+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.
+\end{funcdesc}
+
+\begin{funcdesc}{do_char}{c\, event}
+The user typed character \var{c}. The complete details of the event
+can be found in the \var{event} structure. This method can also be
+provided in a \code{Window} object, which overrides the
+application-wide handler if the window is frontmost.
+\end{funcdesc}
+
+\begin{funcdesc}{do_dialogevent}{event}
+Called early in the event loop to handle modeless dialog events. The
+default method simply dispatches the event to the relevant dialog (not
+through the the \code{DialogWindow} object involved). Override if you
+need special handling of dialog events (keyboard shortcuts, etc).
+\end{funcdesc}
+
+\subsection{Window Objects}
+
+Window objects have the following methods, among others:
+
+\renewcommand{\indexsubitem}{(Window method)}
+
+\begin{funcdesc}{open}{}
+Override this method to open a window. Store the MacOS window-id in
+\code{self.wid} and call \code{self.do_postopen} to register the
+window with the parent application.
+\end{funcdesc}
+
+\begin{funcdesc}{close}{}
+Override this method to do any special processing on window
+close. Call \code{self.do_postclose} to cleanup the parent state.
+\end{funcdesc}
+
+\begin{funcdesc}{do_postresize}{width\, height\, macoswindowid}
+Called after the window is resized. Override if more needs to be done
+than calling \code{InvalRect}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_contentclick}{local\, modifiers\, event}
+The user clicked in the content part of a window. The arguments are
+the coordinates (window-relative), the key modifiers and the raw
+event.
+\end{funcdesc}
+
+\begin{funcdesc}{do_update}{macoswindowid\, event}
+An update event for the window was received. Redraw the window.
+\end{funcdesc}
+
+\begin{funcdesc}{do_activate}{activate\, event}
+The window was activated (\code{activate==1}) or deactivated
+(\code{activate==0}). Handle things like focus highlighting, etc.
+\end{funcdesc}
+
+\subsection{DialogWindow Objects}
+
+DialogWindow objects have the following methods besides those of
+\code{Window} objects:
+
+\renewcommand{\indexsubitem}{(DialogWindow method)}
+
+\begin{funcdesc}{open}{resid}
+Create the dialog window, from the DLOG resource with id
+\var{resid}. The dialog object is stored in \code{self.wid}.
+\end{funcdesc}
+
+\begin{funcdesc}{do_itemhit}{item\, event}
+Item number \var{item} was hit. You are responsible for redrawing
+toggle buttons, etc.
+\end{funcdesc}
+