### Navigation

- index
- modules |
- next |
- previous |
- Camelot v0.1 documentation »
- Camelot Documentation contents »
- Camelot Documentation »

# 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:

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

By default, creates a BoolEditor as its editor.

Field attributes supported by this editor :

> - minimum
> - maximum
> - editable

### CodeDelegate

Field attributes supported by the delegate :

> - parts
> - separator

By default, creates a CodeEditor as its editor.

Field attributes supported by this editor :

> - parts
> - editable

### ColorDelegate

By default, creates a ColorEditor as its editor.

Field attributes supported by this editor :

> - editable

### ColoredFloatDelegate

Custom delegate for float values, representing them in green when they are
  positive and in red when they are negative.

Field attributes supported by the delegate :

> - minimum
> - maximum
> - precision
> - editable
> - reverse
> - neutral
> - unicode_format

By default, creates a ColoredFloatEditor as its editor.

Field attributes supported by this editor :

> - precision
> - minimum
> - maximum
> - prefix
> - suffix
> - editable
> - reverse
> - neutral

### ComboBoxDelegate

Field attributes supported by the delegate :

> - choices
> - editable

By default, creates a ChoicesEditor as its editor.

Field attributes supported by this editor :

> - editable

### CurrencyDelegate

Custom delegate for float values

Field attributes supported by the delegate :

> - minimum
> - maximum
> - precision
> - editable
> - prefix
> - suffix

By default, creates a FloatEditor as its editor.

Field attributes supported by this editor :

> - precision
> - minimum
> - maximum
> - editable
> - prefix
> - suffix
> - calculator

### DateDelegate

Custom delegate for date values

Field attributes supported by the delegate :

> - editable

By default, creates a DateEditor as its editor.

Field attributes supported by this editor :

> - editable
> - nullable
> - format

### DateTimeDelegate

Field attributes supported by the delegate :

> - editable

By default, creates a DateTimeEditor as its editor.

Field attributes supported by this editor :

> - editable
> - format
> - nullable

### EnumerationDelegate

Contrary to the comboboxdelegate, the enumeration delegate does not support dynamic
  choices

Field attributes supported by the delegate :

> - choices
> - editable

By default, creates a ChoicesEditor as its editor.

Field attributes supported by this editor :

> - editable

### FileDelegate

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

By default, creates a FileEditor as its editor.

Field attributes supported by this editor :

> - storage
> - editable

### FloatDelegate

Custom delegate for float values

Field attributes supported by the delegate :

> - minimum
> - maximum
> - precision
> - editable
> - unicode_format
> - prefix
> - suffix

By default, creates a FloatEditor as its editor.

Field attributes supported by this editor :

> - precision
> - minimum
> - maximum
> - editable
> - prefix
> - suffix
> - calculator

### ImageDelegate

### IntegerDelegate

Custom delegate for integer values

Field attributes supported by the delegate :

> - minimum
> - maximum
> - editable
> - unicode_format

By default, creates a IntegerEditor as its editor.

Field attributes supported by this editor :

> - minimum
> - maximum
> - editable
> - prefix
> - suffix
> - calculator

### LabelDelegate

By default, creates a LabelEditor as its editor.

Field attributes supported by this editor :

> - text

### Many2OneDelegate

Custom delegate for many 2 one relations

### ManyToOneChoicesDelegate

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

  the objects of the target class.

### NoteDelegate

By default, creates a NoteEditor as its editor.

Field attributes supported by this editor :

### PlainTextDelegate

Custom delegate for simple string values

Field attributes supported by the delegate :

> - length
> - editable
> - translate_content

By default, creates a TextLineEditor as its editor.

Field attributes supported by this editor :

> - length
> - editable

### RichTextDelegate

Field attributes supported by the delegate :

> - editable

By default, creates a RichTextEditor as its editor.

Field attributes supported by this editor :

> - editable

### SmileyDelegate

Delegate for Smiley’s

Field attributes supported by the delegate :

> - editable

By default, creates a SmileyEditor as its editor.

Field attributes supported by this editor :

> - img
> - editable

### StarDelegate

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

Field attributes supported by the delegate :

> - editable
> - maximum

By default, creates a StarEditor as its editor.

Field attributes supported by this editor :

> - maximum
> - editable

### TextBoolDelegate

### TextEditDelegate

Custom delegate for simple string values

Field attributes supported by the delegate :

> - editable

By default, creates a TextEditEditor as its editor.

Field attributes supported by this editor :

> - length
> - editable

### TimeDelegate

Field attributes supported by the delegate :

> - editable

By default, creates a TimeEditor as its editor.

Field attributes supported by this editor :

> - editable
> - format

### VirtualAddressDelegate

By default, creates a VirtualAddressEditor as its editor.

Field attributes supported by this editor :

> - editable

## 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)

### 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}}

### Navigation

- index
- modules |
- next |
- previous |
- Camelot v0.1 documentation »
- Camelot Documentation contents »
- Camelot Documentation »