Welcome to campos¶
campos helps you to quickly create and generate fully functional forms. Read a bit more about it or jump to User’s Guide
Main features¶
- Good integration
You can use campos‘ fields and forms like normal Qt objects anytime you want in your existing gui code like.
- Dynamic generation
Just pass a source object to
campos.get_forms()method and campos will give you two nice ready to use forms.
- Simplified API
Use campos‘ fields as building blocks to create your forms.
- Works with major Qt bindings
Thanks to QtPy you just need to set
os.environ['QT_API']before you use campos if you have a favorite Qt binding, one of the existing ones will be used otherwise.
User’s Guide¶
This part of the documentation will show you how to get started in using campos.
Installation¶
Install campos with pip
pip install campos
The development version can be downloaded from its page at GitHub.
git clone https://github.com/jbermudezcabrera/campos.git
- campos requires at least one of the supported Qt bindings.
- campos supports all major Qt bindings thanks to QtPy, so you need it.
- campos requires Python version >= 3.0
Quick start¶
With campos you can easily create, generate and modify forms with builtin field validation using code compatible with all major Qt bindings. Let’s take a look.
Generating forms¶
The quickest way to include a form created with campos in your project is generating it from your object’s model(see generating.py for a more complete example):
# [optional] do this only if you want to use an specific Qt binding
import os
os.environ['QT_API'] = 'pyqt4'
import sys
from collections import namedtuple
from PyQt4.QtGui import QApplication
import campos
# define a Person type
Person = namedtuple('Person', 'id name last_name phone address country')
penny = Person(id='F4356721', name='Kaley', last_name='Cuoco', phone='',
address='', country='EE.UU')
app = QApplication(sys.argv)
# generate creation and editions forms from your object attributes
new, edition = campos.get_forms(penny)
new.show()
edition.show()
sys.exit(app.exec_())
After these lines of code you will obtain two ready to use forms containing fields for every valid attribute encountered in your object. It’s also possible to use SQLAlchemy objects and tables:
If you are interested in only one particular type of form you can use from_source methods in form classes:
# to obtain a form customized for creation
form = campos.CreationForm.from_source(penny)
# to obtain a form customized for edition
form = campos.EditionForm.from_source(penny)
# to obtain a neutral form
form = campos.Form.from_source(penny)
You can modify these forms, add or remove options and fields, load an object for edition and connect custom callbacks and validation mechanisms:
from PyQt4.QtGui import QPushButton
# add a new button with a custom callback
new.add_button(QPushButton('Click me'), on_click=lambda: print('clicked'))
# add a new field with validation
f = campos.StringField(name='ten', text='Up to 10 chars', max_length=10)
new.add_field(f)
# load a custom object to edit it
edition.edit(penny, disabled=['fullname'])
The images below show the modified creation form and the edition form with a person’s data loaded:
Please note that validation is done automatically and the form can’t be committed until all fields are valid. You can customize the way validation is done and field’s label and error message positions.
Building forms¶
You can also create your very own form using campos form classes and filling them with fields or any other Qt object you want(see building.py for a more complete example):
# [optional] do this only if you want to use an specific Qt binding
import os
os.environ['QT_API'] = 'pyqt4'
import sys
from collections import namedtuple
from PyQt4.QtGui import QApplication
import campos
# define a Person type
Person = namedtuple('Person', 'id name last_name phone address country')
app = QApplication(sys.argv)
form = campos.CreationForm(validation='instant', options=('ok', 'cancel'))
form.setWindowTitle('Manually done')
personal_id = campos.StringField(name='id', text='ID', max_length=11,
required=True)
name = campos.StringField(name='name', text='Name')
last = campos.StringField(name='last_name', text='Last name')
country = campos.SelectField(name='country', text='Country',
choices=['Cuba', 'EE.UU'])
form.add_field(personal_id)
form.add_field(name)
form.add_field(last)
form.add_field(country)
# group some fields
form.group('Very personal info', ['id', 'name', 'last_name'])
sys.exit(form.exec_())
The code above produces the following form:
API Reference¶
If you are looking for information on a specific function, class or method, this part of the documentation is for you.