Modifier and Type	Class and Description
public abstract static class	ListChangeListener.Change< the list element type E> Represents a report of changes done to an `ObservableList`.

Modifier and Type	Method and Description
public void	onChanged(ListChangeListener.Change<? extends E> an object representing the change that was done c) Called after a change has been made to an ObservableList.

onChanged	back to summary
public void onChanged(ListChangeListener.Change<? extends E> c) Called after a change has been made to an ObservableList. Parameters c:ListChangeListener.Change<? extends E> an object representing the change that was done See Also `Change`

public abstract Class ListChangeListener.Change<E>

Class Inheritance

extends Object

java.lang.Object
javafx.collections.ListChangeListener.Change

Known Direct Subclasses

com.sun.javafx.collections.MappingChange, com.sun.javafx.collections.NonIterableChange, com.sun.javafx.collections.SourceAdapterChange, javafx.collections.ListChangeBuilder.SingleChange, javafx.collections.ListChangeBuilder.IterableChange

Type Parameters

<E>: the list element type

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

Field Summary

Modifier and Type	Field and Description
private final ObservableList<E>	list

Constructor Summary

Access	Constructor and Description
public	Change(ObservableList<E> The list that was changed list) Constructs a new Change instance on the given list.

Method Summary

Modifier and Type	Method and Description
public int	Returns: the number of added items getAddedSize() Returns the size of the interval that was added.
public List<E>	Returns: the newly created sublist view that contains all the added elements getAddedSubList() Returns a subList view of the list that contains only the elements added.
public abstract int	Returns: a beginning (inclusive) of an interval related to the change getFrom() If `wasAdded()` is true, the interval contains all the values that were added.
public ObservableList<E>	Returns: a list that was changed getList() The source list of the change.
protected abstract int[]	Returns: empty array if this is not permutation or an integer array containing the permutation getPermutation() If this change is a permutation, it returns an integer array that describes the permutation.
public int	Returns: the new index of the same element getPermutation(int the old index that contained the element prior to this change i) This method allows developers to observe the permutations that occurred in this change.
public abstract List<E>	Returns: a list with all the removed elements getRemoved() An immutable list of removed/replaced elements.
public int	Returns: the number of removed items getRemovedSize() Returns the size of `getRemoved()` list.
public abstract int	Returns: an end (exclusive) of an interval related to the change getTo() The end of the change interval.
public abstract boolean	Returns: `true` if switched to the next change, `false` if this is the last change next() Goes to the next change.
public abstract void	reset() Resets to the initial stage.
public boolean	Returns: `true` if something was added to the list wasAdded() Indicates if elements were added during this change.
public boolean	Returns: `true` if the change was just a permutation wasPermutated() Indicates if the change was only a permutation.
public boolean	Returns: `true` if something was removed from the list wasRemoved() Indicates if elements were removed during this change.
public boolean	Returns: same as `wasAdded() && wasRemoved()` wasReplaced() Indicates if elements were replaced during this change.
public boolean	Returns: `true` if the current change is an update change wasUpdated() Indicates that the elements between `getFrom()` (inclusive) to `getTo()` exclusive has changed.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

list	back to summary
private final ObservableList<E> list

Constructor Detail

Change	back to summary
public Change(ObservableList<E> list) Constructs a new Change instance on the given list. Parameters list:ObservableList<E> The list that was changed

Change

back to summary

public Change(ObservableList<E> list)

Constructs a new Change instance on the given list.

Parameters

list:ObservableList<E>: The list that was changed

Method Detail

getAddedSize	back to summary
public int getAddedSize() Returns the size of the interval that was added. Returns:int the number of added items Exceptions IllegalStateException: if this Change instance is in initial state

getAddedSize

back to summary

public int getAddedSize()

Returns the size of the interval that was added.

Returns:int

the number of added items

Exceptions

IllegalStateException:: if this Change instance is in initial state

getAddedSubList back to summary

getAddedSubList	back to summary
public List<E> getAddedSubList() Returns a subList view of the list that contains only the elements added. This is actually a shortcut to `c.getList().subList(c.getFrom(), c.getTo());` `for (Node n : change.getAddedSubList()) { // do something }` Returns:List<E> the newly created sublist view that contains all the added elements Exceptions IllegalStateException: if this Change instance is in initial state

public List<E> getAddedSubList()

Returns a subList view of the list that contains only the elements added. This is actually a shortcut to c.getList().subList(c.getFrom(), c.getTo());

for (Node n : change.getAddedSubList()) {
      // do something
}

Returns:List<E>

the newly created sublist view that contains all the added elements

Exceptions

IllegalStateException:: if this Change instance is in initial state

getFrom back to summary

getFrom	back to summary
public abstract int getFrom() If `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. Returns:int a beginning (inclusive) of an interval related to the change Exceptions IllegalStateException: if this Change instance is in initial state

public abstract int getFrom()

If 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.

Returns:int

a beginning (inclusive) of an interval related to the change

Exceptions

IllegalStateException:: if this Change instance is in initial state

getList	back to summary
public ObservableList<E> getList() The source list of the change. Returns:ObservableList<E> a list that was changed

getList

back to summary

public ObservableList<E> getList()

The source list of the change.

Returns:ObservableList<E>: a list that was changed

getPermutation back to summary

getPermutation	back to summary
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 index `getFrom()` of the list. The same applies for the last index and `getTo()`. The method is used by `wasPermutated()` and `getPermutation(int)` methods. Returns:int[] empty array if this is not permutation or an integer array containing the permutation Exceptions IllegalStateException: if this Change instance is in initial state

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 index getFrom() of the list. The same applies for the last index and getTo(). The method is used by wasPermutated() and getPermutation(int) methods.

Returns:int[]

empty array if this is not permutation or an integer array containing the permutation

Exceptions

IllegalStateException:: if this Change instance is in initial state

getPermutation back to summary

getPermutation	back to summary
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 from `getPermutation()` method. You don't have to override this method. Parameters i:int the old index that contained the element prior to this change Returns:int the new index of the same element Exceptions IndexOutOfBoundsException: if i is out of the bounds of the list IllegalStateException: if this is not a permutation change

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 from getPermutation() method. You don't have to override this method.

Parameters

i:int: the old index that contained the element prior to this change

Returns:int

the new index of the same element

Exceptions

IndexOutOfBoundsException:: if i is out of the bounds of the list
IllegalStateException:: if this is not a permutation change

getRemoved	back to summary
public abstract List<E> getRemoved() An immutable list of removed/replaced elements. If no elements were removed from the list, an empty list is returned. Returns:List<E> a list with all the removed elements Exceptions IllegalStateException: if this Change instance is in initial state

getRemoved

back to summary

public abstract List<E> getRemoved()

An immutable list of removed/replaced elements. If no elements were removed from the list, an empty list is returned.

Returns:List<E>

a list with all the removed elements

Exceptions

IllegalStateException:: if this Change instance is in initial state

getRemovedSize back to summary

getRemovedSize	back to summary
public int getRemovedSize() Returns the size of `getRemoved()` list. Returns:int the number of removed items Exceptions IllegalStateException: if this Change instance is in initial state

public int getRemovedSize()

Returns the size of getRemoved() list.

Returns:int

the number of removed items

Exceptions

IllegalStateException:: if this Change instance is in initial state

getTo back to summary

getTo	back to summary
public abstract int getTo() The end of the change interval. Returns:int an end (exclusive) of an interval related to the change Exceptions IllegalStateException: if this Change instance is in initial state See Also `getFrom()`

public abstract int getTo()

The end of the change interval.

Returns:int

an end (exclusive) of an interval related to the change

Exceptions

IllegalStateException:: if this Change instance is in initial state

See Also

getFrom()

next back to summary

next	back to summary
public abstract boolean next() Goes to the next change. The Change instance, in its initial state, is invalid and requires a call to `next()` before calling other methods. The first `next()` call will make this object represent the first change. Returns:boolean `true` if switched to the next change, `false` if this is the last change

public abstract boolean next()

Goes to the next change. The Change instance, in its initial state, is invalid and requires a call to next() before calling other methods. The first next() call will make this object represent the first change.

Returns:boolean: true if switched to the next change, false if this is the last change

reset	back to summary
public abstract void reset() Resets to the initial stage. After this call, `next()` must be called before working with the first change.

wasAdded back to summary

wasAdded	back to summary
public boolean wasAdded() Indicates if elements were added during this change. Returns:boolean `true` if something was added to the list Exceptions IllegalStateException: if this Change instance is in initial state

public boolean wasAdded()

Indicates if elements were added during this change.

Returns:boolean

true if something was added to the list

Exceptions

IllegalStateException:: if this Change instance is in initial state

wasPermutated back to summary

wasPermutated	back to summary
public boolean wasPermutated() Indicates if the change was only a permutation. Returns:boolean `true` if the change was just a permutation Exceptions IllegalStateException: if this Change instance is in initial state

public boolean wasPermutated()

Indicates if the change was only a permutation.

Returns:boolean

true if the change was just a permutation

Exceptions

IllegalStateException:: if this Change instance is in initial state

wasRemoved back to summary

wasRemoved	back to summary
public boolean wasRemoved() Indicates if elements were removed during this change. Note that using set will also produce a change with `wasRemoved()` returning true. See `wasReplaced()`. Returns:boolean `true` if something was removed from the list Exceptions IllegalStateException: if this Change instance is in initial state

public boolean wasRemoved()

Indicates if elements were removed during this change. Note that using set will also produce a change with wasRemoved() returning true. See wasReplaced().

Returns:boolean

true if something was removed from the list

Exceptions

IllegalStateException:: if this Change instance is in initial state

wasReplaced back to summary

wasReplaced	back to summary
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 `Change` class javadoc, will effectively handle the set operation. Returns:boolean same as `wasAdded() && wasRemoved()` Exceptions IllegalStateException: if this Change instance is in initial state

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 Change class javadoc, will effectively handle the set operation.

Returns:boolean

same as wasAdded() && wasRemoved()

Exceptions

IllegalStateException:: if this Change instance is in initial state

wasUpdated back to summary

wasUpdated	back to summary
public boolean wasUpdated() Indicates that the elements between `getFrom()` (inclusive) to `getTo()` exclusive has changed. This is the only optional event type and may not be fired by all ObservableLists. Returns:boolean `true` if the current change is an update change Since JavaFX 2.1

public boolean wasUpdated()

Indicates that the elements between getFrom() (inclusive) to getTo() exclusive has changed. This is the only optional event type and may not be fired by all ObservableLists.

Returns:boolean: true if the current change is an update change
Since: JavaFX 2.1

public Interface ListChangeListener<E>

Nested and Inner Type Summary

Method Summary

Method Detail

public abstract Class ListChangeListener.Change<E>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail