Initial revision

1 files changed, 117 insertions, 0 deletions

diff --git a/Lib/plat-irix5/flp.doc b/Lib/plat-irix5/flp.doc
new file mode 100755
index 0000000..1a2f374
--- /dev/null
+++ b/Lib/plat-irix5/flp.doc
@@ -0,0 +1,117 @@
+.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)