Restructured library documentation

1 files changed, 483 insertions, 0 deletions

diff --git a/Doc/libfl.tex b/Doc/libfl.tex
new file mode 100644
index 0000000..b705a6b
--- /dev/null
+++ b/Doc/libfl.tex
@@ -0,0 +1,483 @@
+\section{Built-in Module \sectcode{fl}}
+\bimodindex{fl}
+
+This module provides an interface to the FORMS Library by Mark
+Overmars, version 2.0b.  For more info about FORMS, write to
+{\tt markov@cs.ruu.nl}.
+
+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 \code{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
+button are methods of the Python object representing the form.
+Consequently, there are no Python equivalents for the C functions
+\code{fl_addto_form} and \code{fl_end_form}, and the equivalent of
+\code{fl_bgn_form} is called \code{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 avaiable, though, so you can mix
+FORMS with pure GL windows.
+
+\strong{Please note:} importing \code{fl} implies a call to the GL function
+\code{foreground()} and to the FORMS routine \code{fl_init()}.
+
+\subsection{Functions defined in module \sectcode{fl}}
+
+Module \code{fl} defines the following functions.  For more information
+about what they do, see the description of the equivalent C function
+in the FORMS documentation:
+
+\renewcommand{\indexsubitem}{(in module fl)}
+\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
+\code{FL.EVENT}.
+\end{funcdesc}
+
+\begin{funcdesc}{check_forms}{}
+Check for FORMS events.  Returns what \code{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 \code{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\, but2\, 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}).
+The \var{but2} and \var{but3} arguments are optional.
+\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 inm 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 \code{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 \code{fl.do_events}.  When a GL event is detected that
+FORMS cannot handle, \code{fl.do_forms()} returns the special value
+\code{FL.EVENT} and you should call \code{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 \code{fl_color},
+\code{fl_mapcolor} and \code{fl_getmcolor}.
+\end{funcdesc}
+
+\subsection{Form object methods and data attributes}
+
+Form objects (returned by \code{fl.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 \samp{add_{\rm \ldots}} functions 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}
+\renewcommand{\indexsubitem}{(form object method)}
+\begin{funcdesc}{show_form}{placement\, bordertype\, name}
+  Show the form.
+\end{funcdesc}
+
+\begin{funcdesc}{hide_form}{}
+  Hide the form.
+\end{funcdesc}
+
+\begin{funcdesc}{redraw_form}{}
+  Redraw the form.
+\end{funcdesc}
+
+\begin{funcdesc}{set_form_position}{x\, y}
+Set the form's position.
+\end{funcdesc}
+
+\begin{funcdesc}{freeze_form}{}
+Freeze the form.
+\end{funcdesc}
+
+\begin{funcdesc}{unfreeze_form}{}
+  Unfreeze the form.
+\end{funcdesc}
+
+\begin{funcdesc}{activate_form}{}
+  Activate the form.
+\end{funcdesc}
+
+\begin{funcdesc}{deactivate_form}{}
+  Deactivate the form.
+\end{funcdesc}
+
+\begin{funcdesc}{bgn_group}{}
+  Begin a new group of objects; return a group object.
+\end{funcdesc}
+
+\begin{funcdesc}{end_group}{}
+  End the current group of objects.
+\end{funcdesc}
+
+\begin{funcdesc}{find_first}{}
+  Find the first object in the form.
+\end{funcdesc}
+
+\begin{funcdesc}{find_last}{}
+  Find the last object in the form.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_box}{type\, x\, y\, w\, h\, name}
+Add a box object to the form.
+No extra methods.
+\end{funcdesc}
+
+\begin{funcdesc}{add_text}{type\, x\, y\, w\, h\, name}
+Add a text object to the form.
+No extra methods.
+\end{funcdesc}
+
+%\begin{funcdesc}{add_bitmap}{type\, x\, y\, w\, h\, name}
+%Add a bitmap object to the form.
+%\end{funcdesc}
+
+\begin{funcdesc}{add_clock}{type\, x\, y\, w\, h\, name}
+Add a clock object to the form. \\
+Method:
+\code{get_clock}.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_button}{type\, x\, y\, w\, h\,  name}
+Add a button object to the form. \\
+Methods:
+\code{get_button},
+\code{set_button}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_lightbutton}{type\, x\, y\, w\, h\, name}
+Add a lightbutton object to the form. \\
+Methods:
+\code{get_button},
+\code{set_button}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_roundbutton}{type\, x\, y\, w\, h\, name}
+Add a roundbutton object to the form. \\
+Methods:
+\code{get_button},
+\code{set_button}.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_slider}{type\, x\, y\, w\, h\, name}
+Add a slider object to the form. \\
+Methods:
+\code{set_slider_value},
+\code{get_slider_value},
+\code{set_slider_bounds},
+\code{get_slider_bounds},
+\code{set_slider_return},
+\code{set_slider_size},
+\code{set_slider_precision},
+\code{set_slider_step}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_valslider}{type\, x\, y\, w\, h\, name}
+Add a valslider object to the form. \\
+Methods:
+\code{set_slider_value},
+\code{get_slider_value},
+\code{set_slider_bounds},
+\code{get_slider_bounds},
+\code{set_slider_return},
+\code{set_slider_size},
+\code{set_slider_precision},
+\code{set_slider_step}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_dial}{type\, x\, y\, w\, h\, name}
+Add a dial object to the form. \\
+Methods:
+\code{set_dial_value},
+\code{get_dial_value},
+\code{set_dial_bounds},
+\code{get_dial_bounds}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_positioner}{type\, x\, y\, w\, h\, name}
+Add a positioner object to the form. \\
+Methods:
+\code{set_positioner_xvalue},
+\code{set_positioner_yvalue},
+\code{set_positioner_xbounds},
+\code{set_positioner_ybounds},
+\code{get_positioner_xvalue},
+\code{get_positioner_yvalue},
+\code{get_positioner_xbounds},
+\code{get_positioner_ybounds}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_counter}{type\, x\, y\, w\, h\, name}
+Add a counter object to the form. \\
+Methods:
+\code{set_counter_value},
+\code{get_counter_value},
+\code{set_counter_bounds},
+\code{set_counter_step},
+\code{set_counter_precision},
+\code{set_counter_return}.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_input}{type\, x\, y\, w\, h\, name}
+Add a input object to the form. \\
+Methods:
+\code{set_input},
+\code{get_input},
+\code{set_input_color},
+\code{set_input_return}.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_menu}{type\, x\, y\, w\, h\, name}
+Add a menu object to the form. \\
+Methods:
+\code{set_menu},
+\code{get_menu},
+\code{addto_menu}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_choice}{type\, x\, y\, w\, h\, name}
+Add a choice object to the form. \\
+Methods:
+\code{set_choice},
+\code{get_choice},
+\code{clear_choice},
+\code{addto_choice},
+\code{replace_choice},
+\code{delete_choice},
+\code{get_choice_text},
+\code{set_choice_fontsize},
+\code{set_choice_fontstyle}.
+\end{funcdesc}
+
+\begin{funcdesc}{add_browser}{type\, x\, y\, w\, h\, name}
+Add a browser object to the form. \\
+Methods:
+\code{set_browser_topline},
+\code{clear_browser},
+\code{add_browser_line},
+\code{addto_browser},
+\code{insert_browser_line},
+\code{delete_browser_line},
+\code{replace_browser_line},
+\code{get_browser_line},
+\code{load_browser},
+\code{get_browser_maxline},
+\code{select_browser_line},
+\code{deselect_browser_line},
+\code{deselect_browser},
+\code{isselected_browser_line},
+\code{get_browser},
+\code{set_browser_fontsize},
+\code{set_browser_fontstyle},
+\code{set_browser_specialkey}.
+\end{funcdesc}
+
+%---
+
+\begin{funcdesc}{add_timer}{type\, x\, y\, w\, h\, name}
+Add a timer object to the form. \\
+Methods:
+\code{set_timer},
+\code{get_timer}.
+\end{funcdesc}
+\end{flushleft}
+
+Form objects have the following data attributes; see the FORMS
+documentation:
+
+\begin{tableiii}{|l|c|l|}{code}{Name}{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 object methods and data attributes}
+
+Besides methods specific to particular kinds of FORMS objects, all
+FORMS objects also have the following methods:
+
+\renewcommand{\indexsubitem}{(FORMS object method)}
+\begin{funcdesc}{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 \code{fl.do_forms()} or
+\code{fl.check_forms()} when they need interaction.)  Call this method
+without arguments to remove the callback function.
+\end{funcdesc}
+
+\begin{funcdesc}{delete_object}{}
+  Delete the object.
+\end{funcdesc}
+
+\begin{funcdesc}{show_object}{}
+  Show the object.
+\end{funcdesc}
+
+\begin{funcdesc}{hide_object}{}
+  Hide the object.
+\end{funcdesc}
+
+\begin{funcdesc}{redraw_object}{}
+  Redraw the object.
+\end{funcdesc}
+
+\begin{funcdesc}{freeze_object}{}
+  Freeze the object.
+\end{funcdesc}
+
+\begin{funcdesc}{unfreeze_object}{}
+  Unfreeze the object.
+\end{funcdesc}
+
+%\begin{funcdesc}{handle_object}{} XXX
+%\end{funcdesc}
+
+%\begin{funcdesc}{handle_object_direct}{} XXX
+%\end{funcdesc}
+
+FORMS objects have these data attributes; see the FORMS documentation:
+
+\begin{tableiii}{|l|c|l|}{code}{Name}{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{Standard Module \sectcode{FL}}
+\nodename{FL (uppercase)}
+\stmodindex{FL}
+
+This module defines symbolic constants needed to use the built-in
+module \code{fl} (see above); they are equivalent to those defined in
+the C header file \file{<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:
+
+\bcode\begin{verbatim}
+import fl
+from FL import *
+\end{verbatim}\ecode
+
+\section{Standard Module \sectcode{flp}}
+\stmodindex{flp}
+
+This module defines functions that can read form definitions created
+by the `form designer' (\code{fdesign}) program that comes with the
+FORMS library (see module \code{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!