diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/fl.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/fl.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,523 @@ + +:mod:`fl` --- FORMS library for graphical user interfaces +========================================================= + +.. module:: fl + :platform: IRIX + :synopsis: FORMS library for applications with graphical user interfaces. + :deprecated: + + +.. deprecated:: 2.6 + The :mod:`fl` module has been deprecated for removal in Python 3.0. + + +.. index:: + single: FORMS Library + single: Overmars, Mark + +This module provides an interface to the FORMS Library by Mark Overmars. The +source for the library can be retrieved by anonymous ftp from host +``ftp.cs.ruu.nl``, directory :file:`SGI/FORMS`. It was last tested with version +2.0b. + +Most functions are literal translations of their C equivalents, dropping the +initial ``fl_`` from their name. Constants used by the library are defined in +module :mod:`FL` described below. + +The creation of objects is a little different in Python than in C: instead of +the 'current form' maintained by the library to which new FORMS objects are +added, all functions that add a FORMS object to a form are methods of the Python +object representing the form. Consequently, there are no Python equivalents for +the C functions :cfunc:`fl_addto_form` and :cfunc:`fl_end_form`, and the +equivalent of :cfunc:`fl_bgn_form` is called :func:`fl.make_form`. + +Watch out for the somewhat confusing terminology: FORMS uses the word +:dfn:`object` for the buttons, sliders etc. that you can place in a form. In +Python, 'object' means any value. The Python interface to FORMS introduces two +new Python object types: form objects (representing an entire form) and FORMS +objects (representing one button, slider etc.). Hopefully this isn't too +confusing. + +There are no 'free objects' in the Python interface to FORMS, nor is there an +easy way to add object classes written in Python. The FORMS interface to GL +event handling is available, though, so you can mix FORMS with pure GL windows. + +**Please note:** importing :mod:`fl` implies a call to the GL function +:cfunc:`foreground` and to the FORMS routine :cfunc:`fl_init`. + + +.. _fl-functions: + +Functions Defined in Module :mod:`fl` +------------------------------------- + +Module :mod:`fl` defines the following functions. For more information about +what they do, see the description of the equivalent C function in the FORMS +documentation: + + +.. function:: make_form(type, width, height) + + Create a form with given type, width and height. This returns a :dfn:`form` + object, whose methods are described below. + + +.. function:: do_forms() + + The standard FORMS main loop. Returns a Python object representing the FORMS + object needing interaction, or the special value :const:`FL.EVENT`. + + +.. function:: check_forms() + + Check for FORMS events. Returns what :func:`do_forms` above returns, or + ``None`` if there is no event that immediately needs interaction. + + +.. function:: set_event_call_back(function) + + Set the event callback function. + + +.. function:: set_graphics_mode(rgbmode, doublebuffering) + + Set the graphics modes. + + +.. function:: get_rgbmode() + + Return the current rgb mode. This is the value of the C global variable + :cdata:`fl_rgbmode`. + + +.. function:: show_message(str1, str2, str3) + + Show a dialog box with a three-line message and an OK button. + + +.. function:: show_question(str1, str2, str3) + + Show a dialog box with a three-line message and YES and NO buttons. It returns + ``1`` if the user pressed YES, ``0`` if NO. + + +.. function:: show_choice(str1, str2, str3, but1[, but2[, but3]]) + + Show a dialog box with a three-line message and up to three buttons. It returns + the number of the button clicked by the user (``1``, ``2`` or ``3``). + + +.. function:: show_input(prompt, default) + + Show a dialog box with a one-line prompt message and text field in which the + user can enter a string. The second argument is the default input string. It + returns the string value as edited by the user. + + +.. function:: show_file_selector(message, directory, pattern, default) + + Show a dialog box in which the user can select a file. It returns the absolute + filename selected by the user, or ``None`` if the user presses Cancel. + + +.. function:: get_directory() + get_pattern() + get_filename() + + These functions return the directory, pattern and filename (the tail part only) + selected by the user in the last :func:`show_file_selector` call. + + +.. function:: qdevice(dev) + unqdevice(dev) + isqueued(dev) + qtest() + qread() + qreset() + qenter(dev, val) + get_mouse() + tie(button, valuator1, valuator2) + + These functions are the FORMS interfaces to the corresponding GL functions. Use + these if you want to handle some GL events yourself when using + :func:`fl.do_events`. When a GL event is detected that FORMS cannot handle, + :func:`fl.do_forms` returns the special value :const:`FL.EVENT` and you should + call :func:`fl.qread` to read the event from the queue. Don't use the + equivalent GL functions! + + .. \funcline{blkqread}{?} + + +.. function:: color() + mapcolor() + getmcolor() + + See the description in the FORMS documentation of :cfunc:`fl_color`, + :cfunc:`fl_mapcolor` and :cfunc:`fl_getmcolor`. + + +.. _form-objects: + +Form Objects +------------ + +Form objects (returned by :func:`make_form` above) have the following methods. +Each method corresponds to a C function whose name is prefixed with ``fl_``; and +whose first argument is a form pointer; please refer to the official FORMS +documentation for descriptions. + +All the :meth:`add_\*` methods return a Python object representing the FORMS +object. Methods of FORMS objects are described below. Most kinds of FORMS +object also have some methods specific to that kind; these methods are listed +here. + + +.. method:: form.show_form(placement, bordertype, name) + + Show the form. + + +.. method:: form.hide_form() + + Hide the form. + + +.. method:: form.redraw_form() + + Redraw the form. + + +.. method:: form.set_form_position(x, y) + + Set the form's position. + + +.. method:: form.freeze_form() + + Freeze the form. + + +.. method:: form.unfreeze_form() + + Unfreeze the form. + + +.. method:: form.activate_form() + + Activate the form. + + +.. method:: form.deactivate_form() + + Deactivate the form. + + +.. method:: form.bgn_group() + + Begin a new group of objects; return a group object. + + +.. method:: form.end_group() + + End the current group of objects. + + +.. method:: form.find_first() + + Find the first object in the form. + + +.. method:: form.find_last() + + Find the last object in the form. + + +.. method:: form.add_box(type, x, y, w, h, name) + + Add a box object to the form. No extra methods. + + +.. method:: form.add_text(type, x, y, w, h, name) + + Add a text object to the form. No extra methods. + +.. \begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name} +.. Add a bitmap object to the form. +.. \end{methoddesc} + + +.. method:: form.add_clock(type, x, y, w, h, name) + + Add a clock object to the form. --- Method: :meth:`get_clock`. + + +.. method:: form.add_button(type, x, y, w, h, name) + + Add a button object to the form. --- Methods: :meth:`get_button`, + :meth:`set_button`. + + +.. method:: form.add_lightbutton(type, x, y, w, h, name) + + Add a lightbutton object to the form. --- Methods: :meth:`get_button`, + :meth:`set_button`. + + +.. method:: form.add_roundbutton(type, x, y, w, h, name) + + Add a roundbutton object to the form. --- Methods: :meth:`get_button`, + :meth:`set_button`. + + +.. method:: form.add_slider(type, x, y, w, h, name) + + Add a slider object to the form. --- Methods: :meth:`set_slider_value`, + :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`, + :meth:`set_slider_return`, :meth:`set_slider_size`, + :meth:`set_slider_precision`, :meth:`set_slider_step`. + + +.. method:: form.add_valslider(type, x, y, w, h, name) + + Add a valslider object to the form. --- Methods: :meth:`set_slider_value`, + :meth:`get_slider_value`, :meth:`set_slider_bounds`, :meth:`get_slider_bounds`, + :meth:`set_slider_return`, :meth:`set_slider_size`, + :meth:`set_slider_precision`, :meth:`set_slider_step`. + + +.. method:: form.add_dial(type, x, y, w, h, name) + + Add a dial object to the form. --- Methods: :meth:`set_dial_value`, + :meth:`get_dial_value`, :meth:`set_dial_bounds`, :meth:`get_dial_bounds`. + + +.. method:: form.add_positioner(type, x, y, w, h, name) + + Add a positioner object to the form. --- Methods: + :meth:`set_positioner_xvalue`, :meth:`set_positioner_yvalue`, + :meth:`set_positioner_xbounds`, :meth:`set_positioner_ybounds`, + :meth:`get_positioner_xvalue`, :meth:`get_positioner_yvalue`, + :meth:`get_positioner_xbounds`, :meth:`get_positioner_ybounds`. + + +.. method:: form.add_counter(type, x, y, w, h, name) + + Add a counter object to the form. --- Methods: :meth:`set_counter_value`, + :meth:`get_counter_value`, :meth:`set_counter_bounds`, :meth:`set_counter_step`, + :meth:`set_counter_precision`, :meth:`set_counter_return`. + + +.. method:: form.add_input(type, x, y, w, h, name) + + Add a input object to the form. --- Methods: :meth:`set_input`, + :meth:`get_input`, :meth:`set_input_color`, :meth:`set_input_return`. + + +.. method:: form.add_menu(type, x, y, w, h, name) + + Add a menu object to the form. --- Methods: :meth:`set_menu`, + :meth:`get_menu`, :meth:`addto_menu`. + + +.. method:: form.add_choice(type, x, y, w, h, name) + + Add a choice object to the form. --- Methods: :meth:`set_choice`, + :meth:`get_choice`, :meth:`clear_choice`, :meth:`addto_choice`, + :meth:`replace_choice`, :meth:`delete_choice`, :meth:`get_choice_text`, + :meth:`set_choice_fontsize`, :meth:`set_choice_fontstyle`. + + +.. method:: form.add_browser(type, x, y, w, h, name) + + Add a browser object to the form. --- Methods: :meth:`set_browser_topline`, + :meth:`clear_browser`, :meth:`add_browser_line`, :meth:`addto_browser`, + :meth:`insert_browser_line`, :meth:`delete_browser_line`, + :meth:`replace_browser_line`, :meth:`get_browser_line`, :meth:`load_browser`, + :meth:`get_browser_maxline`, :meth:`select_browser_line`, + :meth:`deselect_browser_line`, :meth:`deselect_browser`, + :meth:`isselected_browser_line`, :meth:`get_browser`, + :meth:`set_browser_fontsize`, :meth:`set_browser_fontstyle`, + :meth:`set_browser_specialkey`. + + +.. method:: form.add_timer(type, x, y, w, h, name) + + Add a timer object to the form. --- Methods: :meth:`set_timer`, + :meth:`get_timer`. + +Form objects have the following data attributes; see the FORMS documentation: + ++---------------------+-----------------+--------------------------------+ +| Name | C Type | Meaning | ++=====================+=================+================================+ +| :attr:`window` | int (read-only) | GL window id | ++---------------------+-----------------+--------------------------------+ +| :attr:`w` | float | form width | ++---------------------+-----------------+--------------------------------+ +| :attr:`h` | float | form height | ++---------------------+-----------------+--------------------------------+ +| :attr:`x` | float | form x origin | ++---------------------+-----------------+--------------------------------+ +| :attr:`y` | float | form y origin | ++---------------------+-----------------+--------------------------------+ +| :attr:`deactivated` | int | nonzero if form is deactivated | ++---------------------+-----------------+--------------------------------+ +| :attr:`visible` | int | nonzero if form is visible | ++---------------------+-----------------+--------------------------------+ +| :attr:`frozen` | int | nonzero if form is frozen | ++---------------------+-----------------+--------------------------------+ +| :attr:`doublebuf` | int | nonzero if double buffering on | ++---------------------+-----------------+--------------------------------+ + + +.. _forms-objects: + +FORMS Objects +------------- + +Besides methods specific to particular kinds of FORMS objects, all FORMS objects +also have the following methods: + + +.. method:: FORMS object.set_call_back(function, argument) + + Set the object's callback function and argument. When the object needs + interaction, the callback function will be called with two arguments: the + object, and the callback argument. (FORMS objects without a callback function + are returned by :func:`fl.do_forms` or :func:`fl.check_forms` when they need + interaction.) Call this method without arguments to remove the callback + function. + + +.. method:: FORMS object.delete_object() + + Delete the object. + + +.. method:: FORMS object.show_object() + + Show the object. + + +.. method:: FORMS object.hide_object() + + Hide the object. + + +.. method:: FORMS object.redraw_object() + + Redraw the object. + + +.. method:: FORMS object.freeze_object() + + Freeze the object. + + +.. method:: FORMS object.unfreeze_object() + + Unfreeze the object. + +FORMS objects have these data attributes; see the FORMS documentation: + +.. \begin{methoddesc}[FORMS object]{handle_object}{} XXX +.. \end{methoddesc} +.. \begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX +.. \end{methoddesc} + ++--------------------+-----------------+------------------+ +| Name | C Type | Meaning | ++====================+=================+==================+ +| :attr:`objclass` | int (read-only) | object class | ++--------------------+-----------------+------------------+ +| :attr:`type` | int (read-only) | object type | ++--------------------+-----------------+------------------+ +| :attr:`boxtype` | int | box type | ++--------------------+-----------------+------------------+ +| :attr:`x` | float | x origin | ++--------------------+-----------------+------------------+ +| :attr:`y` | float | y origin | ++--------------------+-----------------+------------------+ +| :attr:`w` | float | width | ++--------------------+-----------------+------------------+ +| :attr:`h` | float | height | ++--------------------+-----------------+------------------+ +| :attr:`col1` | int | primary color | ++--------------------+-----------------+------------------+ +| :attr:`col2` | int | secondary color | ++--------------------+-----------------+------------------+ +| :attr:`align` | int | alignment | ++--------------------+-----------------+------------------+ +| :attr:`lcol` | int | label color | ++--------------------+-----------------+------------------+ +| :attr:`lsize` | float | label font size | ++--------------------+-----------------+------------------+ +| :attr:`label` | string | label string | ++--------------------+-----------------+------------------+ +| :attr:`lstyle` | int | label style | ++--------------------+-----------------+------------------+ +| :attr:`pushed` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`focus` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`belowmouse` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`frozen` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`active` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`input` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`visible` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`radio` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ +| :attr:`automatic` | int (read-only) | (see FORMS docs) | ++--------------------+-----------------+------------------+ + + +:mod:`FL` --- Constants used with the :mod:`fl` module +====================================================== + +.. module:: FL + :platform: IRIX + :synopsis: Constants used with the fl module. + :deprecated: + + +.. deprecated:: 2.6 + The :mod:`FL` module has been deprecated for removal in Python 3.0. + + +This module defines symbolic constants needed to use the built-in module +:mod:`fl` (see above); they are equivalent to those defined in the C header file +```` except that the name prefix ``FL_`` is omitted. Read the module +source for a complete list of the defined names. Suggested use:: + + import fl + from FL import * + + +:mod:`flp` --- Functions for loading stored FORMS designs +========================================================= + +.. module:: flp + :platform: IRIX + :synopsis: Functions for loading stored FORMS designs. + :deprecated: + + +.. deprecated:: 2.6 + The :mod:`flp` module has been deprecated for removal in Python 3.0. + + +This module defines functions that can read form definitions created by the +'form designer' (:program:`fdesign`) program that comes with the FORMS library +(see module :mod:`fl` above). + +For now, see the file :file:`flp.doc` in the Python library source directory for +a description. + +XXX A complete description should be inserted here! +