MultiSelectionInList (CUF2 Parent Project 2.0.8 API)

java.lang.Object
- net.sf.cuf.model.AbstractValueModel<List<? extends T>>
- - net.sf.cuf.model.MultiSelectionInList<T>

All Implemented Interfaces:

EventListener, ChangeListener, ExternalUpdate, ValueModel<List<? extends T>>
```
public class MultiSelectionInList<T>
extends AbstractValueModel<List<? extends T>>
implements ChangeListener
```
A MultiSelectionInList holds both a list and a selection. The selection is both available as an index set as well as a list of the selected values from the original list.
The major differences to SelectionInList are:
- We may have multiple selected entries.
- We don't support adding or removing elements from the base list by providing specific methods. That is only possible by directly manipulating the list and then calling ExternalUpdate.signalExternalUpdate().
- Our behavior is undefined if the base list contains the same reference more than once. (Maybe we can improve at a later point in time.)
- This implementation still needs some work and lots of testing.
The MultiSelectionInList is based on a ValueModel that has a List as value. The value of the MultiSelectionInList is the same list as the base list.
Values can be selected and deselected using various methods in this class which result in a change to the selection index set and the selection values list. Alternatively the selected index set or the selected values list can be modified to change the selection.
When changes in the selected values list are registered (via our special list implementation), the content of the selected value list is checked as follows:
- Entries that are in our base list are kept and marked as selected.
- For entries that are not in our base list an exception will be thrown.
- All entries that are in our base list but not in our selected list are marked not selected.
- The entries of the selected value list are sorted to be in the same order as the in the original list.
The selected index set is updated synchronously to the selected values set.
By default, the comparisons are made by reference, not by equals. That means that if you have a list of primitive objects, e.g. Integer, you must use the same instance of an integer in both the base list and in the selected values list, not simply any equal instance.
If you do want a comparison by equals or by any other Comparator, you can explicitly set one using #setSelectionComparator
When changes in the selected index set are registered, the content of the selected value list is updated to reflect the changes. If an index outside the allowed range is added, an exception will be thrown.
When changes in the base model are registered, we try to keep the selection as similar as possible by value, i.e. we try to keep the same selected objects in the list, even if we have to change our index values.
Both the selected index set and the selected values list may be modified in content but not replaced in their value model.

Field Summary

Fields
Modifier and Type	Field and Description
`static Comparator<Object>`	`EQUALS_COMPARATOR` compares two objects and returns 0 when they are `Object.equals(Object)`.
`static Comparator<Object>`	`IDENTITY_COMPARATOR` compares two objects and returns 0 when they are the same reference.

Constructor Summary

Constructors
Constructor and Description
`MultiSelectionInList(List<? extends T> pList)` Creates a new MultiSelectionInList with the given list as our base.
`MultiSelectionInList(ValueModel<List<? extends T>> pListHolder)` Creates a new MultiSelectionInList with the given value model as our base.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearSelection()` clears the selection and makes the appropriate notifications.
`int`	`determineIndexInBaseList(Object pElement)` Checks if the same element is in the base list (by using `mSelectionComparator`).
`void`	`dispose()` Cleanup all resources: disconnect from any input sources (like other ValueModel's ...), and remove all listeners.
`protected List<? extends T>`	`getBaseList()`
`ValueModel<? extends SortedSet<Integer>>`	`getSelectedIndexSetValueModel()`
`ValueModel<? extends List<T>>`	`getSelectedValuesHolder()` Returns the value model that contains the `List` with the selected values from the base list.
`List<? extends T>`	`getValue()` Get the current list.
`boolean`	`isEditable()` delegates to our base model Returns true if a setValue() is possible, and doesn't throw an UnsupportedOperationException,
`void`	`selectAll()` selects all entries and makes the appropriate notifications.
`void`	`setSelectedElements(Collection<? extends T> pSelectedValues)` Sets the selection to the given set of values.
`void`	`setSelectedIndexes(Collection<Integer> pSelectedIndexes)` Sets the selection to the given set of indexes.
`void`	`setSelectionComparator(Comparator<Object> pSelectionComparator)` sets the selection comparator to use when we try to match a selected value to a value in the base list.
`void`	`setValue(List<? extends T> pValue, boolean pIsSetForced)` Set a new value, this will fire a ChangeEvent if the new value is different from the old value.
`void`	`stateChanged(ChangeEvent pEvent)` Invoked when the value model holding our list changed its state.

Methods inherited from class net.sf.cuf.model.AbstractValueModel
addChangeListener, booleanValue, checkDisposed, doubleValue, fireStateChanged, floatValue, getDependents, getName, intValue, isDisposed, isInSetValue, isSetForced, longValue, onChangeSend, removeChangeListener, retractInterestsFor, setInSetValue, setName, setObjectValue, setValue, setValue, setValue, setValue, setValue, setValue, setValueForced, signalExternalUpdate, stringValue

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - EQUALS_COMPARATOR
```
public static final Comparator<Object> EQUALS_COMPARATOR
```
    compares two objects and returns 0 when they are Object.equals(Object). Otherwise -1 is returned (in violation of the Comparator.compare(Object, Object) specification, but it doesn't matter since we use it only as ==0). null values are only equal to other null values.
  - IDENTITY_COMPARATOR
```
public static final Comparator<Object> IDENTITY_COMPARATOR
```
    compares two objects and returns 0 when they are the same reference. Otherwise -1 is returned (in violation of the Comparator.compare(Object, Object) specification, but it doesn't matter since we use it only as ==0).
- Constructor Detail
  - MultiSelectionInList
```
public MultiSelectionInList(ValueModel<List<? extends T>> pListHolder)
```
    Creates a new MultiSelectionInList with the given value model as our base. Initially, no entry is selected.
    
    Parameters:
    pListHolder - the value model, must contain a List as value
    
    Throws:
    
    IllegalArgumentException - if pListHolder is null or pListHolder.getValue() is not null and not a List
  - MultiSelectionInList
```
public MultiSelectionInList(List<? extends T> pList)
```
    Creates a new MultiSelectionInList with the given list as our base. Initially, no entry is selected.
    
    Parameters:
    pList - the list, may be null
- Method Detail
  - setSelectionComparator
```
public void setSelectionComparator(Comparator<Object> pSelectionComparator)
```
    sets the selection comparator to use when we try to match a selected value to a value in the base list. If the parameter is null, we will use the identity comparison (IDENTITY_COMPARATOR). If you want a comparison by Object.equals(Object), you can specify the EQUALS_COMPARATOR.
    
    Parameters:
    pSelectionComparator - the comparator to use when matching selection values to base list values, may be null
  - isEditable
```
public boolean isEditable()
```
    delegates to our base model Returns true if a setValue() is possible, and doesn't throw an UnsupportedOperationException,
    
    Specified by:
    
    isEditable in interface ValueModel<List<? extends T>>
    
    Returns:
    true if setValue() can be called
  - dispose
```
public void dispose()
```
    Cleanup all resources: disconnect from any input sources (like other ValueModel's ...), and remove all listeners.
    
    Specified by:
    
    dispose in interface ValueModel<List<? extends T>>
    
    Overrides:
    
    dispose in class AbstractValueModel<List<? extends T>>
  - setValue
```
public void setValue(List<? extends T> pValue,
            boolean pIsSetForced)
```
    Set a new value, this will fire a ChangeEvent if the new value is different from the old value. The new value must be a List or null. We set the list to the value holder.
    
    Specified by:
    
    setValue in interface ValueModel<List<? extends T>>
    
    Parameters:
    pValue - the new list (null is o.k.)
    pIsSetForced - true if a forced setValue should be done
    
    Throws:
    
    IllegalArgumentException - if pValue is neither a List nor null
  - getValue
```
public List<? extends T> getValue()
```
    Get the current list.
    
    Specified by:
    
    getValue in interface ValueModel<List<? extends T>>
    
    Returns:
    null or our list
  - stateChanged
```
public void stateChanged(ChangeEvent pEvent)
```
    Invoked when the value model holding our list changed its state.
    
    Specified by:
    
    stateChanged in interface ChangeListener
    
    Parameters:
    pEvent - a ChangeEvent object, not used
  - getBaseList
```
protected List<? extends T> getBaseList()
```
    Returns:
    the List value of the mListHolder or null if the value is null
    
    Throws:
    
    IllegalArgumentException - if the value is not null and not a List
  - getSelectedIndexSetValueModel
```
public ValueModel<? extends SortedSet<Integer>> getSelectedIndexSetValueModel()
```
    Returns:
    the value model that contains the Set with the Integers that correspond to the selected indexes in the base list, sorted by index. The ValueModel itself is not modifiable, but the Set is actively working with the MultiSelectionInList so that a notification of changes is not necessary. Note that the following restrictions apply:
    
    The set contains only Integers that are a valid index to the base list.
    Attempts to add other objects or invalid indexes will result in an exception.
  - getSelectedValuesHolder
```
public ValueModel<? extends List<T>> getSelectedValuesHolder()
```
    Returns the value model that contains the List with the selected values from the base list. The ValueModel itself is not modifiable, but the List is actively working with the MultiSelectionInList so that a notification of changes is not necessary. Note that the following restrictions apply:
    - The List in the value model cannot be replaced by a different instance.
    - The List contains the references to the selected elements from the base list.
    - Attempts to add objects that are not in the base list (i.e. not found by the given mSelectionComparator) will result in an exception.
    - When adding an object that is not the same but still equals using mSelectionComparator, we internally replace the reference in this list by the matching one from the base list.
    - The List does not support adding or positioning elements arbitrarily. Attempts to do so will be rerouted to reflect the correct order of selected elements as defined by the base list.
    - The List does not (yet) support all operations.
    Returns:
    the value model that contains the List with the selected values from the base list.
  - determineIndexInBaseList
```
public int determineIndexInBaseList(Object pElement)
```
    Checks if the same element is in the base list (by using mSelectionComparator).
    
    Parameters:
    pElement - the element to check
    
    Returns:
    the index at which the element can be found in the base list or -1 if it is not in the base list
  - selectAll
```
public void selectAll()
```
    selects all entries and makes the appropriate notifications.
  - clearSelection
```
public void clearSelection()
```
    clears the selection and makes the appropriate notifications.
  - setSelectedIndexes
```
public void setSelectedIndexes(Collection<Integer> pSelectedIndexes)
```
    Sets the selection to the given set of indexes.
    
    Parameters:
    pSelectedIndexes - a collection of Integers which must be valid indexes for the base list
  - setSelectedElements
```
public void setSelectedElements(Collection<? extends T> pSelectedValues)
```
    Sets the selection to the given set of values.
    
    Parameters:
    pSelectedValues - a collection of Objects, must have the same references as the base list or be equal using the mSelectionComparator.

Class MultiSelectionInList<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class net.sf.cuf.model.AbstractValueModel

Methods inherited from class java.lang.Object

Field Detail

EQUALS_COMPARATOR

IDENTITY_COMPARATOR

Constructor Detail

MultiSelectionInList

MultiSelectionInList

Method Detail

setSelectionComparator

isEditable

dispose

setValue

getValue

stateChanged

getBaseList

getSelectedIndexSetValueModel

getSelectedValuesHolder

determineIndexInBaseList

selectAll

clearSelection

setSelectedIndexes

setSelectedElements