490 lines
14 KiB
TeX
490 lines
14 KiB
TeX
\section{Built-in Module \sectcode{fl}}
|
|
\label{module-fl}
|
|
\bimodindex{fl}
|
|
|
|
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 \module{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 \sectcode{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, 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}
|
|
|
|
Form objects (returned by \function{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 \code{add_*()} 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}
|
|
\setindexsubitem{(form 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:
|
|
\method{get_clock()}.
|
|
\end{funcdesc}
|
|
|
|
%---
|
|
|
|
\begin{funcdesc}{add_button}{type, x, y, w, h, name}
|
|
Add a button object to the form. \\
|
|
Methods:
|
|
\method{get_button()},
|
|
\method{set_button()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_lightbutton}{type, x, y, w, h, name}
|
|
Add a lightbutton object to the form. \\
|
|
Methods:
|
|
\method{get_button()},
|
|
\method{set_button()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{add_roundbutton}{type, x, y, w, h, name}
|
|
Add a roundbutton object to the form. \\
|
|
Methods:
|
|
\method{get_button()},
|
|
\method{set_button()}.
|
|
\end{funcdesc}
|
|
|
|
%---
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
%---
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
%---
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
\begin{funcdesc}{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{funcdesc}
|
|
|
|
%---
|
|
|
|
\begin{funcdesc}{add_timer}{type, x, y, w, h, name}
|
|
Add a timer object to the form. \\
|
|
Methods:
|
|
\method{set_timer()},
|
|
\method{get_timer()}.
|
|
\end{funcdesc}
|
|
\end{flushleft}
|
|
|
|
Form objects have the following data attributes; see the FORMS
|
|
documentation:
|
|
|
|
\begin{tableiii}{|l|c|l|}{member}{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 Objects}
|
|
|
|
Besides methods specific to particular kinds of FORMS objects, all
|
|
FORMS objects also have the following methods:
|
|
|
|
\setindexsubitem{(FORMS 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 \function{fl.do_forms()}
|
|
or \function{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|}{member}{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}}
|
|
\label{module-FLuppercase}
|
|
\stmodindex{FL}
|
|
|
|
This module defines symbolic constants needed to use the built-in
|
|
module \module{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{Standard Module \sectcode{flp}}
|
|
\label{module-flp}
|
|
\stmodindex{flp}
|
|
|
|
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 \module{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!
|