3.1.5 Form Type

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.

class Form( fields[, flags=0])

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: 'text', 'number', 'date', 'time', 'combo' or 'float'

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

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:

flags

This attribute holds the values of the various configuration flags. Currently supported flags are:

FFormEditModeOnly: When this flag is set, the form remains in edit mode while execute runs.

FFormViewModeOnly: When this flag is set, the form cannot be edited at all.

FFormAutoLabelEdit: This flag enables support for allowing the end-users to edit the labels of the form fields.

FFormAutoFormEdit: 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.

FFormDoubleSpaced: 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 different lines.

menu: 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.

save_hook: 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 True, the 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:

execute( ): Executes the dialog by making it visible on the UI.

insert( index, field_descriptor): Inserts the field descriptor into the Form before the given index.

pop( ): Removes the last field descriptor from the Form and returns it.

length( ): 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.