Doc/library/fl.rst

   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 :c:func:`fl_addto_form` and :c:func:`fl_end_form`, and the
  33 equivalent of :c:func:`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 :c:func:`foreground` and to the FORMS routine :c:func:`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    :c:data:`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 :c:func:`fl_color`,
 157    :c:func:`fl_mapcolor` and :c:func:`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