Module javafx.base
Package javafx.collections

Class 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 a changes done to an Observablelist. The Change may consist of one or more actual changes and must be iterated by 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<tem> 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 done to a list.

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      int getAddedSize​()
      Size of the interval that was added.
      List<E> getAddedSubList​()
      To get a subList view of the list that contains only the elements added, use getAddedSubList() method.
      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 an permutation, it returns an integer array that describes the permutation.
      int getPermutation​(int i)
      By calling these method, you can observe the permutation that happened.
      abstract List<E> getRemoved​()
      An immutable list of removed/replaced elements.
      int getRemovedSize​()
      Size of getRemoved() list.
      abstract int getTo​()
      The end of the change interval.
      abstract boolean next​()
      Go to the next change.
      abstract void reset​()
      Reset 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​()
      Indicates that the elements between getFrom() (inclusive) to getTo() exclusive has changed.

    • Constructor Detail

      • Change

        public Change​(ObservableList<E> list)
        Constructs a new change done to a list.
        Parameters:
        list - that was changed

    • Method Detail

      • next

        public abstract boolean next​()
        Go to the next change. The Change in the initial state is invalid a requires a call to next() before calling other methods. The first next() 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​()
        Reset to the initial stage. After this call, the next() must be called before working with the first change.

      • getList

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

      • getFrom

        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:
        a beginning (inclusive) of an interval related to the change
        Throws:
        IllegalStateException - if this Change is in initial state

      • getTo

        public abstract int getTo​()
        The end of the change interval.
        Returns:
        a end (exclusive) of an interval related to the change.
        Throws:
        IllegalStateException - if this Change is in initial state
        See Also:
        getFrom()

      • getRemoved

        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:
        a list with all the removed elements
        Throws:
        IllegalStateException - if this Change 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 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 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 with wasRemoved() returning true. See wasReplaced().
        Returns:
        true if something was removed from the list
        Throws:
        IllegalStateException - if this Change 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 ListChangeListener.Change above, will effectively handle also set operation.

        Returns:
        same as wasAdded() && wasRemoved()
        Throws:
        IllegalStateException - if this Change is in initial state

      • wasUpdated

        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:
        true if the current change is an update change.
        Since:
        JavaFX 2.1

      • getAddedSubList

        public List<E> getAddedSubList​()
        To get a subList view of the list that contains only the elements added, use getAddedSubList() method. This is actually a shortcut to c.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 is in initial state

      • getRemovedSize

        public int getRemovedSize​()
        Size of getRemoved() list.
        Returns:
        the number of removed items
        Throws:
        IllegalStateException - if this Change is in initial state

      • getAddedSize

        public int getAddedSize​()
        Size of the interval that was added.
        Returns:
        the number of added items
        Throws:
        IllegalStateException - if this Change is in initial state

      • getPermutation

        protected abstract int[] getPermutation​()
        If this change is an 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:
        empty array if this is not permutation or an integer array containing the permutation
        Throws:
        IllegalStateException - if this Change is in initial state

      • getPermutation

        public int getPermutation​(int i)
        By calling these method, you can observe the permutation that happened. 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 - 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 list
        IllegalStateException - if this is not a permutation change