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 removed in Python 3. 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 :c:func:`fl_addto_form` and :c:func:`fl_end_form`, and the 33equivalent of :c:func:`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:c:func:`foreground` and to the FORMS routine :c:func:`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 :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 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 an 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 removed in Python 3. 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 removed in Python 3. 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 524