add hg and python

1 files changed, 507 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libfl.tex b/sys/src/cmd/python/Doc/lib/libfl.tex
new file mode 100644
index 000000000..bafb8e49b
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libfl.tex
@@ -0,0 +1,507 @@
+\section{\module{fl} ---
+         FORMS library for graphical user interfaces}
+
+\declaremodule{builtin}{fl}
+  \platform{IRIX}
+\modulesynopsis{FORMS library for applications with graphical user
+                interfaces.}
+
+
+This module provides an interface to the FORMS Library\index{FORMS
+Library} by Mark Overmars\index{Overmars, Mark}.  The source for the
+library can be retrieved by anonymous ftp from host
+\samp{ftp.cs.ruu.nl}, directory \file{SGI/FORMS}.  It was last tested
+with version 2.0b.
+
+Most functions are literal translations of their C equivalents,
+dropping the initial \samp{fl_} from their name.  Constants used by
+the library are defined in module \refmodule[fl-constants]{FL}
+described below.
+
+The creation of objects is a little different in Python than in C:
+instead of the `current form' maintained by the library to which new
+FORMS objects are added, all functions that add a FORMS object to a
+form are methods of the Python object representing the form.
+Consequently, there are no Python equivalents for the C functions
+\cfunction{fl_addto_form()} and \cfunction{fl_end_form()}, and the
+equivalent of \cfunction{fl_bgn_form()} is called
+\function{fl.make_form()}.
+
+Watch out for the somewhat confusing terminology: FORMS uses the word
+\dfn{object} for the buttons, sliders etc. that you can place in a form.
+In Python, `object' means any value.  The Python interface to FORMS
+introduces two new Python object types: form objects (representing an
+entire form) and FORMS objects (representing one button, slider etc.).
+Hopefully this isn't too confusing.
+
+There are no `free objects' in the Python interface to FORMS, nor is
+there an easy way to add object classes written in Python.  The FORMS
+interface to GL event handling is available, though, so you can mix
+FORMS with pure GL windows.
+
+\strong{Please note:} importing \module{fl} implies a call to the GL
+function \cfunction{foreground()} and to the FORMS routine
+\cfunction{fl_init()}.
+
+\subsection{Functions Defined in Module \module{fl}}
+\nodename{FL Functions}
+
+Module \module{fl} defines the following functions.  For more
+information about what they do, see the description of the equivalent
+C function in the FORMS documentation:
+
+\begin{funcdesc}{make_form}{type, width, height}
+Create a form with given type, width and height.  This returns a
+\dfn{form} object, whose methods are described below.
+\end{funcdesc}
+
+\begin{funcdesc}{do_forms}{}
+The standard FORMS main loop.  Returns a Python object representing
+the FORMS object needing interaction, or the special value
+\constant{FL.EVENT}.
+\end{funcdesc}
+
+\begin{funcdesc}{check_forms}{}
+Check for FORMS events.  Returns what \function{do_forms()} above
+returns, or \code{None} if there is no event that immediately needs
+interaction.
+\end{funcdesc}
+
+\begin{funcdesc}{set_event_call_back}{function}
+Set the event callback function.
+\end{funcdesc}
+
+\begin{funcdesc}{set_graphics_mode}{rgbmode, doublebuffering}
+Set the graphics modes.
+\end{funcdesc}
+
+\begin{funcdesc}{get_rgbmode}{}
+Return the current rgb mode.  This is the value of the C global
+variable \cdata{fl_rgbmode}.
+\end{funcdesc}
+
+\begin{funcdesc}{show_message}{str1, str2, str3}
+Show a dialog box with a three-line message and an OK button.
+\end{funcdesc}
+
+\begin{funcdesc}{show_question}{str1, str2, str3}
+Show a dialog box with a three-line message and YES and NO buttons.
+It returns \code{1} if the user pressed YES, \code{0} if NO.
+\end{funcdesc}
+
+\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{,
+                              but2\optional{, but3}}}
+Show a dialog box with a three-line message and up to three buttons.
+It returns the number of the button clicked by the user
+(\code{1}, \code{2} or \code{3}).
+\end{funcdesc}
+
+\begin{funcdesc}{show_input}{prompt, default}
+Show a dialog box with a one-line prompt message and text field in
+which the user can enter a string.  The second argument is the default
+input string.  It returns the string value as edited by the user.
+\end{funcdesc}
+
+\begin{funcdesc}{show_file_selector}{message, directory, pattern, default}
+Show a dialog box in which the user can select a file.  It returns
+the absolute filename selected by the user, or \code{None} if the user
+presses Cancel.
+\end{funcdesc}
+
+\begin{funcdesc}{get_directory}{}
+\funcline{get_pattern}{}
+\funcline{get_filename}{}
+These functions return the directory, pattern and filename (the tail
+part only) selected by the user in the last
+\function{show_file_selector()} call.
+\end{funcdesc}
+
+\begin{funcdesc}{qdevice}{dev}
+\funcline{unqdevice}{dev}
+\funcline{isqueued}{dev}
+\funcline{qtest}{}
+\funcline{qread}{}
+%\funcline{blkqread}{?}
+\funcline{qreset}{}
+\funcline{qenter}{dev, val}
+\funcline{get_mouse}{}
+\funcline{tie}{button, valuator1, valuator2}
+These functions are the FORMS interfaces to the corresponding GL
+functions.  Use these if you want to handle some GL events yourself
+when using \function{fl.do_events()}.  When a GL event is detected that
+FORMS cannot handle, \function{fl.do_forms()} returns the special value
+\constant{FL.EVENT} and you should call \function{fl.qread()} to read
+the event from the queue.  Don't use the equivalent GL functions!
+\end{funcdesc}
+
+\begin{funcdesc}{color}{}
+\funcline{mapcolor}{}
+\funcline{getmcolor}{}
+See the description in the FORMS documentation of
+\cfunction{fl_color()}, \cfunction{fl_mapcolor()} and
+\cfunction{fl_getmcolor()}.
+\end{funcdesc}
+
+\subsection{Form Objects}
+\label{form-objects}
+
+Form objects (returned by \function{make_form()} above) have the
+following methods.  Each method corresponds to a C function whose
+name is prefixed with \samp{fl_}; and whose first argument is a form
+pointer; please refer to the official FORMS documentation for
+descriptions.
+
+All the \method{add_*()} methods return a Python object representing
+the FORMS object.  Methods of FORMS objects are described below.  Most
+kinds of FORMS object also have some methods specific to that kind;
+these methods are listed here.
+
+\begin{flushleft}
+
+\begin{methoddesc}[form]{show_form}{placement, bordertype, name}
+  Show the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{hide_form}{}
+  Hide the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{redraw_form}{}
+  Redraw the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{set_form_position}{x, y}
+Set the form's position.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{freeze_form}{}
+Freeze the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{unfreeze_form}{}
+  Unfreeze the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{activate_form}{}
+  Activate the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{deactivate_form}{}
+  Deactivate the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{bgn_group}{}
+  Begin a new group of objects; return a group object.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{end_group}{}
+  End the current group of objects.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{find_first}{}
+  Find the first object in the form.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{find_last}{}
+  Find the last object in the form.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name}
+Add a box object to the form.
+No extra methods.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name}
+Add a text object to the form.
+No extra methods.
+\end{methoddesc}
+
+%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
+%Add a bitmap object to the form.
+%\end{methoddesc}
+
+\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name}
+Add a clock object to the form. \\
+Method:
+\method{get_clock()}.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_button}{type, x, y, w, h,  name}
+Add a button object to the form. \\
+Methods:
+\method{get_button()},
+\method{set_button()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name}
+Add a lightbutton object to the form. \\
+Methods:
+\method{get_button()},
+\method{set_button()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name}
+Add a roundbutton object to the form. \\
+Methods:
+\method{get_button()},
+\method{set_button()}.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name}
+Add a slider object to the form. \\
+Methods:
+\method{set_slider_value()},
+\method{get_slider_value()},
+\method{set_slider_bounds()},
+\method{get_slider_bounds()},
+\method{set_slider_return()},
+\method{set_slider_size()},
+\method{set_slider_precision()},
+\method{set_slider_step()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name}
+Add a valslider object to the form. \\
+Methods:
+\method{set_slider_value()},
+\method{get_slider_value()},
+\method{set_slider_bounds()},
+\method{get_slider_bounds()},
+\method{set_slider_return()},
+\method{set_slider_size()},
+\method{set_slider_precision()},
+\method{set_slider_step()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name}
+Add a dial object to the form. \\
+Methods:
+\method{set_dial_value()},
+\method{get_dial_value()},
+\method{set_dial_bounds()},
+\method{get_dial_bounds()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name}
+Add a positioner object to the form. \\
+Methods:
+\method{set_positioner_xvalue()},
+\method{set_positioner_yvalue()},
+\method{set_positioner_xbounds()},
+\method{set_positioner_ybounds()},
+\method{get_positioner_xvalue()},
+\method{get_positioner_yvalue()},
+\method{get_positioner_xbounds()},
+\method{get_positioner_ybounds()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name}
+Add a counter object to the form. \\
+Methods:
+\method{set_counter_value()},
+\method{get_counter_value()},
+\method{set_counter_bounds()},
+\method{set_counter_step()},
+\method{set_counter_precision()},
+\method{set_counter_return()}.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name}
+Add a input object to the form. \\
+Methods:
+\method{set_input()},
+\method{get_input()},
+\method{set_input_color()},
+\method{set_input_return()}.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name}
+Add a menu object to the form. \\
+Methods:
+\method{set_menu()},
+\method{get_menu()},
+\method{addto_menu()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name}
+Add a choice object to the form. \\
+Methods:
+\method{set_choice()},
+\method{get_choice()},
+\method{clear_choice()},
+\method{addto_choice()},
+\method{replace_choice()},
+\method{delete_choice()},
+\method{get_choice_text()},
+\method{set_choice_fontsize()},
+\method{set_choice_fontstyle()}.
+\end{methoddesc}
+
+\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name}
+Add a browser object to the form. \\
+Methods:
+\method{set_browser_topline()},
+\method{clear_browser()},
+\method{add_browser_line()},
+\method{addto_browser()},
+\method{insert_browser_line()},
+\method{delete_browser_line()},
+\method{replace_browser_line()},
+\method{get_browser_line()},
+\method{load_browser()},
+\method{get_browser_maxline()},
+\method{select_browser_line()},
+\method{deselect_browser_line()},
+\method{deselect_browser()},
+\method{isselected_browser_line()},
+\method{get_browser()},
+\method{set_browser_fontsize()},
+\method{set_browser_fontstyle()},
+\method{set_browser_specialkey()}.
+\end{methoddesc}
+
+%---
+
+\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name}
+Add a timer object to the form. \\
+Methods:
+\method{set_timer()},
+\method{get_timer()}.
+\end{methoddesc}
+\end{flushleft}
+
+Form objects have the following data attributes; see the FORMS
+documentation:
+
+\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning}
+  \lineiii{window}{int (read-only)}{GL window id}
+  \lineiii{w}{float}{form width}
+  \lineiii{h}{float}{form height}
+  \lineiii{x}{float}{form x origin}
+  \lineiii{y}{float}{form y origin}
+  \lineiii{deactivated}{int}{nonzero if form is deactivated}
+  \lineiii{visible}{int}{nonzero if form is visible}
+  \lineiii{frozen}{int}{nonzero if form is frozen}
+  \lineiii{doublebuf}{int}{nonzero if double buffering on}
+\end{tableiii}
+
+\subsection{FORMS Objects}
+\label{forms-objects}
+
+Besides methods specific to particular kinds of FORMS objects, all
+FORMS objects also have the following methods:
+
+\begin{methoddesc}[FORMS object]{set_call_back}{function, argument}
+Set the object's callback function and argument.  When the object
+needs interaction, the callback function will be called with two
+arguments: the object, and the callback argument.  (FORMS objects
+without a callback function are returned by \function{fl.do_forms()}
+or \function{fl.check_forms()} when they need interaction.)  Call this
+method without arguments to remove the callback function.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{delete_object}{}
+  Delete the object.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{show_object}{}
+  Show the object.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{hide_object}{}
+  Hide the object.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{redraw_object}{}
+  Redraw the object.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{freeze_object}{}
+  Freeze the object.
+\end{methoddesc}
+
+\begin{methoddesc}[FORMS object]{unfreeze_object}{}
+  Unfreeze the object.
+\end{methoddesc}
+
+%\begin{methoddesc}[FORMS object]{handle_object}{} XXX
+%\end{methoddesc}
+
+%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
+%\end{methoddesc}
+
+FORMS objects have these data attributes; see the FORMS documentation:
+
+\begin{tableiii}{l|l|l}{member}{Name}{C Type}{Meaning}
+  \lineiii{objclass}{int (read-only)}{object class}
+  \lineiii{type}{int (read-only)}{object type}
+  \lineiii{boxtype}{int}{box type}
+  \lineiii{x}{float}{x origin}
+  \lineiii{y}{float}{y origin}
+  \lineiii{w}{float}{width}
+  \lineiii{h}{float}{height}
+  \lineiii{col1}{int}{primary color}
+  \lineiii{col2}{int}{secondary color}
+  \lineiii{align}{int}{alignment}
+  \lineiii{lcol}{int}{label color}
+  \lineiii{lsize}{float}{label font size}
+  \lineiii{label}{string}{label string}
+  \lineiii{lstyle}{int}{label style}
+  \lineiii{pushed}{int (read-only)}{(see FORMS docs)}
+  \lineiii{focus}{int (read-only)}{(see FORMS docs)}
+  \lineiii{belowmouse}{int (read-only)}{(see FORMS docs)}
+  \lineiii{frozen}{int (read-only)}{(see FORMS docs)}
+  \lineiii{active}{int (read-only)}{(see FORMS docs)}
+  \lineiii{input}{int (read-only)}{(see FORMS docs)}
+  \lineiii{visible}{int (read-only)}{(see FORMS docs)}
+  \lineiii{radio}{int (read-only)}{(see FORMS docs)}
+  \lineiii{automatic}{int (read-only)}{(see FORMS docs)}
+\end{tableiii}
+
+
+\section{\module{FL} ---
+         Constants used with the \module{fl} module}
+
+\declaremodule[fl-constants]{standard}{FL}
+  \platform{IRIX}
+\modulesynopsis{Constants used with the \module{fl} module.}
+
+
+This module defines symbolic constants needed to use the built-in
+module \refmodule{fl} (see above); they are equivalent to those defined in
+the C header file \code{<forms.h>} except that the name prefix
+\samp{FL_} is omitted.  Read the module source for a complete list of
+the defined names.  Suggested use:
+
+\begin{verbatim}
+import fl
+from FL import *
+\end{verbatim}
+
+
+\section{\module{flp} ---
+         Functions for loading stored FORMS designs}
+
+\declaremodule{standard}{flp}
+  \platform{IRIX}
+\modulesynopsis{Functions for loading stored FORMS designs.}
+
+
+This module defines functions that can read form definitions created
+by the `form designer' (\program{fdesign}) program that comes with the
+FORMS library (see module \refmodule{fl} above).
+
+For now, see the file \file{flp.doc} in the Python library source
+directory for a description.
+
+XXX A complete description should be inserted here!