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
Form
constructor 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
CreationForm
andEditionForm
subclasses which provide some useful default behaviour for object creation and modification.Parameters: - validation (
str
or aValidation
member) – 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
,ButtonType
orQPushButton
) –options to show in the form, these can be
QPushButton
instances orButtonType
enum members (note that you can use strings too).If you use
ButtonType
members(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_save
andon_cancel
which will be connected to save and cancel buttons. Note that the keyword(except theon_
part) matches the option name(ButtonType
member’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
,ButtonType
orQPushButton
) – new option to add, can be aQPushButton
instance orButtonType
enum 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 ( str
orButtonType
) – button type to find, must be a valid member ofButtonType
enum(note that you can use strings)Returns: the button which type matches the argument Return type: QPushButton
Raises 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: Field
Raises 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
FieldSource
instance.Parameters: - obj (any) – object to extract fields from.
- source_kw (
dict
) – keyword arguments to pass toFieldSource
constructor - form_kw (
dict
) – keyword arguments to pass toForm
constructor
-
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.
-