diff options
Diffstat (limited to 'Doc/libfl.tex')
| -rw-r--r-- | Doc/libfl.tex | 483 |
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! |