Separate Mac user interface modules into separate files, to better support

bookmarkable module sections in the HTML.

Doc/mac/libframework.tex

@@ -0,0 +1,287 @@
+\section{Standard Module \sectcode{FrameWork}}
+\stmodindex{FrameWork}
+\label{module-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 or the examples
+for more details.
+
+The \code{FrameWork} module defines the following functions:
+
+\setindexsubitem{(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.
+
+In stead of a callable object the callback can also be a string. In
+this case menu selection causes the lookup of a method in the topmost
+window and the application. The method name is the callback string
+with \code{'domenu_'} prepended.
+
+Calling the \code{MenuBar} \code{fixmenudimstate} method sets the
+correct dimming for all menu items based on the current front window.
+\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}
+
+\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}
+
+\begin{funcdesc}{setwatchcursor}{}
+Set the mouse cursor to a watch.
+\end{funcdesc}
+
+\begin{funcdesc}{setarrowcursor}{}
+Set the mouse cursor to an arrow.
+\end{funcdesc}
+
+\subsection{Application objects}
+Application objects have the following methods, among others:
+
+\setindexsubitem{(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). While raising \code{self} to exit the mainloop is still
+supported it is not recommended, call \code{self._quit} instead.
+
+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.
+
+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}{}
+Terminate the event \code{mainloop} at the next convenient moment.
+\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}
+
+\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}
+
+Window objects have the following methods, among others:
+
+\setindexsubitem{(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{ControlsWindow Object}
+
+ControlsWindow objects have the following methods besides those of
+\code{Window} objects:
+
+\setindexsubitem{(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 methods:
+
+\setindexsubitem{(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
+\code{Window} objects:
+
+\setindexsubitem{(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}