Module javafx.base
Package javafx.collections

Class ListChangeListener.Change<E>

java.lang.Object
javafx.collections.ListChangeListener.Change<E>
Type Parameters:
E - the list element type
Enclosing interface:
ListChangeListener<E>
public abstract static class ListChangeListener.Change<E> extends Object
Represents a report of changes done to an 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 between from (inclusive) and to (exclusive) and can be queried by calling getPermutation(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) 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.

  • Update change : wasUpdated() return true on an update change. All elements between from (inclusive) and to (exclusive) were updated.
Important: It's necessary to call 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