2.9.5 Using Signal Handlers in Proxies

Proxies implement their behavior by using GTK+ signals extensively, but this mechanism is implemented inside the Proxy and most of it happens automatically, without user-visible effects beyond updating of the model and the interface. However, many times an application needs custom behavior beyond the simple model updating; for this, user-defined handlers can be used normally.

Proxies inherit from the Delegate classes, and they can define signal handlers in the same way as normal Delegates (and Controllers), by using the special syntax as defined in section 2.6. However, there is a special detail that should be understood when using custom callbacks:

The Proxy's internal callbacks are executed first.

This means that, when your on_*() or after_*() handler runs, the Proxy has already updated the model. In practice, this is a good thing, since you usually want to work with the current contents of the widget, not the contents it used to have. Of course, signal handlers in the Proxy that are not associated to widgets attached to model attributes (in other words, widgets not prefixed by a colon (:) in the widgets list) do not present this issue (as there is no Proxy signal handler for them anyway).

One common task of using signal handlers is to trigger updates in some other part of interface. For instance, you might have a radiobutton that makes a certain part of the interface sensitive when toggled. Or an entry that needs to update a label that represents a calculated field in the interface. You can define handlers normally, and you can take advantage of the special Proxy method update(attribute_name), which notifies the Proxy that it should refresh the interface representation of that attribute.

A step-by-step analysis of this example:

Upon running the example you will see that it works as expected; the update() messages in fact make the labels render the correct values, and the accessors return empty strings when they should.

There is an additional hook you can use in your Proxy classes to make updating easier. If you define a method called proxy_updated(), this method will be called each time a proxy-managed widget is manipulated by the user. This allows you to easily perform updating of calculated text indicators, for instance.

There is a set of more complex examples that demonstrate the use of custom handlers in the package, under the directory examples/Diary, which are recommended as further reference.