E
- the list element typepublic abstract static class ListChangeListener.Change<E>
extends java.lang.Object
ObservableList
. The change may consist of one or more actual
changes and must be iterated by calling the next()
method.
Each change must be one of the following:
wasPermutated()
returns true in this case.
The permutation happened at range between from
(inclusive) and to
(exclusive) and
can be queried by calling getPermutation(int)
method.
wasAdded()
, wasRemoved()
returns true.
If both methods return true, wasReplaced()
will also return true.
The getRemoved()
method returns a list of elements that have been
replaced or removed from the list.
The range between from
(inclusive) and to
(exclusive)
denotes the sublist of the list that contain new elements. Note that this is a half-open
interval, so if no elements were added, getFrom()
is equal to getTo()
.
It is possible to get a list of added elements by calling getAddedSubList().
Note that in order to maintain correct indexes of the separate add/remove changes, these changes
must be sorted by their from
index.
wasUpdated()
return true on an update change.
All elements between from
(inclusive) and to
(exclusive) were updated.
next()
method before calling
any other method of Change
. The same applies after calling reset()
.
The only methods that works at any time is getList()
.
Typical usage is to observe changes on an ObservableList in order
to hook or unhook (or add or remove a listener) or in order to maintain
some invariant on every element in that ObservableList. A common code
pattern for doing this looks something like the following:
ObservableList<Item> theList = ...; theList.addListener(new ListChangeListener<Item>() { public void onChanged(Change<Item> c) { while (c.next()) { if (c.wasPermutated()) { for (int i = c.getFrom(); i < c.getTo(); ++i) { //permutate } } else if (c.wasUpdated()) { //update item } else { for (Item remitem : c.getRemoved()) { remitem.remove(Outer.this); } for (Item additem : c.getAddedSubList()) { additem.add(Outer.this); } } } }); }
Warning: This class directly accesses the source list to acquire information about the changes.
This effectively makes the Change object invalid when another change occurs on the list.
For this reason it is not safe to use this class on a different thread.
It also means the source list cannot be modified inside the listener since that would invalidate this Change object
for all subsequent listeners.
Note: in case the change contains multiple changes of different type, these changes must be in the following order: permutation change(s), add or remove changes, update changes This is because permutation changes cannot go after add/remove changes as they would change the position of added elements. And on the other hand, update changes must go after add/remove changes because they refer with their indexes to the current state of the list, which means with all add/remove changes applied.
Modifier and Type | Field and Description |
---|---|
private ObservableList<E> |
list |
Constructor and Description |
---|
Change(ObservableList<E> list)
Constructs a new Change instance on the given list.
|
Modifier and Type | Method and Description |
---|---|
int |
getAddedSize()
Returns the size of the interval that was added.
|
java.util.List<E> |
getAddedSubList()
Returns a subList view of the list that contains only the elements added.
|
abstract int |
getFrom()
If
wasAdded() is true, the interval contains all the values that were added. |
ObservableList<E> |
getList()
The source list of the change.
|
protected abstract int[] |
getPermutation()
If this change is a permutation, it returns an integer array
that describes the permutation.
|
int |
getPermutation(int i)
This method allows developers to observe the permutations that occurred in this change.
|
abstract java.util.List<E> |
getRemoved()
An immutable list of removed/replaced elements.
|
int |
getRemovedSize()
Returns the size of
getRemoved() list. |
abstract int |
getTo()
The end of the change interval.
|
abstract boolean |
next()
Goes to the next change.
|
abstract void |
reset()
Resets to the initial stage.
|
boolean |
wasAdded()
Indicates if elements were added during this change.
|
boolean |
wasPermutated()
Indicates if the change was only a permutation.
|
boolean |
wasRemoved()
Indicates if elements were removed during this change.
|
boolean |
wasReplaced()
Indicates if elements were replaced during this change.
|
boolean |
wasUpdated()
|
private final ObservableList<E> list
public Change(ObservableList<E> list)
list
- The list that was changedpublic abstract boolean next()
next()
before
calling other methods. The first next()
call will make this object
represent the first change.public abstract void reset()
next()
must be called
before working with the first change.public ObservableList<E> getList()
public abstract int getFrom()
wasAdded()
is true, the interval contains all the values that were added.
If wasPermutated()
is true, the interval marks the values that were permutated.
If wasRemoved()
is true and wasAdded
is false, getFrom()
and getTo()
should return the same number - the place where the removed elements were positioned in the list.java.lang.IllegalStateException
- if this Change instance is in initial statepublic abstract int getTo()
java.lang.IllegalStateException
- if this Change instance is in initial stategetFrom()
public abstract java.util.List<E> getRemoved()
java.lang.IllegalStateException
- if this Change instance is in initial statepublic boolean wasPermutated()
java.lang.IllegalStateException
- if this Change instance is in initial statepublic boolean wasAdded()
java.lang.IllegalStateException
- if this Change instance is in initial statepublic boolean wasRemoved()
wasRemoved()
returning
true. See wasReplaced()
.java.lang.IllegalStateException
- if this Change instance is in initial statepublic boolean wasReplaced()
Usually, it's not necessary to use this method directly.
Handling remove operation and then add operation, as in the example in
the ListChangeListener.Change
class javadoc, will effectively handle the set operation.
wasAdded() && wasRemoved()
java.lang.IllegalStateException
- if this Change instance is in initial statepublic boolean wasUpdated()
getFrom()
(inclusive)
to getTo()
exclusive has changed.
This is the only optional event type and may not be
fired by all ObservableLists.public java.util.List<E> getAddedSubList()
c.getList().subList(c.getFrom(), c.getTo());
for (Node n : change.getAddedSubList()) {
// do something
}
java.lang.IllegalStateException
- if this Change instance is in initial statepublic int getRemovedSize()
getRemoved()
list.java.lang.IllegalStateException
- if this Change instance is in initial statepublic int getAddedSize()
java.lang.IllegalStateException
- if this Change instance is in initial stateprotected abstract int[] getPermutation()
getFrom()
of the list. The same applies
for the last index and getTo()
.
The method is used by wasPermutated()
and getPermutation(int)
methods.java.lang.IllegalStateException
- if this Change instance is in initial statepublic int getPermutation(int i)
change.getPermutation(oldIndex);Note: default implementation of this method takes the information from
getPermutation()
method. You don't have to override this method.i
- the old index that contained the element prior to this changejava.lang.IndexOutOfBoundsException
- if i is out of the bounds of the listjava.lang.IllegalStateException
- if this is not a permutation change