| .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) |