KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > internal > databinding > provisional > swt > ControlUpdater


1 /*******************************************************************************
2  * Copyright (c) 2005, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jface.internal.databinding.provisional.swt;
12
13 import org.eclipse.core.databinding.observable.ChangeEvent;
14 import org.eclipse.core.databinding.observable.IChangeListener;
15 import org.eclipse.core.databinding.observable.IObservable;
16 import org.eclipse.core.databinding.observable.ObservableTracker;
17 import org.eclipse.swt.events.DisposeEvent;
18 import org.eclipse.swt.events.DisposeListener;
19 import org.eclipse.swt.events.PaintEvent;
20 import org.eclipse.swt.events.PaintListener;
21 import org.eclipse.swt.widgets.Control;
22
23 /**
24  * NON-API - A ControlUpdater updates an SWT control in response to changes in the model.
25  * By wrapping a block of code in a ControlUpdater, clients can rely on the fact
26  * that the block of code will be re-executed whenever anything changes in the
27  * model that might affect its behavior.
28  *
29  * <p>
30  * ControlUpdaters only execute when their controls are visible. If something changes
31  * in the model while the control is invisible, the updator is flagged as dirty and
32  * the updator stops listening to the model until the next time the control repaints.
33  * This saves CPU cycles by deferring UI updates to widgets that are currently invisible.
34  * </p>
35  *
36  * <p>
37  * Clients should subclass this when copying information from the model to
38  * a control. Typical usage:
39  * </p>
40  *
41  * <ul>
42  * <li>Override updateControl. It should do whatever is necessary to display
43  * the contents of the model in the control.</li>
44  * <li>In the constructor, attach listeners to the model. The listeners should
45  * call markDirty whenever anything changes in the model that affects
46  * updateControl. Note: this step can be omitted when calling any method
47  * tagged with "@TrackedGetter" since ControlUpdater will automatically attach
48  * a listener to any object if a "@TrackedGetter" method is called in
49  * updateControl.</li>
50  * <li>(optional)Extend dispose() to remove any listeners attached in the constructor</li>
51  * </ul>
52  *
53  * <p>
54  * Example:
55  * </p>
56  *
57  * <code>
58  * // Displays an observable value in a label and keeps the label in synch with changes
59  * // in the value.
60  * IReadableValue someValue = ...
61  * final Label myLabel = new Label(parent, SWT.NONE);
62  * new ControlUpdater(myLabel) {
63  * protected void updateControl() {
64  * myLabel.setText(someValue.getValue().toString);
65  * }
66  * }
67  * // myLabel will display the value of someValue the next time it repaints, and will automatically
68  * // be updated whenever someValue changes and the label is visible
69  * </code>
70  *
71  * @since 1.1
72  */
73 public abstract class ControlUpdater {
74     
75     private class PrivateInterface implements PaintListener,
76         DisposeListener, Runnable JavaDoc, IChangeListener {
77         
78         // PaintListener implementation
79 public void paintControl(PaintEvent e) {
80             updateIfNecessary();
81         }
82
83         // DisposeListener implementation
84 public void widgetDisposed(DisposeEvent e) {
85             ControlUpdater.this.dispose();
86         }
87         
88         // Runnable implementation. This method runs at most once per repaint whenever the
89 // value gets marked as dirty.
90 public void run() {
91             if (theControl != null && !theControl.isDisposed() && theControl.isVisible()) {
92                 updateIfNecessary();
93             }
94         }
95         
96         // IChangeListener implementation (listening to the ComputedValue)
97 public void handleChange(ChangeEvent event) {
98             // Whenever this updator becomes dirty, schedule the run() method
99 makeDirty();
100         }
101         
102     }
103     
104     private Runnable JavaDoc updateRunnable = new Runnable JavaDoc() {
105         public void run() {
106             updateControl();
107         }
108     };
109     
110     private PrivateInterface privateInterface = new PrivateInterface();
111     private Control theControl;
112     private IObservable[] dependencies = new IObservable[0];
113     private boolean dirty = false;
114     
115     /**
116      * Creates an updator for the given control.
117      *
118      * @param toUpdate control to update
119      */
120     public ControlUpdater(Control toUpdate) {
121         theControl = toUpdate;
122         
123         theControl.addDisposeListener(privateInterface);
124         theControl.addPaintListener(privateInterface);
125         makeDirty();
126     }
127     
128     private void updateIfNecessary() {
129         if (dirty) {
130             dependencies = ObservableTracker.runAndMonitor(updateRunnable, privateInterface, null);
131             dirty = false;
132         }
133     }
134
135     /**
136      * This is called automatically when the control is disposed. It may also
137      * be called explicitly to remove this updator from the control. Subclasses
138      * will normally extend this method to detach any listeners they attached
139      * in their constructor.
140      */
141     public void dispose() {
142         theControl.removeDisposeListener(privateInterface);
143         theControl.removePaintListener(privateInterface);
144
145         stopListening();
146     }
147
148     private void stopListening() {
149         // Stop listening for dependency changes
150 for (int i = 0; i < dependencies.length; i++) {
151             IObservable observable = dependencies[i];
152                 
153             observable.removeChangeListener(privateInterface);
154         }
155     }
156
157     /**
158      * Updates the control. This method will be invoked once after the
159      * updator is created, and once before any repaint during which the
160      * control is visible and dirty.
161      *
162      * <p>
163      * Subclasses should overload this method to provide any code that
164      * changes the appearance of the widget.
165      * </p>
166      */
167     protected abstract void updateControl();
168     
169     /**
170      * Marks this updator as dirty. Causes the updateControl method to
171      * be invoked before the next time the control is repainted.
172      */
173     protected final void makeDirty() {
174         if (!dirty) {
175             dirty = true;
176             stopListening();
177             SWTUtil.runOnce(theControl.getDisplay(), privateInterface);
178         }
179     }
180     
181 }
182
Popular Tags