Mercurial > projects > dwt2

comparison org.eclipse.core.databinding/src/org/eclipse/core/databinding/DataBindingContext.d @ 78:0a55d2d5a946

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added file for databinding
author Frank Benoit <benoit@tionex.de>
date Tue, 14 Apr 2009 11:35:29 +0200
parents
children 383ce7bd736b
comparison
equal deleted inserted replaced
76:f05e6e8b2f2d 78:0a55d2d5a946
1 /*******************************************************************************
2 * Copyright (c) 2005-2008 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 * Brad Reynolds - bug 159539
11 * Brad Reynolds - bug 140644
12 * Brad Reynolds - bug 159940
13 * Brad Reynolds - bug 116920, 159768
14 * Matthew Hall - bugs 118516, 124684, 218269
15 * Boris Bokowski - bug 218269
16 *******************************************************************************/
17 module org.eclipse.core.databinding.DataBindingContext;
18
19 import java.lang.all;
20
21 import java.util.Iterator;
22
23 import org.eclipse.core.databinding.observable.Observables;
24 import org.eclipse.core.databinding.observable.Realm;
25 import org.eclipse.core.databinding.observable.list.IObservableList;
26 import org.eclipse.core.databinding.observable.list.WritableList;
27 import org.eclipse.core.databinding.observable.map.IObservableMap;
28 import org.eclipse.core.databinding.observable.set.IObservableSet;
29 import org.eclipse.core.databinding.observable.value.IObservableValue;
30 import org.eclipse.core.internal.databinding.ValidationStatusMap;
31 import org.eclipse.core.runtime.Assert;
32 import org.eclipse.core.runtime.IStatus;
33
34 /**
35 * A DataBindingContext is the point of contact for the creation and management
36 * of {@link Binding bindings}, and aggregates validation statuses of its
37 * bindings, or more generally, its validation status providers.
38 * <p>
39 * A DataBindingContext provides the following abilities:
40 * <ul>
41 * <li>Ability to create bindings between
42 * {@link IObservableValue observable values}.</li>
43 * <li>Ability to create bindings between
44 * {@link IObservableList observable lists}.</li>
45 * <li>Access to the bindings created by the instance.</li>
46 * <li>Access to the list of validation status providers (this includes all
47 * bindings).</li>
48 * </ul>
49 * </p>
50 * <p>
51 * Multiple contexts can be used at any point in time. One strategy for the
52 * management of contexts is the aggregation of validation statuses. For example
53 * an <code>IWizardPage</code> could use a single context and the statuses
54 * could be aggregated to set the page status and fulfillment. Each page in the
55 * <code>IWizard</code> would have its own context instance.
56 * </p>
57 *
58 * @since 1.0
59 */
60 public class DataBindingContext {
61 private WritableList bindings;
62 private WritableList validationStatusProviders;
63
64 /**
65 * Unmodifiable version of {@link #bindings} for public exposure.
66 */
67 private IObservableList unmodifiableBindings;
68 /**
69 * Unmodifiable version of {@link #validationStatusProviders} for public
70 * exposure.
71 */
72 private IObservableList unmodifiableStatusProviders;
73
74 private IObservableMap validationStatusMap;
75
76 private Realm validationRealm;
77
78 /**
79 * Creates a data binding context, using the current default realm for the
80 * validation observables.
81 *
82 * @see Realm
83 */
84 public this() {
85 this(Realm.getDefault());
86 }
87
88 /**
89 * Creates a data binding context using the given realm for the validation
90 * observables.
91 *
92 * @param validationRealm
93 * the realm to be used for the validation observables
94 *
95 * @see Realm
96 */
97 public this(Realm validationRealm) {
98 Assert.isNotNull(validationRealm, "Validation realm cannot be null"); //$NON-NLS-1$
99 this.validationRealm = validationRealm;
100
101 bindings = new WritableList(validationRealm);
102 unmodifiableBindings = Observables.unmodifiableObservableList(bindings);
103
104 validationStatusProviders = new WritableList(validationRealm);
105 unmodifiableStatusProviders = Observables
106 .unmodifiableObservableList(validationStatusProviders);
107
108 validationStatusMap = new ValidationStatusMap(validationRealm, bindings);
109 }
110
111 /**
112 * Creates a {@link Binding} to synchronize the values of two
113 * {@link IObservableValue observable values}. During synchronization
114 * validation and conversion can be employed to customize the process. For
115 * specifics on the customization of the process see
116 * {@link UpdateValueStrategy}.
117 *
118 * @param targetObservableValue
119 * target value, commonly a UI widget
120 * @param modelObservableValue
121 * model value
122 * @param targetToModel
123 * strategy to employ when the target is the source of the change
124 * and the model is the destination
125 * @param modelToTarget
126 * strategy to employ when the model is the source of the change
127 * and the target is the destination
128 * @return created binding
129 *
130 * @see UpdateValueStrategy
131 */
132 public final Binding bindValue(IObservableValue targetObservableValue,
133 IObservableValue modelObservableValue,
134 UpdateValueStrategy targetToModel, UpdateValueStrategy modelToTarget) {
135 UpdateValueStrategy targetToModelStrategy = targetToModel !is null ? targetToModel
136 : createTargetToModelUpdateValueStrategy(targetObservableValue, modelObservableValue);
137 UpdateValueStrategy modelToTargetStrategy = modelToTarget !is null ? modelToTarget
138 : createModelToTargetUpdateValueStrategy(modelObservableValue, targetObservableValue);
139 targetToModelStrategy.fillDefaults(targetObservableValue, modelObservableValue);
140 modelToTargetStrategy.fillDefaults(modelObservableValue, targetObservableValue);
141 ValueBinding result = new ValueBinding(targetObservableValue,
142 modelObservableValue, targetToModelStrategy,
143 modelToTargetStrategy);
144 result.init(this);
145 return result;
146 }
147
148 /**
149 * Returns an update value strategy to be used for copying values from the
150 * from value to the to value. Clients may override.
151 *
152 * @param fromValue
153 * @param toValue
154 * @return a update value strategy
155 */
156 protected UpdateValueStrategy createModelToTargetUpdateValueStrategy(
157 IObservableValue fromValue, IObservableValue toValue) {
158 return new UpdateValueStrategy();
159 }
160
161 /**
162 * Returns an update value strategy to be used for copying values from the
163 * from value to the to value. Clients may override.
164 *
165 * @param fromValue
166 * @param toValue
167 * @return a update value strategy
168 */
169 protected UpdateValueStrategy createTargetToModelUpdateValueStrategy(
170 IObservableValue fromValue, IObservableValue toValue) {
171 return new UpdateValueStrategy();
172 }
173
174 /**
175 * Creates a {@link Binding} to synchronize the values of two
176 * {@link IObservableList observable lists}. During synchronization
177 * validation and conversion can be employed to customize the process. For
178 * specifics on the customization of the process see
179 * {@link UpdateListStrategy}.
180 *
181 * @param targetObservableList
182 * target list, commonly a list representing a list in the UI
183 * @param modelObservableList
184 * model list
185 * @param targetToModel
186 * strategy to employ when the target is the source of the change
187 * and the model is the destination
188 * @param modelToTarget
189 * strategy to employ when the model is the source of the change
190 * and the target is the destination
191 * @return created binding
192 *
193 * @see UpdateListStrategy
194 */
195 public final Binding bindList(IObservableList targetObservableList,
196 IObservableList modelObservableList,
197 UpdateListStrategy targetToModel, UpdateListStrategy modelToTarget) {
198 UpdateListStrategy targetToModelStrategy = targetToModel !is null ? targetToModel
199 : createTargetToModelUpdateListStrategy(targetObservableList,
200 modelObservableList);
201 UpdateListStrategy modelToTargetStrategy = modelToTarget !is null ? modelToTarget
202 : createModelToTargetUpdateListStrategy(modelObservableList,
203 targetObservableList);
204 targetToModelStrategy.fillDefaults(targetObservableList,
205 modelObservableList);
206 modelToTargetStrategy.fillDefaults(modelObservableList,
207 targetObservableList);
208 ListBinding result = new ListBinding(targetObservableList,
209 modelObservableList, targetToModelStrategy,
210 modelToTargetStrategy);
211 result.init(this);
212 return result;
213 }
214
215 /**
216 * @param modelObservableList
217 * @param targetObservableList
218 * @return an update list strategy
219 */
220 protected UpdateListStrategy createModelToTargetUpdateListStrategy(
221 IObservableList modelObservableList,
222 IObservableList targetObservableList) {
223 return new UpdateListStrategy();
224 }
225
226 /**
227 * @param targetObservableList
228 * @param modelObservableList
229 * @return an update list strategy
230 */
231 protected UpdateListStrategy createTargetToModelUpdateListStrategy(
232 IObservableList targetObservableList,
233 IObservableList modelObservableList) {
234 return new UpdateListStrategy();
235 }
236
237 /**
238 * Creates a {@link Binding} to synchronize the values of two
239 * {@link IObservableSet observable sets}. During synchronization
240 * validation and conversion can be employed to customize the process. For
241 * specifics on the customization of the process see
242 * {@link UpdateSetStrategy}.
243 *
244 * @param targetObservableSet
245 * target set, commonly a set representing a set in the UI
246 * @param modelObservableSet
247 * model set
248 * @param targetToModel
249 * strategy to employ when the target is the source of the change
250 * and the model is the destination
251 * @param modelToTarget
252 * strategy to employ when the model is the source of the change
253 * and the target is the destination
254 * @return created binding
255 * @since 1.1
256 */
257 public final Binding bindSet(IObservableSet targetObservableSet,
258 IObservableSet modelObservableSet, UpdateSetStrategy targetToModel,
259 UpdateSetStrategy modelToTarget) {
260 if (targetToModel is null)
261 targetToModel = createTargetToModelUpdateSetStrategy(
262 targetObservableSet, modelObservableSet);
263 if (modelToTarget is null)
264 modelToTarget = createModelToTargetUpdateSetStrategy(
265 modelObservableSet, targetObservableSet);
266 targetToModel.fillDefaults(targetObservableSet, modelObservableSet);
267 modelToTarget.fillDefaults(modelObservableSet, targetObservableSet);
268 SetBinding result = new SetBinding(targetObservableSet,
269 modelObservableSet, targetToModel, modelToTarget);
270 result.init(this);
271 return result;
272 }
273
274 /**
275 * @param targetObservableSet
276 * @param modelObservableSet
277 * @return a default set update strategy
278 * @since 1.1
279 */
280 protected UpdateSetStrategy createTargetToModelUpdateSetStrategy(
281 IObservableSet targetObservableSet,
282 IObservableSet modelObservableSet) {
283 return new UpdateSetStrategy();
284 }
285
286 /**
287 * @param modelObservableSet
288 * @param targetObservableSet
289 * @return a default set update strategy
290 * @since 1.1
291 */
292 protected UpdateSetStrategy createModelToTargetUpdateSetStrategy(
293 IObservableSet modelObservableSet,
294 IObservableSet targetObservableSet) {
295 return new UpdateSetStrategy();
296 }
297
298 /**
299 * Disposes of this data binding context and all bindings and validation
300 * status providers that were added to this context.
301 */
302 public final void dispose() {
303 Binding[] bindingArray = cast(Binding[]) bindings.toArray(new Binding[bindings.size()]);
304 for (int i = 0; i < bindingArray.length; i++) {
305 bindingArray[i].dispose();
306 }
307 ValidationStatusProvider[] statusProviderArray = cast(ValidationStatusProvider[]) validationStatusProviders
308 .toArray(new ValidationStatusProvider[validationStatusProviders
309 .size()]);
310 for (int i = 0; i < statusProviderArray.length; i++) {
311 if (!statusProviderArray[i].isDisposed())
312 statusProviderArray[i].dispose();
313 }
314 }
315
316 /**
317 * Returns an unmodifiable observable list with elements of type
318 * {@link Binding}, ordered by time of addition.
319 *
320 * @return the observable list containing all bindings
321 */
322 public final IObservableList getBindings() {
323 return unmodifiableBindings;
324 }
325
326 /**
327 * Returns an unmodifiable observable list with elements of type
328 * {@link ValidationStatusProvider}, ordered by time of addition.
329 *
330 * @return the observable list containing all bindings
331 * @since 1.1
332 */
333 public final IObservableList getValidationStatusProviders() {
334 return unmodifiableStatusProviders;
335 }
336
337 /**
338 * Returns an observable map from bindings (type: {@link Binding}) to
339 * statuses (type: {@link IStatus}). The keys of the map are the bindings
340 * returned by {@link #getBindings()}, and the values are the current
341 * validaion status objects for each binding.
342 *
343 * @return the observable map from bindings to status objects.
344 *
345 * @deprecated as of 1.1, please use {@link #getValidationStatusProviders()}
346 */
347 public final IObservableMap getValidationStatusMap() {
348 return validationStatusMap;
349 }
350
351 /**
352 * Adds the given binding to this data binding context. This will also add
353 * the given binding to the list of validation status providers.
354 *
355 * @param binding
356 * The binding to add.
357 * @see #addValidationStatusProvidercast(ValidationStatusProvider)
358 * @see #getValidationStatusProviders()
359 */
360 public void addBinding(Binding binding) {
361 addValidationStatusProvider(binding);
362 bindings.add(binding);
363 }
364
365 /**
366 * Adds the given validation status provider to this data binding context.
367 *
368 * @param validationStatusProvider
369 * The validation status provider to add.
370 * @since 1.1
371 */
372 public void addValidationStatusProvider(
373 ValidationStatusProvider validationStatusProvider) {
374 validationStatusProviders.add(validationStatusProvider);
375 }
376
377 /**
378 * Updates all model observable objects to reflect the current state of the
379 * target observable objects.
380 *
381 */
382 public final void updateModels() {
383 for (Iterator it = bindings.iterator(); it.hasNext();) {
384 Binding binding = cast(Binding) it.next();
385 binding.updateTargetToModel();
386 }
387 }
388
389 /**
390 * Updates all target observable objects to reflect the current state of the
391 * model observable objects.
392 *
393 */
394 public final void updateTargets() {
395 for (Iterator it = bindings.iterator(); it.hasNext();) {
396 Binding binding = cast(Binding) it.next();
397 binding.updateModelToTarget();
398 }
399 }
400
401 /**
402 * Removes the given binding.
403 *
404 * @param binding
405 * @return <code>true</code> if was associated with the context,
406 * <code>false</code> if not
407 */
408 public bool removeBinding(Binding binding) {
409 return bindings.remove(binding) && removeValidationStatusProvider(binding);
410 }
411
412 /**
413 * Removes the validation status provider.
414 *
415 * @param validationStatusProvider
416 * @return <code>true</code> if was associated with the context,
417 * <code>false</code> if not
418 * @since 1.1
419 */
420 public bool removeValidationStatusProvider(
421 ValidationStatusProvider validationStatusProvider) {
422 return validationStatusProviders.remove(validationStatusProvider);
423 }
424
425 /**
426 * Returns the validation realm.
427 *
428 * @return the realm for the validation observables
429 * @see Realm
430 */
431 public final Realm getValidationRealm() {
432 return validationRealm;
433 }
434 }