mirror of https://github.com/python/cpython.git
488 lines
14 KiB
TeX
488 lines
14 KiB
TeX
\section{Built-in Module \sectcode{fl}}
|
|
\label{module-fl}
|
|
\bimodindex{fl}
|
|
|
|
This module provides an interface to the FORMS Library by Mark
|
|
Overmars. 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 \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
|
|
form 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 available, 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}}
|
|
\nodename{FL Functions}
|
|
|
|
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\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 \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 Objects}
|
|
|
|
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 Objects}
|
|
|
|
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}}
|
|
\label{module-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}}
|
|
\label{module-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!
|