Delegates

Release:0.1
Date:July 02, 2010

Delegates are a cornerstone of the Qt model/delegate/view framework. A delegate is used to display and edit data from a model.

In the Camelot framework, every field of an Entity has an associated delegate that specifies how the field will be displayed and edited. When a new form or table is constructed, the delegates of all fields on the form or table will construct editors for their fields and fill them with data from the model. When the data has been edited in the form, the delegates will take care of updating the model with the new data.

All Camelot delegates are subclasses of QAbstractItemDelegate.

The PyQT website provides detailed information the differenct classes involved in the model/delegate/view framework.

Specifying delegates

The use of a specific delegate can be forced by using the delegate field attribute. Suppose rating is a field of type integer, then it can be forced to be visualized as stars:

from camelot.view.controls import delegates

class Movie(Entity):
  title = Field(Unicode(50))
  rating = Field(Integer)

  class Admin(EntityAdmin):
    list_display = ['title', 'rating']
    field_attributes = {'rating':{'delegate':delegates.StarDelegate}}

The above code will result in:

../_images/StarEditor_editable.png

If no delegate field attribute is given, a default one will be taken depending on the sqlalchemy field type.

All available delegates can be found in camelot.view.controls.delegates

Available delegates

Camelot includes a number of Qt delegates, most of them are used as default delegates for the various sqlalchemy and camelot field types.

Some delegates take specific arguments into account for their construction. All field_attributes specified for a certain field will be propagated towards the constructor of the delegate. Some of them will be used by the delegate itself, others will be used by the editor, created by the delegate.

BoolDelegate

Custom delegate for boolean values

../_images/BoolDelegate_unselected_disabled.png ../_images/BoolDelegate_unselected_editable.png ../_images/BoolDelegate_selected_disabled.png ../_images/BoolDelegate_selected_editable.png

By default, creates a BoolEditor as its editor.

../_images/BoolEditor_editable.png

Field attributes supported by this editor :

CodeDelegate

../_images/CodeDelegate_unselected_disabled.png ../_images/CodeDelegate_unselected_editable.png ../_images/CodeDelegate_selected_disabled.png ../_images/CodeDelegate_selected_editable.png

Field attributes supported by the delegate :

  • parts
  • separator

By default, creates a CodeEditor as its editor.

../_images/CodeEditor_editable.png

Field attributes supported by this editor :

ColorDelegate

../_images/ColorDelegate_unselected_disabled.png ../_images/ColorDelegate_unselected_editable.png ../_images/ColorDelegate_selected_disabled.png ../_images/ColorDelegate_selected_editable.png

By default, creates a ColorEditor as its editor.

../_images/ColorEditor_editable.png

Field attributes supported by this editor :

ColoredFloatDelegate

Custom delegate for float values, representing them in green when they are
positive and in red when they are negative.
../_images/ColoredFloatDelegate_unselected_disabled.png ../_images/ColoredFloatDelegate_unselected_editable.png ../_images/ColoredFloatDelegate_selected_disabled.png ../_images/ColoredFloatDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a ColoredFloatEditor as its editor.

../_images/ColoredFloatEditor_editable.png

Field attributes supported by this editor :

ComboBoxDelegate

../_images/ComboBoxDelegate_unselected_disabled.png ../_images/ComboBoxDelegate_unselected_editable.png ../_images/ComboBoxDelegate_selected_disabled.png ../_images/ComboBoxDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a ChoicesEditor as its editor.

../_images/ChoicesEditor_editable.png

Field attributes supported by this editor :

CurrencyDelegate

Custom delegate for float values

../_images/CurrencyDelegate_unselected_disabled.png ../_images/CurrencyDelegate_unselected_editable.png ../_images/CurrencyDelegate_selected_disabled.png ../_images/CurrencyDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a FloatEditor as its editor.

../_images/FloatEditor_editable.png

Field attributes supported by this editor :

DateDelegate

Custom delegate for date values

../_images/DateDelegate_unselected_disabled.png ../_images/DateDelegate_unselected_editable.png ../_images/DateDelegate_selected_disabled.png ../_images/DateDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a DateEditor as its editor.

../_images/DateEditor_editable.png

Field attributes supported by this editor :

DateTimeDelegate

../_images/DateTimeDelegate_unselected_disabled.png ../_images/DateTimeDelegate_unselected_editable.png ../_images/DateTimeDelegate_selected_disabled.png ../_images/DateTimeDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a DateTimeEditor as its editor.

../_images/DateTimeEditor_editable.png

Field attributes supported by this editor :

EnumerationDelegate

Contrary to the comboboxdelegate, the enumeration delegate does not support dynamic
choices
../_images/EnumerationDelegate_unselected_disabled.png ../_images/EnumerationDelegate_unselected_editable.png ../_images/EnumerationDelegate_selected_disabled.png ../_images/EnumerationDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a ChoicesEditor as its editor.

../_images/ChoicesEditor_editable.png

Field attributes supported by this editor :

FileDelegate

Delegate for camelot.types.file fields. Expects values of type camelot.core.files.storage.StoredFile.

../_images/FileDelegate_unselected_disabled.png ../_images/FileDelegate_unselected_editable.png ../_images/FileDelegate_selected_disabled.png ../_images/FileDelegate_selected_editable.png

By default, creates a FileEditor as its editor.

../_images/FileEditor_editable.png

Field attributes supported by this editor :

FloatDelegate

Custom delegate for float values

../_images/FloatDelegate_unselected_disabled.png ../_images/FloatDelegate_unselected_editable.png ../_images/FloatDelegate_selected_disabled.png ../_images/FloatDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a FloatEditor as its editor.

../_images/FloatEditor_editable.png

Field attributes supported by this editor :

ImageDelegate

../_images/image.png

IntegerDelegate

Custom delegate for integer values

../_images/IntegerDelegate_unselected_disabled.png ../_images/IntegerDelegate_unselected_editable.png ../_images/IntegerDelegate_selected_disabled.png ../_images/IntegerDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a IntegerEditor as its editor.

../_images/IntegerEditor_editable.png

Field attributes supported by this editor :

LabelDelegate

_static/delegates/LabelDelegate_unselected_disabled.png _static/delegates/LabelDelegate_unselected_editable.png _static/delegates/LabelDelegate_selected_disabled.png _static/delegates/LabelDelegate_selected_editable.png

By default, creates a LabelEditor as its editor.

_static/editors/LabelEditor_editable.png

Field attributes supported by this editor :

  • text

Many2OneDelegate

Custom delegate for many 2 one relations

../_images/manytoone.png

ManyToOneChoicesDelegate

Display a ManyToOne field as a ComboBox, filling the list of choices with

the objects of the target class.

../_images/enumeration.png

NoteDelegate

_static/delegates/NoteDelegate_unselected_disabled.png _static/delegates/NoteDelegate_unselected_editable.png _static/delegates/NoteDelegate_selected_disabled.png _static/delegates/NoteDelegate_selected_editable.png

By default, creates a NoteEditor as its editor.

../_images/NoteEditor_editable.png

Field attributes supported by this editor :

PlainTextDelegate

Custom delegate for simple string values

../_images/PlainTextDelegate_unselected_disabled.png ../_images/PlainTextDelegate_unselected_editable.png ../_images/PlainTextDelegate_selected_disabled.png ../_images/PlainTextDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a TextLineEditor as its editor.

../_images/TextLineEditor_editable.png

Field attributes supported by this editor :

RichTextDelegate

../_images/RichTextDelegate_unselected_disabled.png ../_images/RichTextDelegate_unselected_editable.png ../_images/RichTextDelegate_selected_disabled.png ../_images/RichTextDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a RichTextEditor as its editor.

../_images/RichTextEditor_editable.png

Field attributes supported by this editor :

SmileyDelegate

Delegate for Smiley’s

../_images/SmileyDelegate_unselected_disabled.png ../_images/SmileyDelegate_unselected_editable.png ../_images/SmileyDelegate_selected_disabled.png ../_images/SmileyDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a SmileyEditor as its editor.

../_images/SmileyEditor_editable.png

Field attributes supported by this editor :

StarDelegate

Delegate for integer values from (1 to 5)(Rating Delegate)

../_images/StarDelegate_unselected_disabled.png ../_images/StarDelegate_unselected_editable.png ../_images/StarDelegate_selected_disabled.png ../_images/StarDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a StarEditor as its editor.

../_images/StarEditor_editable.png

Field attributes supported by this editor :

TextBoolDelegate

TextEditDelegate

Custom delegate for simple string values

../_images/TextEditDelegate_unselected_disabled.png ../_images/TextEditDelegate_unselected_editable.png ../_images/TextEditDelegate_selected_disabled.png ../_images/TextEditDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a TextEditEditor as its editor.

_static/editors/TextEditEditor_editable.png

Field attributes supported by this editor :

TimeDelegate

../_images/TimeDelegate_unselected_disabled.png ../_images/TimeDelegate_unselected_editable.png ../_images/TimeDelegate_selected_disabled.png ../_images/TimeDelegate_selected_editable.png

Field attributes supported by the delegate :

By default, creates a TimeEditor as its editor.

../_images/TimeEditor_editable.png

Field attributes supported by this editor :

VirtualAddressDelegate

../_images/VirtualAddressDelegate_unselected_disabled.png ../_images/VirtualAddressDelegate_unselected_editable.png ../_images/VirtualAddressDelegate_selected_disabled.png ../_images/VirtualAddressDelegate_selected_editable.png

By default, creates a VirtualAddressEditor as its editor.

../_images/VirtualAddressEditor_editable.png

Field attributes supported by this editor :

Field attributes

calculator

True or False

Indicates whether a calculator should be available when editing this field.

editable

True or False

Indicates whether the user can edit the field.

minimum, maximum

The minimum and maximum allowed values for Integer and Float delegates or their related delegates like the Star delegate.

choices

A function taking as a single argument the object to which the field belongs. The function returns a list of tuples containing for each possible choice the value to be stored on the model and the value displayed to the user.

The use of choices forces the use of the ComboBox delegate:

field_attributes = {'state':{'choices':lambda o:[(1, 'Active'),
                                                 (2, 'Passive')]}}

minimal_column_width

An integer specifying the minimal column width when this field is displayed in a table view. The width is expressed as the number of characters that should fit in the column:

field_attributes = {'name':{'minimal_column_width':50}}

will make the column wide enough to display at least 50 characters.

prefix

String to display before a number

suffix

String to display after a number

tooltip

A function taking as a single argument the object to which the field belongs. The function should return a string that will be used as a tooltip. The string may contain html markup.

from camelot.admin.object_admin import ObjectAdmin
from camelot.view.controls import delegates

def dynamic_tooltip_x(coordinate):
  return u'The <b>x</b> value of the coordinate, now set to %s'%(coordinate.x)

def dynamic_tooltip_y(coordinate):
  return u'The <b>y</b> value of the coordinate, now set to %s'%(coordinate.y)
  
class Coordinate(object):
  
  def __init__(self):
    self.id = 1
    self.x = 0.0
    self.y = 0.0
      
  class Admin(ObjectAdmin):
    form_display = ['x', 'y',]
    field_attributes = dict(x=dict(delegate=delegates.FloatDelegate, 
                                   tooltip=dynamic_tooltip_x),
                            y=dict(delegate=delegates.FloatDelegate,
                                   tooltip=dynamic_tooltip_y),
                            )
    form_size = (100,100)
../_images/fields_with_tooltips.png

background_color

A function taking as a single argument the object to which the field belongs. The function should return None if the default background should be used, or a QColor to be used as the background.

"""This Admin class turns the background of a Person's first
name pink if its first name doesn't start with a capital"""

from PyQt4.QtGui import QColor

from camelot.model.authentication import Person

def first_name_background_color(person):
    import string
    if person.first_name:
        if person.first_name[0] not in string.uppercase:
            return QColor('pink')
    
class Admin(Person.Admin):
    field_attributes = {'first_name':{'background_color':first_name_background_color}}
../_images/background_color.png