Mercurial > projects > dwt2
comparison org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/IObservable.d @ 95:6208d4f6a277
Added trees for databinding.beans and observable
author | Frank Benoit <benoit@tionex.de> |
---|---|
date | Tue, 21 Apr 2009 10:55:51 +0200 |
parents | |
children | b74ac5dfcc06 |
comparison
equal
deleted
inserted
replaced
94:1d37a7813832 | 95:6208d4f6a277 |
---|---|
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 *******************************************************************************/ | |
11 package org.eclipse.core.databinding.observable; | |
12 | |
13 /** | |
14 * An object with state that allows to listen for state changes. | |
15 * | |
16 * <p> | |
17 * Implementations must not manage listeners themselves, listener management | |
18 * must be delegated to a private instance of type {@link ChangeSupport} if it | |
19 * is not inherited from {@link AbstractObservable}. | |
20 * </p> | |
21 * | |
22 * @noextend This interface is not intended to be extended by clients. | |
23 * @noimplement This interface is not intended to be implemented by clients. | |
24 * Clients should instead subclass one of the classes in the | |
25 * framework that implement this interface. Note that direct | |
26 * implementers of this interface outside of the framework will be | |
27 * broken in future releases when methods are added to this | |
28 * interface. | |
29 * | |
30 * @since 1.0 | |
31 * | |
32 */ | |
33 public interface IObservable { | |
34 | |
35 /** | |
36 * Returns the realm for this observable. Unless otherwise specified, | |
37 * getters and setters must be accessed from within this realm. Listeners | |
38 * will be within this realm when they receive events from this observable. | |
39 * <p> | |
40 * Because observables can only be accessed from within one realm, and they | |
41 * always fire events on that realm, their state can be observed in an | |
42 * incremental way. It is always safe to call getters of an observable from | |
43 * within a change listener attached to that observable. | |
44 * </p> | |
45 * | |
46 * @return the realm | |
47 */ | |
48 public Realm getRealm(); | |
49 | |
50 /** | |
51 * Adds the given change listener to the list of change listeners. Change | |
52 * listeners are notified about changes of the state of this observable in a | |
53 * generic way, without specifying the change that happened. To get the | |
54 * changed state, a change listener needs to query for the current state of | |
55 * this observable. | |
56 * | |
57 * @param listener | |
58 */ | |
59 public void addChangeListener(IChangeListener listener); | |
60 | |
61 /** | |
62 * Removes the given change listener from the list of change listeners. Has | |
63 * no effect if the given listener is not registered as a change listener. | |
64 * | |
65 * @param listener | |
66 */ | |
67 public void removeChangeListener(IChangeListener listener); | |
68 | |
69 /** | |
70 * Adds the given stale listener to the list of stale listeners. Stale | |
71 * listeners are notified when an observable object becomes stale, not when | |
72 * is becomes non-stale. | |
73 * | |
74 * @param listener | |
75 * | |
76 * @see #isStale() | |
77 */ | |
78 public void addStaleListener(IStaleListener listener); | |
79 | |
80 /** | |
81 * Removes the given stale listener from the list of stale listeners. Has no | |
82 * effect if the given listener is not registered as a stale listener. | |
83 * | |
84 * @param listener | |
85 */ | |
86 public void removeStaleListener(IStaleListener listener); | |
87 | |
88 /** | |
89 * Returns whether the state of this observable is stale and is expected to | |
90 * change soon. A non-stale observable that becomes stale will notify its | |
91 * stale listeners. A stale object that becomes non-stale does so by | |
92 * changing its state and notifying its change listeners, it does <b>not</b> | |
93 * notify its stale listeners about becoming non-stale. Clients that do not | |
94 * expect asynchronous changes may ignore staleness of observable objects. | |
95 * | |
96 * @return true if this observable's state is stale and will change soon. | |
97 * | |
98 * @TrackedGetter - implementers must call | |
99 * {@link ObservableTracker#getterCalledcast(IObservable)}. | |
100 */ | |
101 public bool isStale(); | |
102 | |
103 /** | |
104 * Disposes of this observable object, removing all listeners registered | |
105 * with this object, and all listeners this object might have registered on | |
106 * other objects. | |
107 */ | |
108 public void dispose(); | |
109 } |