forms module¶
-
class
campos.forms.Form(options=('ok', 'cancel'), fields=(), validation='current', **kwargs)[source]¶ Forms are used to arrange fields in order to facilitate data input and validation.
You can create a form by calling the
Formconstructor and providing fields and options:fields = [StringField(), SelectField(), FileField(), TextField()] buttons = ('reset', 'ok', 'cancel') form = Form(fields=fields, options=buttons)
Or also by calling
from_source()which generates form’s fields introspecting a source object:class Person: def __init__(self, name, last_name, age): self.name = name self.last_name = last_name self.age = age p = Person('Sheldon', 'Cooper', 25) form = Form.from_source(p)
You can group related fields using
group()method:form.group('Identification', ['name', 'last_name'])
Also you can find a field contained in the form using its name:
field = form.field('last_name')
and obtain it’s value using dot notation:
value = form.last_name
Forms provide validation through
validate()method which is called automatically when validation is set to ‘instant’.More specialized forms can be created using
CreationFormandEditionFormsubclasses which provide some useful default behaviour for object creation and modification.Parameters: - validation (
stror aValidationmember) – validation mechanism used by the form, if it’s ‘instant’ all fields are checked anytime one of them changes and corresponding buttons are enabled/disabled accordingly. If it’s ‘manual’ you should invokevalidate()method by yourself. - fields (iterable of
Field) – fields to add to this form - options (iterable of
str,ButtonTypeorQPushButton) –options to show in the form, these can be
QPushButtoninstances orButtonTypeenum members (note that you can use strings too).If you use
ButtonTypemembers(or string) then you can connect the button with a callback passed as a keyword argument.For instance, if your options are
['save', 'cancel']you can pass two keyword arguments namedon_saveandon_cancelwhich will be connected to save and cancel buttons. Note that the keyword(except theon_part) matches the option name(ButtonTypemember’s name).Buttons with a rejection role(accept, cancel, etc) will be connected to form’s
close()method if no callback is settled for them.
See also
Adds a new button or option to form’s button box and connects it with a callback. The new button is always returned.
Buttons with a rejection role(accept, cancel, etc) will be connected to form’s
close()method if no callback is settled for them.Parameters: - btn (
str,ButtonTypeorQPushButton) – new option to add, can be aQPushButtoninstance orButtonTypeenum members(note that you can use strings too) - on_click (callable) – callback to invoke whenever the button is clicked.
Returns: the new button
Return type: QPushButton- btn (
Finds a button given its type.
Parameters: which ( strorButtonType) – button type to find, must be a valid member ofButtonTypeenum(note that you can use strings)Returns: the button which type matches the argument Return type: QPushButtonRaises ValueError: if no button of the given type was found
-
field(name)[source]¶ Find a field by its name.
Parameters: name ( str) – name of the fieldReturns: a field Return type: FieldRaises ValueError: if there is no field in the form with the given name
-
static
from_source(obj, source_kw={}, form_kw={})[source]¶ Creates a form introspecting fields from an object.
Fields are generated using a suited
FieldSourceinstance.Parameters: - obj (any) – object to extract fields from.
- source_kw (
dict) – keyword arguments to pass toFieldSourceconstructor - form_kw (
dict) – keyword arguments to pass toFormconstructor
-
group(title, fieldnames, layout='vertical')[source]¶ Groups fields in a common area under a title using chosen layout.
Parameters: - title (
str) – title of the group - fieldnames (iterable of
str) – names of the fields to group - layout (one of (‘vertical’, ‘horizontal’, ‘grid’)) – layout manager used to arrange fields inside the group. Defaults to ‘vertical’.
- title (
-
remove_field(name)[source]¶ Removes and returns a field from this form using its name.
Parameters: name ( Field) – name of the field to removeReturns: the removed field Return type: Field
-
validate(title='Invalid fields', msg=None)[source]¶ Runs validation on every field of this form.
This method is automatically called if form validation is set to ‘instant’, all buttons with an acceptance role are disabled when invalid fields are found.
If form validation is set to ‘manual’ then a message is shown when invalid fields are found.
Parameters: - title (
str) – title of the message shown when invalid fields are found. Used only when form validation is set to ‘manual’ - msg (
str) – text to show when invalid fields are found. Used only when form validation is set to ‘manual’
- title (
-
validation¶ Validation mechanism used by the form.
If it’s ‘instant’ all fields are checked whenever one of them changes. If it’s ‘manual’ you should invokevalidate()method by yourself.Type: Validation
- validation (
-
class
campos.forms.CreationForm(**kwargs)[source]¶ Form subclass with useful defaults to create new objects.
This form’s options defaults to
('reset', 'save', 'cancel'). Also, areset()method is included and connected by default to the reset button to restore all fields in the form to their default values.See also
-
class
campos.forms.EditionForm(**kwargs)[source]¶ Form subclass with useful defaults to edit existing objects.
This form’s options defaults to
('reset', 'save', 'cancel'). Also, areset()method is included and connected by default to a reset button to restore all fields in the form to their saved values.You can edit an existing object using
edit()method which obtains a value for every field from the object, field names must be equal to attributes names in the object in order to obtain their current value:class Person: def __init__(self, name, last_name, age): self.name = name self.last_name = last_name self.age = age billy = Person('Billy', 'Smith', 20) john = Person('John', 'Bit', 26) # create form's fields using Person attributes form = EditionForm.from_source(billy) # prepares the form for edition and fills fields with current values form.edit(john)
See also
-
edit(obj, disabled=())[source]¶ Puts the form in edition mode, filling fields with object values.
To prevent some of the fields from been modified when editing use disable keyword and provide the names of the fields. Field names must match object attributes in order to load values correctly.
Parameters: - obj (any) – object used to fill form fields, only those attributes which match field names will be used.
- disabled (iterable of
str) – names of the fields to be disabled in edition mode.
-