- Type Parameters:
E
- the list element type
- Enclosing interface:
- ListChangeListener<E>
public abstract static class ListChangeListener.Change<E> extends 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:
- Permutation change :
wasPermutated()
returns true in this case. The permutation happened at range betweenfrom
(inclusive) andto
(exclusive) and can be queried by callinggetPermutation(int)
method. - Add or remove change : In this case, at least one of the
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) andto
(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 togetTo()
.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. - Update change :
wasUpdated()
return true on an update change. All elements betweenfrom
(inclusive) andto
(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.
- Since:
- JavaFX 2.0
-
Constructor Summary
Constructors Constructor Description Change(ObservableList<E> list)
Constructs a new Change instance on the given list. -
Method Summary
Modifier and Type Method Description int
getAddedSize()
Returns the size of the interval that was added.List<E>
getAddedSubList()
Returns a subList view of the list that contains only the elements added.abstract int
getFrom()
IfwasAdded()
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 List<E>
getRemoved()
An immutable list of removed/replaced elements.int
getRemovedSize()
Returns the size ofgetRemoved()
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()
-
Constructor Details
-
Change
Constructs a new Change instance on the given list.- Parameters:
list
- The list that was changed
-
-
Method Details
-
next
public abstract boolean next()Goes to the next change. The Change instance, in its initial state, is invalid and requires a call tonext()
before calling other methods. The firstnext()
call will make this object represent the first change.- Returns:
true
if switched to the next change,false
if this is the last change
-
reset
public abstract void reset()Resets to the initial stage. After this call,next()
must be called before working with the first change. -
getList
The source list of the change.- Returns:
- a list that was changed
-
getFrom
public abstract int getFrom()IfwasAdded()
is true, the interval contains all the values that were added. IfwasPermutated()
is true, the interval marks the values that were permutated. IfwasRemoved()
is true andwasAdded
is false,getFrom()
andgetTo()
should return the same number - the place where the removed elements were positioned in the list.- Returns:
- a beginning (inclusive) of an interval related to the change
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
getTo
public abstract int getTo()The end of the change interval.- Returns:
- an end (exclusive) of an interval related to the change
- Throws:
IllegalStateException
- if this Change instance is in initial state- See Also:
getFrom()
-
getRemoved
An immutable list of removed/replaced elements. If no elements were removed from the list, an empty list is returned.- Returns:
- a list with all the removed elements
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
wasPermutated
public boolean wasPermutated()Indicates if the change was only a permutation.- Returns:
true
if the change was just a permutation- Throws:
IllegalStateException
- if this Change instance is in initial state
-
wasAdded
public boolean wasAdded()Indicates if elements were added during this change.- Returns:
true
if something was added to the list- Throws:
IllegalStateException
- if this Change instance is in initial state
-
wasRemoved
public boolean wasRemoved()Indicates if elements were removed during this change. Note that using set will also produce a change withwasRemoved()
returning true. SeewasReplaced()
.- Returns:
true
if something was removed from the list- Throws:
IllegalStateException
- if this Change instance is in initial state
-
wasReplaced
public boolean wasReplaced()Indicates if elements were replaced during this change. This is usually true when set is called on the list. Set operation will act like remove and add operation at the same time.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.- Returns:
- same as
wasAdded() && wasRemoved()
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
wasUpdated
public boolean wasUpdated()Indicates that the elements betweengetFrom()
(inclusive) togetTo()
exclusive has changed. This is the only optional event type and may not be fired by all ObservableLists.- Returns:
true
if the current change is an update change- Since:
- JavaFX 2.1
-
getAddedSubList
Returns a subList view of the list that contains only the elements added. This is actually a shortcut toc.getList().subList(c.getFrom(), c.getTo());
for (Node n : change.getAddedSubList()) { // do something }
- Returns:
- the newly created sublist view that contains all the added elements
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
getRemovedSize
public int getRemovedSize()Returns the size ofgetRemoved()
list.- Returns:
- the number of removed items
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
getAddedSize
public int getAddedSize()Returns the size of the interval that was added.- Returns:
- the number of added items
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
getPermutation
protected abstract int[] getPermutation()If this change is a permutation, it returns an integer array that describes the permutation. This array maps directly from the previous indexes to the new ones. This method is not publicly accessible and therefore can return an array safely. The 0 index of the array corresponds to indexgetFrom()
of the list. The same applies for the last index andgetTo()
. The method is used bywasPermutated()
andgetPermutation(int)
methods.- Returns:
- empty array if this is not permutation or an integer array containing the permutation
- Throws:
IllegalStateException
- if this Change instance is in initial state
-
getPermutation
public int getPermutation(int i)This method allows developers to observe the permutations that occurred in this change. In order to get the new position of an element, you must call:change.getPermutation(oldIndex);
Note: default implementation of this method takes the information fromgetPermutation()
method. You don't have to override this method.- Parameters:
i
- the old index that contained the element prior to this change- Returns:
- the new index of the same element
- Throws:
IndexOutOfBoundsException
- if i is out of the bounds of the listIllegalStateException
- if this is not a permutation change
-