|
1 .SH |
|
2 Module flp |
|
3 .LP |
|
4 The flp module loads fl-forms from fd files, as generated |
|
5 by fdesign. The module is designed to be flexible enough to allow |
|
6 almost anything to be done with the loaded form. |
|
7 .LP |
|
8 Loadform defines |
|
9 two types of functions: functions to parse fd files and functions to |
|
10 create the forms from the templates returned by the parse functions. |
|
11 There are fairly low-level create functions that create single objects, |
|
12 and convenience routines that create complete forms, including callbacks, |
|
13 etc. |
|
14 .LP |
|
15 The exception flp.error is raised whenever an error occurs while parsing a forms |
|
16 definition file or creating a form. |
|
17 .SH 2 |
|
18 Parsing functions |
|
19 .LP |
|
20 There are two parsing functions, parse_form() and parse_forms(). They |
|
21 take the following form: |
|
22 .LP |
|
23 .ft C |
|
24 ftuple = parse_form(filename, formname) |
|
25 .br |
|
26 ftdict = parse_forms(filename) |
|
27 .IP |
|
28 Parse_form parses a single form, and returns a tuple (ftmp, otmplist). |
|
29 Ftmp is a template for a form, otmplist is a list of templates for |
|
30 objects. See below for a description of these templates. |
|
31 .IP |
|
32 Parse_forms parses all forms in an fd file. It returns a dictionary of |
|
33 (ftmp, otmplist) tuples, indexed by formname. |
|
34 .IP |
|
35 Filename is the name of the forms definition file to inspect. The functions |
|
36 appends '.fd' if needed, and use 'sys.path' to locate the file. |
|
37 .IP |
|
38 formname is the name of the form to load. This argument is mandatory, |
|
39 even if the file only contains one form. |
|
40 .LP |
|
41 The form template and object template are structures that contain all |
|
42 the information read from the fd file, in 'natural' form. A form |
|
43 template record contains the following fields: |
|
44 .IP |
|
45 .nf |
|
46 "Name", the name of the form; |
|
47 "Width", the width of the form; |
|
48 "Height", the height of the form; and |
|
49 "Numberofobjects", the number of objects in the form. |
|
50 .LP |
|
51 An object template contains the following fields: |
|
52 .IP |
|
53 .nf |
|
54 "Class", the class of object (eg. FL.BUTTON); |
|
55 "Type", the sub-class (eg. FL.NORMALBUTTON); |
|
56 "Box", a list with four members: [x, y, width, height]; |
|
57 "Boxtype", the type of box (eg. FL.DOWNBOX); |
|
58 "Colors", a list with the two object colors; |
|
59 "Alignment", the label alignment (eg. FL.ALIGNLEFT); |
|
60 "Style", the label style (eg. FL.BOLDSTYLE); |
|
61 "Lcol", the label color; |
|
62 "Label", a string containing the label; |
|
63 "Name", a string containing the name of the object; |
|
64 "Callback", a string containing the callback routine name; and |
|
65 "Argument", a string containing the callback routine extra argument. |
|
66 .SH |
|
67 Low-level create routines. |
|
68 .LP |
|
69 The three low-level creation routines are called as follows: |
|
70 .LP |
|
71 .ft C |
|
72 form = create_form(form_template) |
|
73 .IP |
|
74 Create an fl form from a form template. Returns the form created. |
|
75 .LP |
|
76 .ft C |
|
77 obj = create_object(form, obj_template) |
|
78 .IP |
|
79 Create an object in an fl form. Return the new object. |
|
80 An error is raised if the object has a callback routine. |
|
81 .SH |
|
82 High-level create routines. |
|
83 .LP |
|
84 The 'standard' way to handle forms in python is to define a class |
|
85 that contains the form and all the objects (insofar as they are named), |
|
86 and that defines all the callback functions, and use an instance of |
|
87 this class to handle the form interaction. |
|
88 Flp contains three routines that simplify handling this paradigm: |
|
89 .LP |
|
90 .ft C |
|
91 create_full_form(instance, ftuple) |
|
92 .IP |
|
93 This routine takes an instance of your form-handling class and an |
|
94 ftuple (as returned by the parsing routines) as parameters. It inserts |
|
95 the form into the instance, defines all object names and arranges that |
|
96 the callback methods are called. All the names inserted into the |
|
97 instance are the same as the names used for the objects, etc. in the |
|
98 fd file. |
|
99 .LP |
|
100 .ft C |
|
101 merge_full_form(instance, form, ftuple) |
|
102 .IP |
|
103 This function does the same as create_full_form, only it does not create |
|
104 the form itself nor the 'background box' that fdesign automatically |
|
105 adds to each form. This is useful if your class inherits a superclass |
|
106 that already defines a skeleton form (with 'OK' and 'Cancel' buttons, |
|
107 for instance), and you want to merge the new form into that existing |
|
108 form. The 'form' parameter is the form to which the new objects are |
|
109 added. |
|
110 .LP |
|
111 If you use the paradigm sketched here but need slightly more control |
|
112 over object creation there is a routine that creates a single object |
|
113 and inserts its name (and arranges for the callback routine to be |
|
114 called): |
|
115 .LP |
|
116 .ft C |
|
117 create_object_instance(instance, form, obj_template) |