Documented MACFS, macostools, EasyDialogs and FrameWork modules.

1 files changed, 201 insertions, 0 deletions

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}
+