add hg and python

1 files changed, 314 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/mac/libframework.tex b/sys/src/cmd/python/Doc/mac/libframework.tex
new file mode 100644
index 000000000..692c31fe4
--- /dev/null
+++ b/sys/src/cmd/python/Doc/mac/libframework.tex
@@ -0,0 +1,314 @@
+\section{\module{FrameWork} ---
+         Interactive application framework}
+
+\declaremodule{standard}{FrameWork}
+  \platform{Mac}
+\modulesynopsis{Interactive application framework.}
+
+
+The \module{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.
+
+Work on the \module{FrameWork} has pretty much stopped, now that
+\module{PyObjC} is available for full Cocoa access from Python, 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 following are some comments posted on the
+MacPython newsgroup about the strengths and limitations of
+\module{FrameWork}:
+
+\begin{quotation}
+The strong point of \module{FrameWork} is that it allows you to break
+into the control-flow at many different places. \refmodule{W}, for
+instance, uses a different way to enable/disable menus and that plugs
+right in leaving the rest intact.  The weak points of
+\module{FrameWork} are that it has no abstract command interface (but
+that shouldn't be difficult), that its dialog support is minimal and
+that its control/toolbar support is non-existent.
+\end{quotation}
+
+
+The \module{FrameWork} module defines the following functions:
+
+
+\begin{funcdesc}{Application}{}
+An object representing the complete application. See below for a
+description of the methods. The default \method{__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 create, 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.
+
+Instead 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} \method{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{(\var{left}, \var{top}, \var{right}, \var{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. However, the window will
+however always be the exact 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 \label{application-objects}}
+
+Application objects have the following methods, among others:
+
+
+\begin{methoddesc}[Application]{makeusermenus}{}
+Override this method if you need menus in your application. Append the
+menus to the attribute \member{menubar}.
+\end{methoddesc}
+
+\begin{methoddesc}[Application]{getabouttext}{}
+Override this method to return a text string describing your
+application.  Alternatively, override the \method{do_about()} method
+for more elaborate ``about'' messages.
+\end{methoddesc}
+
+\begin{methoddesc}[Application]{mainloop}{\optional{mask\optional{, 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 \var{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 \code{1} if the event is fully
+handled and \code{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 \function{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{methoddesc}
+
+\begin{methoddesc}[Application]{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 immediately
+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{methoddesc}
+
+\begin{methoddesc}[Application]{_quit}{}
+Terminate the running \method{mainloop()} call at the next convenient
+moment.
+\end{methoddesc}
+
+\begin{methoddesc}[Application]{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{methoddesc}
+
+\begin{methoddesc}[Application]{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 \code{DialogWindow} object involved). Override if you
+need special handling of dialog events (keyboard shortcuts, etc).
+\end{methoddesc}
+
+\begin{methoddesc}[Application]{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{methoddesc}
+
+
+\subsection{Window Objects \label{window-objects}}
+
+Window objects have the following methods, among others:
+
+\setindexsubitem{(Window method)}
+
+\begin{methoddesc}[Window]{open}{}
+Override this method to open a window. Store the MacOS window-id in
+\member{self.wid} and call the \method{do_postopen()} method to
+register the window with the parent application.
+\end{methoddesc}
+
+\begin{methoddesc}[Window]{close}{}
+Override this method to do any special processing on window
+close. Call the \method{do_postclose()} method to cleanup the parent
+state.
+\end{methoddesc}
+
+\begin{methoddesc}[Window]{do_postresize}{width, height, macoswindowid}
+Called after the window is resized. Override if more needs to be done
+than calling \code{InvalRect}.
+\end{methoddesc}
+
+\begin{methoddesc}[Window]{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{methoddesc}
+
+\begin{methoddesc}[Window]{do_update}{macoswindowid, event}
+An update event for the window was received. Redraw the window.
+\end{methoddesc}
+
+\begin{methoddesc}{do_activate}{activate, event}
+The window was activated (\code{\var{activate} == 1}) or deactivated
+(\code{\var{activate} == 0}). Handle things like focus highlighting,
+etc.
+\end{methoddesc}
+
+
+\subsection{ControlsWindow Object \label{controlswindow-object}}
+
+ControlsWindow objects have the following methods besides those of
+\code{Window} objects:
+
+
+\begin{methoddesc}[ControlsWindow]{do_controlhit}{window, control,
+                                                  pcode, event}
+Part \var{pcode} of control \var{control} was hit by the
+user. Tracking and such has already been taken care of.
+\end{methoddesc}
+
+
+\subsection{ScrolledWindow Object \label{scrolledwindow-object}}
+
+ScrolledWindow objects are ControlsWindow objects with the following
+extra methods:
+
+
+\begin{methoddesc}[ScrolledWindow]{scrollbars}{\optional{wantx\optional{,
+                                               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{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{getscrollbarvalues}{}
+You must supply this method. It should return a tuple \code{(\var{x},
+\var{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{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{updatescrollbars}{}
+Call this method when the document has changed. It will call
+\method{getscrollbarvalues()} and update the scrollbars.
+\end{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{scrollbar_callback}{which, what, value}
+Supplied by you and called after user interaction. \var{which} will
+be \code{'x'} or \code{'y'}, \var{what} will be \code{'-'},
+\code{'--'}, \code{'set'}, \code{'++'} or \code{'+'}. For
+\code{'set'}, \var{value} will contain the new scrollbar position.
+\end{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{scalebarvalues}{absmin, absmax,
+                                                   curmin, curmax}
+Auxiliary method to help you calculate values to return from
+\method{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{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{do_activate}{onoff, event}
+Takes care of dimming/highlighting scrollbars when a window becomes
+frontmost. If you override this method, call this one at the end of
+your method.
+\end{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{do_postresize}{width, height, window}
+Moves scrollbars to the correct position. Call this method initially
+if you override it.
+\end{methoddesc}
+
+\begin{methoddesc}[ScrolledWindow]{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{methoddesc}
+
+
+\subsection{DialogWindow Objects \label{dialogwindow-objects}}
+
+DialogWindow objects have the following methods besides those of
+\code{Window} objects:
+
+
+\begin{methoddesc}[DialogWindow]{open}{resid}
+Create the dialog window, from the DLOG resource with id
+\var{resid}. The dialog object is stored in \member{self.wid}.
+\end{methoddesc}
+
+\begin{methoddesc}[DialogWindow]{do_itemhit}{item, event}
+Item number \var{item} was hit. You are responsible for redrawing
+toggle buttons, etc.
+\end{methoddesc}