Thursday, February 12, 2009

Bind a viewer in one statement with ViewerSupport

We've added the ViewerSupport class to simplify setting up viewers (including tree viewers), usually in just one statement.


ObservableListContentProvider contentProvider =
new ObservableListContentProvider();
viewer.setContentProvider( contentProvider );
new ObservableMapLabelProvider(
new String[] {
"title", "releaseDate", "director", "writer" } ) ) );
viewer.setInput(BeansObservables.observeList(model, "movies"));


BeansObservables.observeList(model, "movies"),
BeanProperties.values(new String[] {
"title", "releaseDate", "director", "writer" } ) );

Master-detail editing with multiple selection

A few weeks ago we released DuplexingObservableValue. This class, among other things, helps make possible master-detail editing on a multiple selection:

Because the selected movies have the same director and same writer, those values are displayed in the master-detail fields at the bottom. However, since they have different titles and release dates, those fields use a stand-in "multi value" instead.

Editing the release date field simultaneously changes the release date of all movies in the selection.

Here's the code that was used to hook up the detail fields to the multi-selection of the viewer:

IObservableList selections = ViewerProperties.multipleSelection()

"", "<Multiple titles>"));

"", "<Multiple dates>"));

"", "<Multiple directors>"));

"", "<Multiple writers>"));
See the full code listing for this snippet here.

Disclaimer: The method DuplexingObservableValue.withDefaults() was added after the 3.5M5 milestone, so in order to use it you need to check out the databinding projects from CVS HEAD, or be using a more recent integration build.

Tuesday, February 03, 2009

Introducing the Properties API

Observables are hard to implement. There are a handful of rules, guidelines and corner cases that observables implementors must pay attention to for data binding to work properly. Observables must call ObservableTracker.getterCalled() for things like ComputedValue or MultiValidator to work; observables must ensure that all invocations are made from within the realm; a ChangeEvent must be fired before ValueChangeEvent; the list goes on. To an extent we've been able to isolate these concerns within the framework, but over time I couldn't help noticing that many of our observables followed a template--a lengthy, complicated one.

In June 2008 I stumbled across bug 194734 and I thought Tom was on to something. I started working on a prototype, which we've been evolving and refining for the past six months. I'm very pleased with the result, and if you've tried implementing your own observables before, I think you will be too.

There are four types of properties: IValueProperty, IListProperty, ISetProperty and IMapProperty. Properties serve two main purposes:
  • They act as convenient, portable observable factories for a particular property.
  • They act as strategy objects for the observables they create. That is, the observables use the properties to access, modify, and listen to the property source object.
Suppose you want to observe the "name" property of a bean object:

Person person = new Person("Joe");
IValueProperty nameProperty = BeanProperties.value("name");
IObservableValue personName =

One of the strengths of properties is how easy it is to combine them to observe nested attributes:

IListProperty childrenProperty = BeanProperties.list("children");
IValueProperty nameProperty = BeanProperties.value("name");
IObservableList namesOfChildren =

or, a shorter version:

IObservableList namesOfChildren = BeanProperties

Properties are reusable:

IValueProperty selection = WidgetProperties.selection();
IObservableValue buttonSelection = selection.observe(button);
IObservableValue comboSelection = selection.observe(combo);
IObservableValue spinnerSelection = selection.observe(spinner);

But most importantly, they are easy to implement. Let's close with a real-world example:

DataBinding does not come with built-in support for observing the selection of a DateTime widget (see bug 169876 for an explanation why). However a useful use case is to observe the date portion (year+month+day) and set the time of day to midnight.

The following is a complete property implementation for the DateTime#selection property, that you are free to use in your own projects:

public class DateTimeSelectionProperty extends SimpleValueProperty {
public Object getValueType() {
return Date.class;

// One calendar per thread to preserve thread-safety
private static final ThreadLocal calendar =
new ThreadLocal() {
protected Object initialValue() {
return Calendar.getInstance();

protected Object doGetValue(Object source) {
Calendar cal = (Calendar) calendar.get();

DateTime dateTime = (DateTime) source;
cal.set(dateTime.getYear(), dateTime.getMonth(),
return cal.getTime();

protected void doSetValue(Object source, Object value) {
Calendar cal = (Calendar) calendar.get();
cal.setTime((Date) value);

DateTime dateTime = (DateTime) source;

public INativePropertyListener adaptListener(
ISimplePropertyListener listener) {
return new WidgetListener(listener);

private class WidgetListener implements INativePropertyListener,
Listener {
private final ISimplePropertyListener listener;

protected WidgetListener(ISimplePropertyListener listener) {
this.listener = listener;

public void handleEvent(Event event) {
new SimplePropertyEvent(event.widget,
DateTimeSelectionProperty.this, null));

protected void doAddListener(Object source,
INativePropertyListener listener) {
((DateTime) source).addListener(
SWT.Selection, (Listener) listener);

protected void doRemoveListener(Object source,
INativePropertyListener listener) {
((DateTime) source).removeListener(
SWT.Selection, (Listener) listener);

public IObservableValue observe(Object source) {
// For widgets, we want the display realm instead of
// Realm.getDefault()
Realm realm = SWTObservables.getRealm(
((Widget) source).getDisplay());
return observe(realm, source);

Now we can observe the selection of a DateTime:

IObservableValue selection =
new DateTimeSelectionProperty().observe(dateTime);

Today we released WidgetValueProperty as public API, but did not make it in time for M5. However in the future (starting in the next integration build), implementing properties for widgets will be much simpler:

  • Omit the adaptListener, doAddListener, and doRemoveListener methods
  • Omit the WidgetListener class
  • Omit the observe() method
  • Add a no-arg constructor with a call to super(eventType) in the constructor.

In the example the constructor would call "super(SWT.Selection)". As long as the the widget supports untyped listeners, WidgetValueProperty will handle the listener parts for you.