|
|
| (12 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| | == Data Binding Tutorial == | | == Data Binding Tutorial == |
| − | --[[User:Frank.schaare.gmail.com|Frank.schaare.gmail.com]] 20:24, 12 October 2007 (EDT)
| |
| − | === Terms ===
| |
| − | ----
| |
| | | | |
| − | * Model: a Model represents the Domain Model of your Application.
| + | Please see [http://www.vogella.com/articles/EclipseDataBinding/article.html Eclipse JFace Databinding and Validation - Tutorial] |
| − | * Target: a Target represents the GUI side.
| + | |
| − | === A first simple binding ===
| + | |
| − | ----
| + | |
| − | | + | |
| − | <p>Looking at the example snippets, you'll see a few SWT examples. This time, we'll create a very simple RCP view. Our createPartControl method has just one Text Element:</p>
| + | |
| − | <pre>
| + | |
| − | public void createPartControl(Composite parent){
| + | |
| − | | + | |
| − | name = new Text(parent, SWT.BORDER);
| + | |
| − | final GridData gd_name = new GridData(SWT.FILL, SWT.CENTER, true, false);
| + | |
| − | name.setLayoutData(gd_name);
| + | |
| − | | + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>That Text name represents the Target of our binding. Let's add a simple Model:</p>
| + | |
| − | <pre>
| + | |
| − | static class Person extends ModelObject{
| + | |
| − | // A property...
| + | |
| − | String name = "HelloWorld";
| + | |
| − | | + | |
| − | public String getName() {
| + | |
| − | return name;
| + | |
| − | }
| + | |
| − | | + | |
| − | public void setName(String name) {
| + | |
| − | this.name = name;
| + | |
| − | }
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>As you may have noticed, the Person Class extends '''Model Object'''. If you want to bind your Domain Models, you'll have to ensure support for PropertyChangeSupport. The easiest way to achieve this, is to extend Model Object. You'll find a suitable Template in org.eclipse.jface.examples.databinding package.</p>
| + | |
| − | <p>To create your first binding, you need to instantiate a '''DataBindingContext'''. Create a method like this:</p>
| + | |
| − | <pre>
| + | |
| − | private DataBindingContext initDataBindings() {
| + | |
| − | DataBindingContext bindingContext = new DataBindingContext();
| + | |
| − | | + | |
| − | return bindingContext;
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>Next, we add a '''IObservableValue''' Object for the Target:</p>
| + | |
| − | <pre>
| + | |
| − | private DataBindingContext initDataBindings() {
| + | |
| − | DataBindingContext bindingContext = new DataBindingContext();
| + | |
| − | | + | |
| − | IObservableValue nameTextObserveWidget = SWTObservables.observeText(name, SWT.FocusOut);
| + | |
| − | | + | |
| − | return bindingContext;
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>The observeText method takes two params
| + | |
| − | <ul>
| + | |
| − | <li>name: the observed Control</li>
| + | |
| − | <li>event: when the model will be updated. Choices are SWT.FocusOut, SWT.Modify or SWT.NONE</li>
| + | |
| − | </ul>
| + | |
| − | </p>
| + | |
| − | <p>Second, we add a '''IObservableValue''' Object for the Model:</p>
| + | |
| − | <pre>
| + | |
| − | private DataBindingContext initDataBindings() {
| + | |
| − | DataBindingContext bindingContext = new DataBindingContext();
| + | |
| − | IObservableValue nameTextObserveWidget = SWTObservables.observeText(name, SWT.FocusOut);
| + | |
| − | | + | |
| − | IObservableValue personNameObserveValue = BeansObservables.observeValue(person, "name");
| + | |
| − | | + | |
| − | return bindingContext;
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>The observeValue method takes two params
| + | |
| − | <ul>
| + | |
| − | <li>bean: the observed bean</li>
| + | |
| − | <li>propertyName: the name of the observed property, in our case the persons name.</li>
| + | |
| − | </ul>
| + | |
| − | </p>
| + | |
| − | <p>Last, we need to bind Target and Model. This is done through the DataBindingContext#bindValue method:</p>
| + | |
| − | <pre>
| + | |
| − | private DataBindingContext initDataBindings() {
| + | |
| − | DataBindingContext bindingContext = new DataBindingContext();
| + | |
| − | IObservableValue nameTextObserveWidget = SWTObservables.observeText(name, SWT.FocusOut);
| + | |
| − | IObservableValue personNameObserveValue = BeansObservables.observeValue(person, "name");
| + | |
| − | | + | |
| − | bindingContext.bindValue(nameTextObserveWidget, personNameObserveValue, null, null);
| + | |
| − | | + | |
| − | return bindingContext;
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>The bindValue method takes four params
| + | |
| − | <ul>
| + | |
| − | <li>targetObservableValue: our first created IObservableValue </li>
| + | |
| − | <li>modelObservableValue: our second created IObservableValue </li>
| + | |
| − | <li>UpdateValueStrategy targetToModel: will be dicusssed later</li>
| + | |
| − | <li>UpdateValueStrategy modelToTarget: will be dicusssed later</li>
| + | |
| − | </ul>
| + | |
| − | </p>
| + | |
| − | <p>That's it. You successfully created your first JFace Data Binding !</p>
| + | |
| − | === Introducing UpdateValueStrategy ===
| + | |
| − | ----
| + | |
| − | | + | |
| − | <p>Next, we'll take a closer look at '''Snippet014WizardDialog''', to explore some advanced features.</p>
| + | |
| − | <p>Snippet014WizardDialog includes an inner class '''SampleWizardModel''':</p>
| + | |
| − | <pre>
| + | |
| − | static class SampleWizardModel {
| + | |
| − | IObservableValue intValue = new WritableValue(null, Integer.class);
| + | |
| − | IObservableValue dateValue = new WritableValue(null, Date.class);
| + | |
| − | }
| + | |
| − | </pre>
| + | |
| − | <p>Again, you'll find an IObservableValue, but with a few differences to our first example. First, it is instantiated as a '''WritableValue(Object initialValue, Object valueType)'''. This is a mutable implementation of IObservableValue that will maintain a value and fire change events when the value changes. Second, the IObservableValue is instantiated inside the Model, differently from our first example. If you are in a situation where you can't get PropertyChangeSupport by extending a class similar to ModelObject, this variant may be a good alternative.</p>
| + | |
| − | <p>As another nested inner Class, you'll find Class '''FirstWizardPage'''. In createControl method, a DataBindingContext is instantiated at first, no news right here. The binding is created with this code:</p>
| + | |
| − | <pre>
| + | |
| − | dbc.bindValue(SWTObservables.observeText(text, SWT.Modify),
| + | |
| − | ((SampleWizard) getWizard()).getModel().intValue,
| + | |
| − | new UpdateValueStrategy().setAfterConvertValidator(new SingleDigitValidator()),
| + | |
| − | null);
| + | |
| − | </pre>
| + | |
| − | <p>Oooh, what a monster. Fortunately, you have already some good knowledge to understand whats going on here. The first parameter is a Target IObservableValue bound to the Wizards Text control. It's provided with a SWT.Modify event, which means that anytime, the controls text changes, the Data Binding mechanism is invoked. The second parameter is the already dicussed WritableValue. Remember, it's an IObservableValue implementation, so again, we deal with two Observables. The third parameter ist the most interessting and new part of the story: first, a new '''UpdateValueStrategy''' is instantiated. This is required, when you have to deal with:
| + | |
| − | <ul>
| + | |
| − | <li>Validation</li>
| + | |
| − | <li>Conversion</li>
| + | |
| − | <li>Automatic processing</li>
| + | |
| − | </ul>
| + | |
| − | in your binding.
| + | |
| − | </p>
| + | |
| − | It offers five phases for manipulation where you can hook on:
| + | |
| − | <ul>
| + | |
| − | <li>Validate after get</li>
| + | |
| − | <li>Conversion</li>
| + | |
| − | <li>Validate after conversion</li>
| + | |
| − | <li>Validate before set</li>
| + | |
| − | <li>Value set</li>
| + | |
| − | </ul>
| + | |
| − | You may have a look to the '''UpdateValueStrategy''' JavaDocs, which is quite voluptuous documentated, for further Information.
| + | |
| − | <p>In our case, the method setAfterConvertValidator(IValidator validator) is called, which invokes the validator after the source value is converted to the type of the destination observable. setAfterConvertValidator eats an IValidator as param. This one is offered as another inner Class nested in Class FirstWizardPage. It simply checks, whether incoming value is between 0 and 9. If not, a '''ValidationStatus(IStatus.ERROR, message)''' is returned, resulting WizardPage1 moaning about the wrong value:</p>
| + | |
| − | [[Image:Snippet014WizardDialog.JPG]]
| + | |
| − | === Binding Collections ===
| + | |
| − | ----
| + | |
| − | === MasterDetail Binding ===
| + | |
| − | | + | |
| − | ----
| + | |
| − | | + | |
| − | === ObservablesManager ===
| + | |
| − | | + | |
| − | ----
| + | |
