Form implements a dynamically configurable, editable multi-field
dialog. Form caters for advanced dialog use cases with requirements
such as free selectability of the combination of fields, possibility of
validating the user input, and automatically producing the contents of some
dialog fields before allowing the closing of the dialog.
3.1.5 Form Type
Creates a Form instance.
fields is a list of field descriptors:
(label, type[, value]) where
label is a Unicode string
type is one of the following strings:
value, depending on type: Unicode string, numeric, float (seconds
since Unix epoch rounded down to the nearest local midnight), float (seconds
since local midnight),
([choice_label ...], index) of float. For
'float' type the initial value setting might not be shown in the
Form can also be configured and populated after construction. The
configuration flags are visible as an attribute. Form implements
the list protocol that can be used for setting the form fields, as well as
obtaining their values after the dialog has been executed.
Instances of Form type have the following attributes:
This attribute holds the values of the various configuration flags.
Currently supported flags are:
When this flag is set, the form remains in edit mode while execute
When this flag is set, the form cannot be edited at all.
This flag enables support for allowing the end-users to edit the labels of
the form fields.
This flag enables automatic support for allowing the end-users to add and
delete the form fields. Note that this is an experimental feature and is not
guaranteed to work with all SDK versions.
When this flag is set, double-spaced layout is applied when the form is
executed: one field takes two lines, as the label and the value field are on
A list of
(title, callback) pairs, where
each pair describes an item in the form's menu bar that is active while the
dialog is being executed. title (Unicode) is the name of
the item and callback the associated callable object.
This attribute can be set to a callable object that receives one argument
and returns a Boolean value. It gets called every time the users want to
save the contents of an executing Form dialog. A candidate list for
new form content - a list representing the currently visible state of the
UI - is given as an argument. The list can be modified by
save_hook. If save_hook returns
candidate list is set as the new contents of the form. Otherwise, the form
UI is reset to reflect the field list contained in Form object.
Instances of Form type have the following methods:
Executes the dialog by making it visible on the UI.
Inserts the field descriptor into the Form before the given index.
Removes the last field descriptor from the Form and returns it.
- the number of field descriptors in the form.
The subscript notation
f[i] can be used to access or modify the
i-th element of the form
f. Same limitations as discussed above
in the context of the flag FFormAutoFormEdit apply to
modifying a form while it is executing. The ability to change the
schema of a form while it is executing is an experimental feature.
See About this document... for information on suggesting changes.