2 :mod:`fl` --- FORMS library for graphical user interfaces
3 =========================================================
7 :synopsis: FORMS library for applications with graphical user interfaces.
12 single: Overmars, Mark
14 This module provides an interface to the FORMS Library by Mark Overmars. The
15 source for the library can be retrieved by anonymous ftp from host
16 ``ftp.cs.ruu.nl``, directory :file:`SGI/FORMS`. It was last tested with version
19 Most functions are literal translations of their C equivalents, dropping the
20 initial ``fl_`` from their name. Constants used by the library are defined in
21 module :mod:`FL` described below.
23 The creation of objects is a little different in Python than in C: instead of
24 the 'current form' maintained by the library to which new FORMS objects are
25 added, all functions that add a FORMS object to a form are methods of the Python
26 object representing the form. Consequently, there are no Python equivalents for
27 the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the
28 equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`.
30 Watch out for the somewhat confusing terminology: FORMS uses the word
31 :dfn:`object` for the buttons, sliders etc. that you can place in a form. In
32 Python, 'object' means any value. The Python interface to FORMS introduces two
33 new Python object types: form objects (representing an entire form) and FORMS
34 objects (representing one button, slider etc.). Hopefully this isn't too
37 There are no 'free objects' in the Python interface to FORMS, nor is there an
38 easy way to add object classes written in Python. The FORMS interface to GL
39 event handling is available, though, so you can mix FORMS with pure GL windows.
41 **Please note:** importing :mod:`fl` implies a call to the GL function
42 :cfunc:`foreground` and to the FORMS routine :cfunc:`fl_init`.
47 Functions Defined in Module :mod:`fl`
48 -------------------------------------
50 Module :mod:`fl` defines the following functions. For more information about
51 what they do, see the description of the equivalent C function in the FORMS
55 .. function:: make_form(type, width, height)
57 Create a form with given type, width and height. This returns a :dfn:`form`
58 object, whose methods are described below.
61 .. function:: do_forms()
63 The standard FORMS main loop. Returns a Python object representing the FORMS
64 object needing interaction, or the special value :const:`FL.EVENT`.
67 .. function:: check_forms()
69 Check for FORMS events. Returns what :func:`do_forms` above returns, or
70 ``None`` if there is no event that immediately needs interaction.
73 .. function:: set_event_call_back(function)
75 Set the event callback function.
78 .. function:: set_graphics_mode(rgbmode, doublebuffering)
80 Set the graphics modes.
83 .. function:: get_rgbmode()
85 Return the current rgb mode. This is the value of the C global variable
89 .. function:: show_message(str1, str2, str3)
91 Show a dialog box with a three-line message and an OK button.
94 .. function:: show_question(str1, str2, str3)
96 Show a dialog box with a three-line message and YES and NO buttons. It returns
97 ``1`` if the user pressed YES, ``0`` if NO.
100 .. function:: show_choice(str1, str2, str3, but1[, but2[, but3]])
102 Show a dialog box with a three-line message and up to three buttons. It returns
103 the number of the button clicked by the user (``1``, ``2`` or ``3``).
106 .. function:: show_input(prompt, default)
108 Show a dialog box with a one-line prompt message and text field in which the
109 user can enter a string. The second argument is the default input string. It
110 returns the string value as edited by the user.
113 .. function:: show_file_selector(message, directory, pattern, default)
115 Show a dialog box in which the user can select a file. It returns the absolute
116 filename selected by the user, or ``None`` if the user presses Cancel.
119 .. function:: get_directory()
123 These functions return the directory, pattern and filename (the tail part only)
124 selected by the user in the last :func:`show_file_selector` call.
127 .. function:: qdevice(dev)
135 tie(button, valuator1, valuator2)
137 These functions are the FORMS interfaces to the corresponding GL functions. Use
138 these if you want to handle some GL events yourself when using
139 :func:`fl.do_events`. When a GL event is detected that FORMS cannot handle,
140 :func:`fl.do_forms` returns the special value :const:`FL.EVENT` and you should
141 call :func:`fl.qread` to read the event from the queue. Don't use the
142 equivalent GL functions!
144 .. \funcline{blkqread}{?}
147 .. function:: color()
151 See the description in the FORMS documentation of :cfunc:`fl_color`,
152 :cfunc:`fl_mapcolor` and :cfunc:`fl_getmcolor`.
160 Form objects (returned by :func:`make_form` above) have the following methods.
161 Each method corresponds to a C function whose name is prefixed with ``fl_``; and
162 whose first argument is a form pointer; please refer to the official FORMS
163 documentation for descriptions.
165 All the :meth:`add_\*` methods return a Python object representing the FORMS
166 object. Methods of FORMS objects are described below. Most kinds of FORMS
167 object also have some methods specific to that kind; these methods are listed
171 .. method:: form.show_form(placement, bordertype, name)
176 .. method:: form.hide_form()
181 .. method:: form.redraw_form()
186 .. method:: form.set_form_position(x, y)
188 Set the form's position.
191 .. method:: form.freeze_form()
196 .. method:: form.unfreeze_form()
201 .. method:: form.activate_form()
206 .. method:: form.deactivate_form()
211 .. method:: form.bgn_group()
213 Begin a new group of objects; return a group object.
216 .. method:: form.end_group()
218 End the current group of objects.
221 .. method:: form.find_first()
223 Find the first object in the form.
226 .. method:: form.find_last()
228 Find the last object in the form.
231 .. method:: form.add_box(type, x, y, w, h, name)
233 Add a box object to the form. No extra methods.
236 .. method:: form.add_text(type, x, y, w, h, name)
238 Add a text object to the form. No extra methods.
240 .. \begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
241 .. Add a bitmap object to the form.
245 .. method:: form.add_clock(type, x, y, w, h, name)
247 Add a clock object to the form. --- Method: :meth:`get_clock`.
250 .. method:: form.add_button(type, x, y, w, h, name)
252 Add a button object to the form. --- Methods: :meth:`get_button`,
256 .. method:: form.add_lightbutton(type, x, y, w, h, name)
258 Add a lightbutton object to the form. --- Methods: :meth:`get_button`,
262 .. method:: form.add_roundbutton(type, x, y, w, h, name)
264 Add a roundbutton object to the form. --- Methods: :meth:`get_button`,
268 .. method:: form.add_slider(type, x, y, w, h, name)
270 Add a slider object to the form. --- Methods: :meth:`set_slider_value`,
271 :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
272 :meth:`set_slider_return`, :meth:`set_slider_size`,
273 :meth:`set_slider_precision`, :meth:`set_slider_step`.
276 .. method:: form.add_valslider(type, x, y, w, h, name)
278 Add a valslider object to the form. --- Methods: :meth:`set_slider_value`,
279 :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,
280 :meth:`set_slider_return`, :meth:`set_slider_size`,
281 :meth:`set_slider_precision`, :meth:`set_slider_step`.
284 .. method:: form.add_dial(type, x, y, w, h, name)
286 Add a dial object to the form. --- Methods: :meth:`set_dial_value`,
287 :meth:`get_dial_value`, :meth:`set_dial_bounds`, :meth:`get_dial_bounds`.
290 .. method:: form.add_positioner(type, x, y, w, h, name)
292 Add a positioner object to the form. --- Methods:
293 :meth:`set_positioner_xvalue`, :meth:`set_positioner_yvalue`,
294 :meth:`set_positioner_xbounds`, :meth:`set_positioner_ybounds`,
295 :meth:`get_positioner_xvalue`, :meth:`get_positioner_yvalue`,
296 :meth:`get_positioner_xbounds`, :meth:`get_positioner_ybounds`.
299 .. method:: form.add_counter(type, x, y, w, h, name)
301 Add a counter object to the form. --- Methods: :meth:`set_counter_value`,
302 :meth:`get_counter_value`, :meth:`set_counter_bounds`, :meth:`set_counter_step`,
303 :meth:`set_counter_precision`, :meth:`set_counter_return`.
306 .. method:: form.add_input(type, x, y, w, h, name)
308 Add a input object to the form. --- Methods: :meth:`set_input`,
309 :meth:`get_input`, :meth:`set_input_color`, :meth:`set_input_return`.
312 .. method:: form.add_menu(type, x, y, w, h, name)
314 Add a menu object to the form. --- Methods: :meth:`set_menu`,
315 :meth:`get_menu`, :meth:`addto_menu`.
318 .. method:: form.add_choice(type, x, y, w, h, name)
320 Add a choice object to the form. --- Methods: :meth:`set_choice`,
321 :meth:`get_choice`, :meth:`clear_choice`, :meth:`addto_choice`,
322 :meth:`replace_choice`, :meth:`delete_choice`, :meth:`get_choice_text`,
323 :meth:`set_choice_fontsize`, :meth:`set_choice_fontstyle`.
326 .. method:: form.add_browser(type, x, y, w, h, name)
328 Add a browser object to the form. --- Methods: :meth:`set_browser_topline`,
329 :meth:`clear_browser`, :meth:`add_browser_line`, :meth:`addto_browser`,
330 :meth:`insert_browser_line`, :meth:`delete_browser_line`,
331 :meth:`replace_browser_line`, :meth:`get_browser_line`, :meth:`load_browser`,
332 :meth:`get_browser_maxline`, :meth:`select_browser_line`,
333 :meth:`deselect_browser_line`, :meth:`deselect_browser`,
334 :meth:`isselected_browser_line`, :meth:`get_browser`,
335 :meth:`set_browser_fontsize`, :meth:`set_browser_fontstyle`,
336 :meth:`set_browser_specialkey`.
339 .. method:: form.add_timer(type, x, y, w, h, name)
341 Add a timer object to the form. --- Methods: :meth:`set_timer`,
344 Form objects have the following data attributes; see the FORMS documentation:
346 +---------------------+-----------------+--------------------------------+
347 | Name | C Type | Meaning |
348 +=====================+=================+================================+
349 | :attr:`window` | int (read-only) | GL window id |
350 +---------------------+-----------------+--------------------------------+
351 | :attr:`w` | float | form width |
352 +---------------------+-----------------+--------------------------------+
353 | :attr:`h` | float | form height |
354 +---------------------+-----------------+--------------------------------+
355 | :attr:`x` | float | form x origin |
356 +---------------------+-----------------+--------------------------------+
357 | :attr:`y` | float | form y origin |
358 +---------------------+-----------------+--------------------------------+
359 | :attr:`deactivated` | int | nonzero if form is deactivated |
360 +---------------------+-----------------+--------------------------------+
361 | :attr:`visible` | int | nonzero if form is visible |
362 +---------------------+-----------------+--------------------------------+
363 | :attr:`frozen` | int | nonzero if form is frozen |
364 +---------------------+-----------------+--------------------------------+
365 | :attr:`doublebuf` | int | nonzero if double buffering on |
366 +---------------------+-----------------+--------------------------------+
374 Besides methods specific to particular kinds of FORMS objects, all FORMS objects
375 also have the following methods:
378 .. method:: FORMS object.set_call_back(function, argument)
380 Set the object's callback function and argument. When the object needs
381 interaction, the callback function will be called with two arguments: the
382 object, and the callback argument. (FORMS objects without a callback function
383 are returned by :func:`fl.do_forms` or :func:`fl.check_forms` when they need
384 interaction.) Call this method without arguments to remove the callback
388 .. method:: FORMS object.delete_object()
393 .. method:: FORMS object.show_object()
398 .. method:: FORMS object.hide_object()
403 .. method:: FORMS object.redraw_object()
408 .. method:: FORMS object.freeze_object()
413 .. method:: FORMS object.unfreeze_object()
417 FORMS objects have these data attributes; see the FORMS documentation:
419 .. \begin{methoddesc}[FORMS object]{handle_object}{} XXX
421 .. \begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
424 +--------------------+-----------------+------------------+
425 | Name | C Type | Meaning |
426 +====================+=================+==================+
427 | :attr:`objclass` | int (read-only) | object class |
428 +--------------------+-----------------+------------------+
429 | :attr:`type` | int (read-only) | object type |
430 +--------------------+-----------------+------------------+
431 | :attr:`boxtype` | int | box type |
432 +--------------------+-----------------+------------------+
433 | :attr:`x` | float | x origin |
434 +--------------------+-----------------+------------------+
435 | :attr:`y` | float | y origin |
436 +--------------------+-----------------+------------------+
437 | :attr:`w` | float | width |
438 +--------------------+-----------------+------------------+
439 | :attr:`h` | float | height |
440 +--------------------+-----------------+------------------+
441 | :attr:`col1` | int | primary color |
442 +--------------------+-----------------+------------------+
443 | :attr:`col2` | int | secondary color |
444 +--------------------+-----------------+------------------+
445 | :attr:`align` | int | alignment |
446 +--------------------+-----------------+------------------+
447 | :attr:`lcol` | int | label color |
448 +--------------------+-----------------+------------------+
449 | :attr:`lsize` | float | label font size |
450 +--------------------+-----------------+------------------+
451 | :attr:`label` | string | label string |
452 +--------------------+-----------------+------------------+
453 | :attr:`lstyle` | int | label style |
454 +--------------------+-----------------+------------------+
455 | :attr:`pushed` | int (read-only) | (see FORMS docs) |
456 +--------------------+-----------------+------------------+
457 | :attr:`focus` | int (read-only) | (see FORMS docs) |
458 +--------------------+-----------------+------------------+
459 | :attr:`belowmouse` | int (read-only) | (see FORMS docs) |
460 +--------------------+-----------------+------------------+
461 | :attr:`frozen` | int (read-only) | (see FORMS docs) |
462 +--------------------+-----------------+------------------+
463 | :attr:`active` | int (read-only) | (see FORMS docs) |
464 +--------------------+-----------------+------------------+
465 | :attr:`input` | int (read-only) | (see FORMS docs) |
466 +--------------------+-----------------+------------------+
467 | :attr:`visible` | int (read-only) | (see FORMS docs) |
468 +--------------------+-----------------+------------------+
469 | :attr:`radio` | int (read-only) | (see FORMS docs) |
470 +--------------------+-----------------+------------------+
471 | :attr:`automatic` | int (read-only) | (see FORMS docs) |
472 +--------------------+-----------------+------------------+
475 :mod:`FL` --- Constants used with the :mod:`fl` module
476 ======================================================
480 :synopsis: Constants used with the fl module.
483 This module defines symbolic constants needed to use the built-in module
484 :mod:`fl` (see above); they are equivalent to those defined in the C header file
485 ``<forms.h>`` except that the name prefix ``FL_`` is omitted. Read the module
486 source for a complete list of the defined names. Suggested use::
492 :mod:`flp` --- Functions for loading stored FORMS designs
493 =========================================================
497 :synopsis: Functions for loading stored FORMS designs.
500 This module defines functions that can read form definitions created by the
501 'form designer' (:program:`fdesign`) program that comes with the FORMS library
502 (see module :mod:`fl` above).
504 For now, see the file :file:`flp.doc` in the Python library source directory for
507 XXX A complete description should be inserted here!