1 

     2 :mod:`fl` --- FORMS library for graphical user interfaces

     3 =========================================================

     4 

     5 .. module:: fl

     6    :platform: IRIX

     7    :synopsis: FORMS library for applications with graphical user interfaces.

     8    :deprecated:

     9    

    10    

    11 .. deprecated:: 2.6

    12     The :mod:`fl` module has been deprecated for removal in Python 3.0.

    13 

    14 

    15 .. index::

    16    single: FORMS Library

    17    single: Overmars, Mark

    18 

    19 This module provides an interface to the FORMS Library by Mark Overmars.  The

    20 source for the library can be retrieved by anonymous ftp from host

    21 ``ftp.cs.ruu.nl``, directory :file:`SGI/FORMS`.  It was last tested with version

    22 2.0b.

    23 

    24 Most functions are literal translations of their C equivalents, dropping the

    25 initial ``fl_`` from their name.  Constants used by the library are defined in

    26 module :mod:`FL` described below.

    27 

    28 The creation of objects is a little different in Python than in C: instead of

    29 the 'current form' maintained by the library to which new FORMS objects are

    30 added, all functions that add a FORMS object to a form are methods of the Python

    31 object representing the form. Consequently, there are no Python equivalents for

    32 the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the

    33 equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`.

    34 

    35 Watch out for the somewhat confusing terminology: FORMS uses the word

    36 :dfn:`object` for the buttons, sliders etc. that you can place in a form. In

    37 Python, 'object' means any value.  The Python interface to FORMS introduces two

    38 new Python object types: form objects (representing an entire form) and FORMS

    39 objects (representing one button, slider etc.). Hopefully this isn't too

    40 confusing.

    41 

    42 There are no 'free objects' in the Python interface to FORMS, nor is there an

    43 easy way to add object classes written in Python.  The FORMS interface to GL

    44 event handling is available, though, so you can mix FORMS with pure GL windows.

    45 

    46 **Please note:** importing :mod:`fl` implies a call to the GL function

    47 :cfunc:`foreground` and to the FORMS routine :cfunc:`fl_init`.

    48 

    49 

    50 .. _fl-functions:

    51 

    52 Functions Defined in Module :mod:`fl`

    53 -------------------------------------

    54 

    55 Module :mod:`fl` defines the following functions.  For more information about

    56 what they do, see the description of the equivalent C function in the FORMS

    57 documentation:

    58 

    59 

    60 .. function:: make_form(type, width, height)

    61 

    62    Create a form with given type, width and height.  This returns a :dfn:`form`

    63    object, whose methods are described below.

    64 

    65 

    66 .. function:: do_forms()

    67 

    68    The standard FORMS main loop.  Returns a Python object representing the FORMS

    69    object needing interaction, or the special value :const:`FL.EVENT`.

    70 

    71 

    72 .. function:: check_forms()

    73 

    74    Check for FORMS events.  Returns what :func:`do_forms` above returns, or

    75    ``None`` if there is no event that immediately needs interaction.

    76 

    77 

    78 .. function:: set_event_call_back(function)

    79 

    80    Set the event callback function.

    81 

    82 

    83 .. function:: set_graphics_mode(rgbmode, doublebuffering)

    84 

    85    Set the graphics modes.

    86 

    87 

    88 .. function:: get_rgbmode()

    89 

    90    Return the current rgb mode.  This is the value of the C global variable

    91    :cdata:`fl_rgbmode`.

    92 

    93 

    94 .. function:: show_message(str1, str2, str3)

    95 

    96    Show a dialog box with a three-line message and an OK button.

    97 

    98 

    99 .. function:: show_question(str1, str2, str3)

   100 

   101    Show a dialog box with a three-line message and YES and NO buttons. It returns

   102    ``1`` if the user pressed YES, ``0`` if NO.

   103 

   104 

   105 .. function:: show_choice(str1, str2, str3, but1[, but2[, but3]])

   106 

   107    Show a dialog box with a three-line message and up to three buttons. It returns

   108    the number of the button clicked by the user (``1``, ``2`` or ``3``).

   109 

   110 

   111 .. function:: show_input(prompt, default)

   112 

   113    Show a dialog box with a one-line prompt message and text field in which the

   114    user can enter a string.  The second argument is the default input string.  It

   115    returns the string value as edited by the user.

   116 

   117 

   118 .. function:: show_file_selector(message, directory, pattern, default)

   119 

   120    Show a dialog box in which the user can select a file.  It returns the absolute

   121    filename selected by the user, or ``None`` if the user presses Cancel.

   122 

   123 

   124 .. function:: get_directory()

   125               get_pattern()

   126               get_filename()

   127 

   128    These functions return the directory, pattern and filename (the tail part only)

   129    selected by the user in the last :func:`show_file_selector` call.

   130 

   131 

   132 .. function:: qdevice(dev)

   133               unqdevice(dev)

   134               isqueued(dev)

   135               qtest()

   136               qread()

   137               qreset()

   138               qenter(dev, val)

   139               get_mouse()

   140               tie(button, valuator1, valuator2)

   141 

   142    These functions are the FORMS interfaces to the corresponding GL functions.  Use

   143    these if you want to handle some GL events yourself when using

   144    :func:`fl.do_events`.  When a GL event is detected that FORMS cannot handle,

   145    :func:`fl.do_forms` returns the special value :const:`FL.EVENT` and you should

   146    call :func:`fl.qread` to read the event from the queue.  Don't use the

   147    equivalent GL functions!

   148 

   149    .. \funcline{blkqread}{?}

   150 

   151 

   152 .. function:: color()

   153               mapcolor()

   154               getmcolor()

   155 

   156    See the description in the FORMS documentation of :cfunc:`fl_color`,

   157    :cfunc:`fl_mapcolor` and :cfunc:`fl_getmcolor`.

   158 

   159 

   160 .. _form-objects:

   161 

   162 Form Objects

   163 ------------

   164 

   165 Form objects (returned by :func:`make_form` above) have the following methods.

   166 Each method corresponds to a C function whose name is prefixed with ``fl_``; and

   167 whose first argument is a form pointer; please refer to the official FORMS

   168 documentation for descriptions.

   169 

   170 All the :meth:`add_\*` methods return a Python object representing the FORMS

   171 object.  Methods of FORMS objects are described below.  Most kinds of FORMS

   172 object also have some methods specific to that kind; these methods are listed

   173 here.

   174 

   175 

   176 .. method:: form.show_form(placement, bordertype, name)

   177 

   178    Show the form.

   179 

   180 

   181 .. method:: form.hide_form()

   182 

   183    Hide the form.

   184 

   185 

   186 .. method:: form.redraw_form()

   187 

   188    Redraw the form.

   189 

   190 

   191 .. method:: form.set_form_position(x, y)

   192 

   193    Set the form's position.

   194 

   195 

   196 .. method:: form.freeze_form()

   197 

   198    Freeze the form.

   199 

   200 

   201 .. method:: form.unfreeze_form()

   202 

   203    Unfreeze the form.

   204 

   205 

   206 .. method:: form.activate_form()

   207 

   208    Activate the form.

   209 

   210 

   211 .. method:: form.deactivate_form()

   212 

   213    Deactivate the form.

   214 

   215 

   216 .. method:: form.bgn_group()

   217 

   218    Begin a new group of objects; return a group object.

   219 

   220 

   221 .. method:: form.end_group()

   222 

   223    End the current group of objects.

   224 

   225 

   226 .. method:: form.find_first()

   227 

   228    Find the first object in the form.

   229 

   230 

   231 .. method:: form.find_last()

   232 

   233    Find the last object in the form.

   234 

   235 

   236 .. method:: form.add_box(type, x, y, w, h, name)

   237 

   238    Add a box object to the form. No extra methods.

   239 

   240 

   241 .. method:: form.add_text(type, x, y, w, h, name)

   242 

   243    Add a text object to the form. No extra methods.

   244 

   245 .. \begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}

   246 .. Add a bitmap object to the form.

   247 .. \end{methoddesc}

   248 

   249 

   250 .. method:: form.add_clock(type, x, y, w, h, name)

   251 

   252    Add a clock object to the form.  ---  Method: :meth:`get_clock`.

   253 

   254 

   255 .. method:: form.add_button(type, x, y, w, h,  name)

   256 

   257    Add a button object to the form.  ---  Methods: :meth:`get_button`,

   258    :meth:`set_button`.

   259 

   260 

   261 .. method:: form.add_lightbutton(type, x, y, w, h, name)

   262 

   263    Add a lightbutton object to the form.  ---  Methods: :meth:`get_button`,

   264    :meth:`set_button`.

   265 

   266 

   267 .. method:: form.add_roundbutton(type, x, y, w, h, name)

   268 

   269    Add a roundbutton object to the form.  ---  Methods: :meth:`get_button`,

   270    :meth:`set_button`.

   271 

   272 

   273 .. method:: form.add_slider(type, x, y, w, h, name)

   274 

   275    Add a slider object to the form.  ---  Methods: :meth:`set_slider_value`,

   276    :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,

   277    :meth:`set_slider_return`, :meth:`set_slider_size`,

   278    :meth:`set_slider_precision`, :meth:`set_slider_step`.

   279 

   280 

   281 .. method:: form.add_valslider(type, x, y, w, h, name)

   282 

   283    Add a valslider object to the form.  ---  Methods: :meth:`set_slider_value`,

   284    :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`,

   285    :meth:`set_slider_return`, :meth:`set_slider_size`,

   286    :meth:`set_slider_precision`, :meth:`set_slider_step`.

   287 

   288 

   289 .. method:: form.add_dial(type, x, y, w, h, name)

   290 

   291    Add a dial object to the form.  ---  Methods: :meth:`set_dial_value`,

   292    :meth:`get_dial_value`, :meth:`set_dial_bounds`, :meth:`get_dial_bounds`.

   293 

   294 

   295 .. method:: form.add_positioner(type, x, y, w, h, name)

   296 

   297    Add a positioner object to the form.  ---  Methods:

   298    :meth:`set_positioner_xvalue`, :meth:`set_positioner_yvalue`,

   299    :meth:`set_positioner_xbounds`, :meth:`set_positioner_ybounds`,

   300    :meth:`get_positioner_xvalue`, :meth:`get_positioner_yvalue`,

   301    :meth:`get_positioner_xbounds`, :meth:`get_positioner_ybounds`.

   302 

   303 

   304 .. method:: form.add_counter(type, x, y, w, h, name)

   305 

   306    Add a counter object to the form.  ---  Methods: :meth:`set_counter_value`,

   307    :meth:`get_counter_value`, :meth:`set_counter_bounds`, :meth:`set_counter_step`,

   308    :meth:`set_counter_precision`, :meth:`set_counter_return`.

   309 

   310 

   311 .. method:: form.add_input(type, x, y, w, h, name)

   312 

   313    Add a input object to the form.  ---  Methods: :meth:`set_input`,

   314    :meth:`get_input`, :meth:`set_input_color`, :meth:`set_input_return`.

   315 

   316 

   317 .. method:: form.add_menu(type, x, y, w, h, name)

   318 

   319    Add a menu object to the form.  ---  Methods: :meth:`set_menu`,

   320    :meth:`get_menu`, :meth:`addto_menu`.

   321 

   322 

   323 .. method:: form.add_choice(type, x, y, w, h, name)

   324 

   325    Add a choice object to the form.  ---  Methods: :meth:`set_choice`,

   326    :meth:`get_choice`, :meth:`clear_choice`, :meth:`addto_choice`,

   327    :meth:`replace_choice`, :meth:`delete_choice`, :meth:`get_choice_text`,

   328    :meth:`set_choice_fontsize`, :meth:`set_choice_fontstyle`.

   329 

   330 

   331 .. method:: form.add_browser(type, x, y, w, h, name)

   332 

   333    Add a browser object to the form.  ---  Methods: :meth:`set_browser_topline`,

   334    :meth:`clear_browser`, :meth:`add_browser_line`, :meth:`addto_browser`,

   335    :meth:`insert_browser_line`, :meth:`delete_browser_line`,

   336    :meth:`replace_browser_line`, :meth:`get_browser_line`, :meth:`load_browser`,

   337    :meth:`get_browser_maxline`, :meth:`select_browser_line`,

   338    :meth:`deselect_browser_line`, :meth:`deselect_browser`,

   339    :meth:`isselected_browser_line`, :meth:`get_browser`,

   340    :meth:`set_browser_fontsize`, :meth:`set_browser_fontstyle`,

   341    :meth:`set_browser_specialkey`.

   342 

   343 

   344 .. method:: form.add_timer(type, x, y, w, h, name)

   345 

   346    Add a timer object to the form.  ---  Methods: :meth:`set_timer`,

   347    :meth:`get_timer`.

   348 

   349 Form objects have the following data attributes; see the FORMS documentation:

   350 

   351 +---------------------+-----------------+--------------------------------+

   352 | Name                | C Type          | Meaning                        |

   353 +=====================+=================+================================+

   354 | :attr:`window`      | int (read-only) | GL window id                   |

   355 +---------------------+-----------------+--------------------------------+

   356 | :attr:`w`           | float           | form width                     |

   357 +---------------------+-----------------+--------------------------------+

   358 | :attr:`h`           | float           | form height                    |

   359 +---------------------+-----------------+--------------------------------+

   360 | :attr:`x`           | float           | form x origin                  |

   361 +---------------------+-----------------+--------------------------------+

   362 | :attr:`y`           | float           | form y origin                  |

   363 +---------------------+-----------------+--------------------------------+

   364 | :attr:`deactivated` | int             | nonzero if form is deactivated |

   365 +---------------------+-----------------+--------------------------------+

   366 | :attr:`visible`     | int             | nonzero if form is visible     |

   367 +---------------------+-----------------+--------------------------------+

   368 | :attr:`frozen`      | int             | nonzero if form is frozen      |

   369 +---------------------+-----------------+--------------------------------+

   370 | :attr:`doublebuf`   | int             | nonzero if double buffering on |

   371 +---------------------+-----------------+--------------------------------+

   372 

   373 

   374 .. _forms-objects:

   375 

   376 FORMS Objects

   377 -------------

   378 

   379 Besides methods specific to particular kinds of FORMS objects, all FORMS objects

   380 also have the following methods:

   381 

   382 

   383 .. method:: FORMS object.set_call_back(function, argument)

   384 

   385    Set the object's callback function and argument.  When the object needs

   386    interaction, the callback function will be called with two arguments: the

   387    object, and the callback argument.  (FORMS objects without a callback function

   388    are returned by :func:`fl.do_forms` or :func:`fl.check_forms` when they need

   389    interaction.)  Call this method without arguments to remove the callback

   390    function.

   391 

   392 

   393 .. method:: FORMS object.delete_object()

   394 

   395    Delete the object.

   396 

   397 

   398 .. method:: FORMS object.show_object()

   399 

   400    Show the object.

   401 

   402 

   403 .. method:: FORMS object.hide_object()

   404 

   405    Hide the object.

   406 

   407 

   408 .. method:: FORMS object.redraw_object()

   409 

   410    Redraw the object.

   411 

   412 

   413 .. method:: FORMS object.freeze_object()

   414 

   415    Freeze the object.

   416 

   417 

   418 .. method:: FORMS object.unfreeze_object()

   419 

   420    Unfreeze the object.

   421 

   422 FORMS objects have these data attributes; see the FORMS documentation:

   423 

   424 .. \begin{methoddesc}[FORMS object]{handle_object}{} XXX

   425 .. \end{methoddesc}

   426 .. \begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX

   427 .. \end{methoddesc}

   428 

   429 +--------------------+-----------------+------------------+

   430 | Name               | C Type          | Meaning          |

   431 +====================+=================+==================+

   432 | :attr:`objclass`   | int (read-only) | object class     |

   433 +--------------------+-----------------+------------------+

   434 | :attr:`type`       | int (read-only) | object type      |

   435 +--------------------+-----------------+------------------+

   436 | :attr:`boxtype`    | int             | box type         |

   437 +--------------------+-----------------+------------------+

   438 | :attr:`x`          | float           | x origin         |

   439 +--------------------+-----------------+------------------+

   440 | :attr:`y`          | float           | y origin         |

   441 +--------------------+-----------------+------------------+

   442 | :attr:`w`          | float           | width            |

   443 +--------------------+-----------------+------------------+

   444 | :attr:`h`          | float           | height           |

   445 +--------------------+-----------------+------------------+

   446 | :attr:`col1`       | int             | primary color    |

   447 +--------------------+-----------------+------------------+

   448 | :attr:`col2`       | int             | secondary color  |

   449 +--------------------+-----------------+------------------+

   450 | :attr:`align`      | int             | alignment        |

   451 +--------------------+-----------------+------------------+

   452 | :attr:`lcol`       | int             | label color      |

   453 +--------------------+-----------------+------------------+

   454 | :attr:`lsize`      | float           | label font size  |

   455 +--------------------+-----------------+------------------+

   456 | :attr:`label`      | string          | label string     |

   457 +--------------------+-----------------+------------------+

   458 | :attr:`lstyle`     | int             | label style      |

   459 +--------------------+-----------------+------------------+

   460 | :attr:`pushed`     | int (read-only) | (see FORMS docs) |

   461 +--------------------+-----------------+------------------+

   462 | :attr:`focus`      | int (read-only) | (see FORMS docs) |

   463 +--------------------+-----------------+------------------+

   464 | :attr:`belowmouse` | int (read-only) | (see FORMS docs) |

   465 +--------------------+-----------------+------------------+

   466 | :attr:`frozen`     | int (read-only) | (see FORMS docs) |

   467 +--------------------+-----------------+------------------+

   468 | :attr:`active`     | int (read-only) | (see FORMS docs) |

   469 +--------------------+-----------------+------------------+

   470 | :attr:`input`      | int (read-only) | (see FORMS docs) |

   471 +--------------------+-----------------+------------------+

   472 | :attr:`visible`    | int (read-only) | (see FORMS docs) |

   473 +--------------------+-----------------+------------------+

   474 | :attr:`radio`      | int (read-only) | (see FORMS docs) |

   475 +--------------------+-----------------+------------------+

   476 | :attr:`automatic`  | int (read-only) | (see FORMS docs) |

   477 +--------------------+-----------------+------------------+

   478 

   479 

   480 :mod:`FL` --- Constants used with the :mod:`fl` module

   481 ======================================================

   482 

   483 .. module:: FL

   484    :platform: IRIX

   485    :synopsis: Constants used with the fl module.

   486    :deprecated:

   487    

   488    

   489 .. deprecated:: 2.6

   490     The :mod:`FL` module has been deprecated for removal in Python 3.0.

   491 

   492 

   493 This module defines symbolic constants needed to use the built-in module

   494 :mod:`fl` (see above); they are equivalent to those defined in the C header file

   495 ``<forms.h>`` except that the name prefix ``FL_`` is omitted.  Read the module

   496 source for a complete list of the defined names.  Suggested use::

   497 

   498    import fl

   499    from FL import *

   500 

   501 

   502 :mod:`flp` --- Functions for loading stored FORMS designs

   503 =========================================================

   504 

   505 .. module:: flp

   506    :platform: IRIX

   507    :synopsis: Functions for loading stored FORMS designs.

   508    :deprecated:

   509    

   510    

   511 .. deprecated:: 2.6

   512     The :mod:`flp` module has been deprecated for removal in Python 3.0.

   513 

   514 

   515 This module defines functions that can read form definitions created by the

   516 'form designer' (:program:`fdesign`) program that comes with the FORMS library

   517 (see module :mod:`fl` above).

   518 

   519 For now, see the file :file:`flp.doc` in the Python library source directory for

   520 a description.

   521 

   522 XXX A complete description should be inserted here!

   523