/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
 19This module provides an interface to the FORMS Library by Mark Overmars.  The
 20source 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
 222.0b.
 23
 24Most functions are literal translations of their C equivalents, dropping the
 25initial ``fl_`` from their name.  Constants used by the library are defined in
 26module :mod:`FL` described below.
 27
 28The creation of objects is a little different in Python than in C: instead of
 29the 'current form' maintained by the library to which new FORMS objects are
 30added, all functions that add a FORMS object to a form are methods of the Python
 31object representing the form. Consequently, there are no Python equivalents for
 32the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the
 33equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`.
 34
 35Watch 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
 37Python, 'object' means any value.  The Python interface to FORMS introduces two
 38new Python object types: form objects (representing an entire form) and FORMS
 39objects (representing one button, slider etc.). Hopefully this isn't too
 40confusing.
 41
 42There are no 'free objects' in the Python interface to FORMS, nor is there an
 43easy way to add object classes written in Python.  The FORMS interface to GL
 44event 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
 52Functions Defined in Module :mod:`fl`
 53-------------------------------------
 54
 55Module :mod:`fl` defines the following functions.  For more information about
 56what they do, see the description of the equivalent C function in the FORMS
 57documentation:
 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
162Form Objects
163------------
164
165Form objects (returned by :func:`make_form` above) have the following methods.
166Each method corresponds to a C function whose name is prefixed with ``fl_``; and
167whose first argument is a form pointer; please refer to the official FORMS
168documentation for descriptions.
169
170All the :meth:`add_\*` methods return a Python object representing the FORMS
171object.  Methods of FORMS objects are described below.  Most kinds of FORMS
172object also have some methods specific to that kind; these methods are listed
173here.
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
349Form 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
376FORMS Objects
377-------------
378
379Besides methods specific to particular kinds of FORMS objects, all FORMS objects
380also 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
422FORMS 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
493This 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
496source 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
515This 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
519For now, see the file :file:`flp.doc` in the Python library source directory for
520a description.
521
522XXX A complete description should be inserted here!
523