Class Adapter

This is the base class for all adapters. All adapters derive from class Observer. Instantiation of an Adapter can be optionally complex and customizable by using same optional parameters. Available parameters are presented here, but examples will show them applied in a practical manner.

Important operations are:

Constructor

Class constructor gets several parameters, but only two are strictly required.

def __init__(self, model, prop_name, 
             prop_read=None, prop_write=None, 
             value_error=None)

model

is the Model instance containing the property to be observed.

prop_name

is the model's property name (as a string). It is possible to use a dotted notation to identify a property contained into a hierarchy of models. For example 'a.b.c' identifies property 'c' into model 'b' inside model 'a', where model 'a' is an attribute of given top level model. Last name can be an observable or non-observable attribute, and previous names (if specified) must all refer to instances of class Model. First name from the left must be the name of a model instance inside the given model.

prop_read

optional function that apply custom modifications to the value of the property before reading it. The function takes a value and must return a transformed value. Use to customize the way the property is read, and to apply useful transformations to the read value.

prop_write

Like prop_read optional function that apply custom modifications to the value of the property before writing it. The function takes a value and must return a transformed value whose type must be compatible with the type of the property. Use to customize the way the property is written, and to apply useful transformations to the value.

value_error

optional parameter that can be a function (or a method) to be called when a ValueError exception occurs while trying to set a wrong value for the property inside the model. The function will receive: the adapter, the property name and the value coming from the widget that offended the model. Useful to catch and handle error conditions.

Widget connection

Constructor connects properties, while widgets are connected through method connect_widget:

def connect_widget(self, widget,
                   getter=None, setter=None, 
                   signal=None, arg=None, update=True)

widget

is the widget that is needed to connect

getter

optional function used to ``read'' the widget. The function receives a widget instance.

setter

optional function used to ``write'' the widget. The function receives a widget instance and the value to be written.

signal

Optional name of the signal that will be used to monitor the widget changes.

arg

Optional argument that is passed to the signal handler. It will be used when connecting the signal.

update

If False, the widget will be not initially updated with the initial value of the property. Used in very particular conditions.

update_model()

Forces the property to be updated from the value hold by the widget. This method should be called directly by the user in very unusual conditions.

update_widget()

Forces the widget to be updated from the property value. This method should be called directly by the user when the property is not observable, or in very unusual conditions.

At this step thorough people would be asking them self how instantiation of adapters can work in its simplest option, i.e. by specifying the minimal set of parameters, and exploiting all default values for the others.

The framework searches information about widgets and possible default values for any unspecified parameter into module adapters.default.

Suppose for example that the specified widget is a gtk.Entry. Good candidates for unspecified getter and setter would be gtk.Entry.get_text and gtk.Entry.set_text respectively. signal will be "changed" to capture events that change the value of the widget.

Later a list of all currently supported widgets will be presented.