[jboss-user] [JBoss Tools] - How we use jface databinding in Deltacloud Tools

Tue Oct 26 11:53:25 EDT 2010

Andre Dietisheim [http://community.jboss.org/people/adietish] modified the document:

"How we use jface databinding in Deltacloud Tools"

To view the document, visit: http://community.jboss.org/docs/DOC-15964

--------------------------------------------------------------
h1. Less code
If you use jface databinding to code your swt views in Eclipse you'll get spared from writing listeners and updating code by hand. JFace databinding offers very nice abstractions and automatisms that offer funcitonalities for the vast majority of the tasks where you have to listen for user input and update the view accordingly.

h1. *Premise*
If you implement a complex and highly dynamic UI in Eclipse you'll have to code many many many listener that wait for user actions. Those listeners mostly do nothing spectacular but update widgets and models in reaction to the user inputs. You end up with a lot of repetitive boilerplate code. UI frameworks in the non-java land (ex. http://qt.nokia.com/products/  Trolltechs QT) already have approaches that are far more elegant and slick than what we knew for Swing and SWT.
By luck Eclipse has progressed in this area (since 2005!) and offers neat abstractions that help a lot in this area and lead to far more concise and a less verbose implementations: Jface Databinding!

h2. Usecase
We had to implement a wizard page that allows a user to create a connection to a deltacloud server. The user has to supply a name, an url and the credentials for it.

 http://community.jboss.org/servlet/JiveServlet/showImage/10530/cloud-connection-wizard.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/10530/cloud-connection-wizard.png 

Sounds pretty simple at first sight. Looking closer at it you'll discover few buttons that shall be disabled if you enter inacurrate values. To inform the user in a intuitive way, the inaccurate values shall be marked by decorations. Furthermore a wizard page shows a global  error message that reflects whether the user may finish the steps he's up to.

 http://community.jboss.org/servlet/JiveServlet/showImage/10531/invalid-url.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/10531/invalid-url.png 
h1. Solution
h2. No duplicate names
Our GUI holds multiple connections to various deltacloud servers. The wizard we discuss here allows you to edit existing connections or create new ones. You may of course not use a name that's already used for another connection. The wizard shall inform you that the name you chose is already used.

 http://community.jboss.org/servlet/JiveServlet/showImage/10533/duplicate-name.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/10533/duplicate-name.png 

To be intuitive the wizard shall decorate the field that's invalid. The wizard shall also show you what's wrong in cleartext and disallow you may to finish the wizard.

 http://community.jboss.org/servlet/JiveServlet/showImage/102-15964-11-10534/duplicate-name-markers.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15964-11-10534/450-338/duplicate-name-markers.png 

You may have a look at the code we have in our svn to see the source code we discuss here:  http://anonsvn.jboss.org/repos/jbosstools/trunk/deltacloud/plugins/org.jboss.tools.deltacloud.ui/src/org/jboss/tools/internal/deltacloud/ui/wizards/CloudConnectionPage.java CloudConnectionPage.java

*Enable and disable Finish button*
 http://community.jboss.org/servlet/JiveServlet/showImage/102-15964-11-10538/enable-disable-finish.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15964-11-10538/250-50/enable-disable-finish.png 

In non-technical pure logical terms there's a single trigger to all these markers: You entered a bad value to a field.
The wizard reacts by decorating the text field that holds a the duplicate name, it displays the error in the header and it disabled the Finish button.
Jface databinding offers a context that holds a global validity state for a form. If a form gets invalid, the golbal state gets invalid, too. A jface wizards is built upon several pages. Such a page is a form that may be globally valid or invalid.
> DataBindingContext dbc = new DataBindingContext();
To enable/disable the Finish button you now need to connect the wizard page to the DataBindingContext. Jface databinding will then enable/disable the Finish (or the Next Page button for instance) automatically for you. To bind the validity of the databinding context to the page validity, you only need 1 line of code:
> WizardPageSupport.create(this, dbc);
Jface databinding will now enable the finish button (or the next-page button) for you as soon as the form aka the databinding context is valid.

h2. Let's decorate the name text field
We have no settings that are tracked by jface databinding yet. Our databinding context's always valid for now. We will now add the name to our binding context, track its validity and propagate its state to the context.

h3. Observables

Jface databinding is a framework that is built upon the principle of *model-view-controller (MVC)*. It connects a view to a model and stips down the code that's needed to implement the controller.
It basically synchronizes the value that's in a view (a SWT widget in our case) to the value held in a model (a bean with a property name in our case). You may enter a new name in the widget and jface databinding makes sure that the model gets that new value. It of course does that the other way round, too: As soon as you set a new value to the model, jface databinding will set this value to the widget that's visible in the wizard.
In order to do that it must be aware of changes on both ends of this binding. It needs to be able to observe values and get notified of changes. Jface databinding implements its own observable pattern, it offers a standardized interface on both ends: *Observable*. 

 http://community.jboss.org/servlet/JiveServlet/showImage/102-15964-11-10539/observables.png  http://community.jboss.org/servlet/JiveServlet/downloadImage/102-15964-11-10539/450-367/observables.png 

SWT already offers Listeners that allow you to listen to changes in widgets and react to them. JFace databinding offers observable adapters that wrap these listeners and let them participate to the framework.
> IObservableValue textObservable = WidgetProperties.text(SWT.Modify).observe(nameText)
The jdk knows *PropertyChangeSupport* to observe changes in bean properties. Jface databinding also offers adapters to this observable pattern.
> IObservableValue beanPropertyObservable = BeanProperties.value(CloudConnectionModel.class, "name")
> 
>  
> IObservableValue beanPropertyObservable = BeanProperties.value(CloudConnectionModel.class, "name")

h1. Conclusione
--------------------------------------------------------------

Comment by going to Community
[http://community.jboss.org/docs/DOC-15964]

Create a new document in JBoss Tools at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2128]
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/jboss-user/attachments/20101026/6be3913a/attachment.html 