blob: 1a2f374ae7ab4d62f5d100201b759cecbb50c85f [file] [log] [blame]
Guido van Rossumb5a40dc1992-03-27 15:10:29 +00001.SH
2Module flp
3.LP
4The flp module loads fl-forms from fd files, as generated
5by fdesign. The module is designed to be flexible enough to allow
6almost anything to be done with the loaded form.
7.LP
8Loadform defines
9two types of functions: functions to parse fd files and functions to
10create the forms from the templates returned by the parse functions.
11There are fairly low-level create functions that create single objects,
12and convenience routines that create complete forms, including callbacks,
13etc.
14.LP
15The exception flp.error is raised whenever an error occurs while parsing a forms
16definition file or creating a form.
17.SH 2
18Parsing functions
19.LP
20There are two parsing functions, parse_form() and parse_forms(). They
21take the following form:
22.LP
23.ft C
24ftuple = parse_form(filename, formname)
25.br
26ftdict = parse_forms(filename)
27.IP
28Parse_form parses a single form, and returns a tuple (ftmp, otmplist).
29Ftmp is a template for a form, otmplist is a list of templates for
30objects. See below for a description of these templates.
31.IP
32Parse_forms parses all forms in an fd file. It returns a dictionary of
33(ftmp, otmplist) tuples, indexed by formname.
34.IP
35Filename is the name of the forms definition file to inspect. The functions
36appends '.fd' if needed, and use 'sys.path' to locate the file.
37.IP
38formname is the name of the form to load. This argument is mandatory,
39even if the file only contains one form.
40.LP
41The form template and object template are structures that contain all
42the information read from the fd file, in 'natural' form. A form
43template 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
51An 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
67Low-level create routines.
68.LP
69The three low-level creation routines are called as follows:
70.LP
71.ft C
72form = create_form(form_template)
73.IP
74Create an fl form from a form template. Returns the form created.
75.LP
76.ft C
77obj = create_object(form, obj_template)
78.IP
79Create an object in an fl form. Return the new object.
80An error is raised if the object has a callback routine.
81.SH
82High-level create routines.
83.LP
84The 'standard' way to handle forms in python is to define a class
85that contains the form and all the objects (insofar as they are named),
86and that defines all the callback functions, and use an instance of
87this class to handle the form interaction.
88Flp contains three routines that simplify handling this paradigm:
89.LP
90.ft C
91create_full_form(instance, ftuple)
92.IP
93This routine takes an instance of your form-handling class and an
94ftuple (as returned by the parsing routines) as parameters. It inserts
95the form into the instance, defines all object names and arranges that
96the callback methods are called. All the names inserted into the
97instance are the same as the names used for the objects, etc. in the
98fd file.
99.LP
100.ft C
101merge_full_form(instance, form, ftuple)
102.IP
103This function does the same as create_full_form, only it does not create
104the form itself nor the 'background box' that fdesign automatically
105adds to each form. This is useful if your class inherits a superclass
106that already defines a skeleton form (with 'OK' and 'Cancel' buttons,
107for instance), and you want to merge the new form into that existing
108form. The 'form' parameter is the form to which the new objects are
109added.
110.LP
111If you use the paradigm sketched here but need slightly more control
112over object creation there is a routine that creates a single object
113and inserts its name (and arranges for the callback routine to be
114called):
115.LP
116.ft C
117create_object_instance(instance, form, obj_template)