Getting started with Properties

Over the last few days, I’ve been communicating with a developer who was having trouble getting the Properties view to work with his view and objects. It turns out that the real problem was more a lack of understanding of the adapter framework. I came up with three progressive examples to demonstrate their use.

Using the Properties view is simple enough. Since it shows properties for the selected object, the first step to using it is to make sure that the workbench selection service knows about the object selected in your view. There’s an entire Eclipse Corner article written on the subject of the selection service. You can find that article here. The short version, assuming that your view uses a JFace table or tree viewer, is to include something like the following in your createPartControl method:

...
public void createPartControl(Composite parent) {
	viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL);
	viewer.setContentProvider(new ViewContentProvider());
	viewer.setLabelProvider(new ViewLabelProvider());

	getSite().setSelectionProvider(viewer);

	viewer.setInput(getViewSite());
}
...

I’ve marked the important part in bold. Once you have your view contributing to the workbench selection, you need to make sure that the objects that your view is selecting contribute properties. The easiest (but not necessary most correct) way to do this is to have your class implement the IPropertySource interface:

...
public class Person implements IPropertySource {
	private String name;
	private Object street;
	private Object city;

	public Person(String name) {
		this.name = name;
		this.street = "";
		this.city = "";
	}

	public Object getEditableValue() {
		return this;
	}

	public IPropertyDescriptor[] getPropertyDescriptors() {
		return new IPropertyDescriptor[] {
				new TextPropertyDescriptor("name", "Name"),
				new TextPropertyDescriptor("street", "Street"),
				new TextPropertyDescriptor("city", "City")
		};
	}

	public Object getPropertyValue(Object id) {
		if ("name".equals(id)) return name;
		else if ("street".equals(id)) return street;
		else if ("city".equals(id)) return city;
		return null;
	}

	public void setPropertyValue(Object id, Object value) {
		if ("name".equals(id)) name = (String)value;
		else if ("street".equals(id)) street = (String)value;
		else if ("city".equals(id)) city = (String)value;
	}

	public boolean isPropertySet(Object id) {
		return false;
	}

	public void resetPropertyValue(Object id) {
	}
}

In this example, my object has three properties that are all text values. I’ve marked in bold one of the property descriptors that defines the behaviour of the property in the Property view. The first parameter is the name of the property, and the second one is the label for that property in the view. There are other types of property descriptors that you can use; you can even make your own if you have a special type of property.

I’ve kept this example deliberately simple. My properties cannot be reset, nor does the implementation have any notion of whether or not properties have been set. A more sophisticated implementation will provide the user with more sophisticated options.

I indicated earlier that this solution is “not necessarily [the] most correct”. This is because, for this to work, my domain object needs to know about the very view-centric (and Eclipse-centric) notion of being a property source; in short, there is a tight-coupling between the model and view and this not a good thing™. This where adapters come in. I’ll introduce adapters in the next installment.

In the meantime, if you want to learn more about properties in Eclipse, check out these articles.