| .SH |
| Module flp |
| .LP |
| The flp module loads fl-forms from fd files, as generated |
| by fdesign. The module is designed to be flexible enough to allow |
| almost anything to be done with the loaded form. |
| .LP |
| Loadform defines |
| two types of functions: functions to parse fd files and functions to |
| create the forms from the templates returned by the parse functions. |
| There are fairly low-level create functions that create single objects, |
| and convenience routines that create complete forms, including callbacks, |
| etc. |
| .LP |
| The exception flp.error is raised whenever an error occurs while parsing a forms |
| definition file or creating a form. |
| .SH 2 |
| Parsing functions |
| .LP |
| There are two parsing functions, parse_form() and parse_forms(). They |
| take the following form: |
| .LP |
| .ft C |
| ftuple = parse_form(filename, formname) |
| .br |
| ftdict = parse_forms(filename) |
| .IP |
| Parse_form parses a single form, and returns a tuple (ftmp, otmplist). |
| Ftmp is a template for a form, otmplist is a list of templates for |
| objects. See below for a description of these templates. |
| .IP |
| Parse_forms parses all forms in an fd file. It returns a dictionary of |
| (ftmp, otmplist) tuples, indexed by formname. |
| .IP |
| Filename is the name of the forms definition file to inspect. The functions |
| appends '.fd' if needed, and use 'sys.path' to locate the file. |
| .IP |
| formname is the name of the form to load. This argument is mandatory, |
| even if the file only contains one form. |
| .LP |
| The form template and object template are structures that contain all |
| the information read from the fd file, in 'natural' form. A form |
| template record contains the following fields: |
| .IP |
| .nf |
| "Name", the name of the form; |
| "Width", the width of the form; |
| "Height", the height of the form; and |
| "Numberofobjects", the number of objects in the form. |
| .LP |
| An object template contains the following fields: |
| .IP |
| .nf |
| "Class", the class of object (eg. FL.BUTTON); |
| "Type", the sub-class (eg. FL.NORMALBUTTON); |
| "Box", a list with four members: [x, y, width, height]; |
| "Boxtype", the type of box (eg. FL.DOWNBOX); |
| "Colors", a list with the two object colors; |
| "Alignment", the label alignment (eg. FL.ALIGNLEFT); |
| "Style", the label style (eg. FL.BOLDSTYLE); |
| "Lcol", the label color; |
| "Label", a string containing the label; |
| "Name", a string containing the name of the object; |
| "Callback", a string containing the callback routine name; and |
| "Argument", a string containing the callback routine extra argument. |
| .SH |
| Low-level create routines. |
| .LP |
| The three low-level creation routines are called as follows: |
| .LP |
| .ft C |
| form = create_form(form_template) |
| .IP |
| Create an fl form from a form template. Returns the form created. |
| .LP |
| .ft C |
| obj = create_object(form, obj_template) |
| .IP |
| Create an object in an fl form. Return the new object. |
| An error is raised if the object has a callback routine. |
| .SH |
| High-level create routines. |
| .LP |
| The 'standard' way to handle forms in python is to define a class |
| that contains the form and all the objects (insofar as they are named), |
| and that defines all the callback functions, and use an instance of |
| this class to handle the form interaction. |
| Flp contains three routines that simplify handling this paradigm: |
| .LP |
| .ft C |
| create_full_form(instance, ftuple) |
| .IP |
| This routine takes an instance of your form-handling class and an |
| ftuple (as returned by the parsing routines) as parameters. It inserts |
| the form into the instance, defines all object names and arranges that |
| the callback methods are called. All the names inserted into the |
| instance are the same as the names used for the objects, etc. in the |
| fd file. |
| .LP |
| .ft C |
| merge_full_form(instance, form, ftuple) |
| .IP |
| This function does the same as create_full_form, only it does not create |
| the form itself nor the 'background box' that fdesign automatically |
| adds to each form. This is useful if your class inherits a superclass |
| that already defines a skeleton form (with 'OK' and 'Cancel' buttons, |
| for instance), and you want to merge the new form into that existing |
| form. The 'form' parameter is the form to which the new objects are |
| added. |
| .LP |
| If you use the paradigm sketched here but need slightly more control |
| over object creation there is a routine that creates a single object |
| and inserts its name (and arranges for the callback routine to be |
| called): |
| .LP |
| .ft C |
| create_object_instance(instance, form, obj_template) |
