Logo Search packages:      
Sourcecode: libjgoodies-binding-java version File versions

com::jgoodies::binding::list::SelectionInListModel Class Reference

Inheritance diagram for com::jgoodies::binding::list::SelectionInListModel:

com::jgoodies::binding::list::ListModelHolder com::jgoodies::binding::value::ValueModel com::jgoodies::binding::beans::Model com::jgoodies::binding::beans::Observable

List of all members.

Detailed Description

Represents a selection in a ListModel. Provides bound bean properties for the ListModel, the selection, the selection index, and the selection empty state. Selection changes fire an event only if the old and new value are not equal. If you need to compare the identity you can use and observe the selection index instead of the selection or value.

The SelectionInListModel uses three ValueModels to hold the ListModel, the selection and selection index and provides bound bean properties for these models. You can access, observe and replace these ValueModels. This is useful to connect a SelectionInListModel with other ValueModels; for example you can use the SelectionInListModel's selection holder as bean channel for a PresentationModel. See the Binding tutorial classes for examples on how to connect a SelectionInListModel with a PresentationModel.

This class also implements the ListModel interface that allows API users to observe fine grained changes in the structure and contents of the list. Hence instances of this class can be used directly as model of a JList. If you want to use a SelectionInList with a JComboBox or JTable, you can convert the SelectionInList to the associated component model interfaces using the adapter classes com.jgoodies.binding.adapter.ComboBoxAdapter and com.jgoodies.binding.adapter.AbstractTableAdapter respectively. These classes are part of the Binding library too.

Unlike the older SelectionInList, the SelectionInListModel supports only ListModels as content of its ListModel holder. The SelectionInList2 supports Lists as content of its List holder. The SelectionInList2 and SelectionInListModel differ in how precise they can fire events about changes to the content and structure of the underlying List or ListModel content. The SelectionInList2 can only report that the List changes completely; this is done by emitting a PropertyChangeEvent for the list property. Also, a ListDataEvent is fired that reports a complete change. The SelectionInListModel reports the same PropertyChangeEvent. But fine grained changes in the ListModel will be forwarded as fine grained changes in the content, added and removed elements.

If the List or ListModel content doesn't change at all, or if it always changes completely, there's no differences between the SelectionInListModel and the SelectionInList2. But if the list structure or content changes, the ListModel reports more fine grained events to registered ListDataListeners, which in turn allows list views to chooser better user interface gestures: for example, a table with scroll pane may retain the current selection and scroll offset.

An example for the benefit of fine grained ListDataEvents is the asynchronous transport of list elements from a server to a client. Let's say you transport the list elements in portions of 10 elements to improve the application's responsiveness. The user can then work with the SelectionInListModel as soon as the ListModel gets populated. If at a later time more elements are added to the ListModel, the SelectionInListModel can retain the selection index (and selection) and will just report a ListDataEvent about the interval added. JList, JTable and JComboBox will then just add the new elements at the end of the list presentation.

If you want to combine List operations and the ListModel change reports, you may consider using an implementation that combines these two interfaces, for example ArrayListModel or LinkedListModel.

Imporant Note: If you change the ListModel instance, either by calling setListModel(ListModel) or by setting a new value to the underlying list holder, you must ensure that the list holder throws a PropertyChangeEvent whenever the instance changes. This event is used to remove a ListDataListener from the old ListModel instance and is later used to add it to the new ListModel instance. It is easy to violate this constraint, just because Java's standard PropertyChangeSupport helper class that is used by many beans, checks a changed property value via equals, not ==. For example, if you change the SelectionInList's list model from an empty list L1 to another empty list instance L2, the PropertyChangeSupport won't generate a PropertyChangeEvent, and so, the SelectionInList won't know about the change, which may lead to unexpected behavior.

This binding library provides some help for firing PropertyChangeEvents if the old ListModel and new ListModel are equal but not the same. Class com.jgoodies.binding.beans.ExtendedPropertyChangeSupport allows to permanently or individually check the identity (using ==) instead of checking the equity (using equals). Class com.jgoodies.binding.beans.Model uses this extended property change support. And class ValueHolder uses it too and can be configured to always test the identity.

This class provides public convenience methods for firing ListDataEvents, see the methods fireContentsChanged, fireIntervalAdded, and fireIntervalRemoved. These are automatically invoked if the list holder holds a ListModel that fires these events. If on the other hand the underlying List or ListModel does not fire a required ListDataEvent, you can use these methods to notify presentations about a change. It is recommended to avoid sending duplicate ListDataEvents; hence check if the underlying ListModel fires the necessary events or not. Typically an underlying ListModel will fire the add and remove events; but often it'll lack an event if the (seletcted) contents has changed. A convenient way to indicate that change is fireSelectedContentsChanged. See the tutorial's AlbumManagerModel for an example how to use this feature.

Constraints: The ListModel holder holds instances of ListModel, the selection holder values of type Object and the selection index holder of type Integer. The selection index holder must hold non-null index values; however, when firing an index value change event, both the old and new value may be null. If the ListModel changes, the underyling ValueModel must fire a PropertyChangeEvent.

Karsten Lentzsch

See also:










Definition at line 170 of file SelectionInListModel.java.

Public Member Functions

final void addListDataListener (ListDataListener l)
final synchronized void addPropertyChangeListener (String propertyName, PropertyChangeListener listener)
final synchronized void addPropertyChangeListener (PropertyChangeListener listener)
final void addValueChangeListener (PropertyChangeListener l)
final synchronized void addVetoableChangeListener (String propertyName, VetoableChangeListener listener)
final synchronized void addVetoableChangeListener (VetoableChangeListener listener)
void clearSelection ()
final void fireContentsChanged (int index0, int index1)
final void fireIntervalAdded (int index0, int index1)
final void fireIntervalRemoved (int index0, int index1)
void fireSelectedContentsChanged ()
final Object getElementAt (int index)
final ListDataListener[] getListDataListeners ()
final ListModel getListModel ()
final ValueModel getListModelHolder ()
final synchronized
getPropertyChangeListeners (String propertyName)
final synchronized
getPropertyChangeListeners ()
Object getSelection ()
ValueModel getSelectionHolder ()
int getSelectionIndex ()
ValueModel getSelectionIndexHolder ()
final int getSize ()
Object getValue ()
final synchronized
getVetoableChangeListeners (String propertyName)
final synchronized
getVetoableChangeListeners ()
boolean hasSelection ()
final boolean isEmpty ()
boolean isSelectionEmpty ()
void release ()
final void removeListDataListener (ListDataListener l)
final synchronized void removePropertyChangeListener (String propertyName, PropertyChangeListener listener)
final synchronized void removePropertyChangeListener (PropertyChangeListener listener)
final void removeValueChangeListener (PropertyChangeListener l)
final synchronized void removeVetoableChangeListener (String propertyName, VetoableChangeListener listener)
final synchronized void removeVetoableChangeListener (VetoableChangeListener listener)
 SelectionInListModel (ValueModel listModelHolder, ValueModel selectionHolder, ValueModel selectionIndexHolder)
 SelectionInListModel (ValueModel listModelHolder, ValueModel selectionHolder)
 SelectionInListModel (ValueModel listModelHolder)
 SelectionInListModel (ListModel listModel, ValueModel selectionHolder, ValueModel selectionIndexHolder)
 SelectionInListModel (ListModel listModel, ValueModel selectionHolder)
 SelectionInListModel (ListModel listModel)
 SelectionInListModel ()
final void setListModel (ListModel newListModel)
final void setListModelHolder (ValueModel newListModelHolder)
void setSelection (Object newSelection)
void setSelectionHolder (ValueModel newSelectionHolder)
void setSelectionIndex (int newSelectionIndex)
void setSelectionIndexHolder (ValueModel newSelectionIndexHolder)
void setValue (Object newValue)

Static Public Attributes

static final String PROPERTYNAME_LIST_MODEL = "listModel"
static final String PROPERTYNAME_LIST_MODEL_HOLDER = "listModelHolder"
static final String PROPERTYNAME_SELECTION = "selection"
static final String PROPERTYNAME_SELECTION_EMPTY = "selectionEmpty"
static final String PROPERTYNAME_SELECTION_HOLDER = "selectionHolder"
static final String PROPERTYNAME_SELECTION_INDEX = "selectionIndex"
static final String PROPERTYNAME_SELECTION_INDEX_HOLDER = "selectionIndexHolder"
static final String PROPERTYNAME_VALUE = "value"

Protected Member Functions

ListDataListener createListDataChangeHandler ()
final boolean equals (Object o1, Object o2)
final void fireListChanged (int oldLastIndex, int newLastIndex)
final void fireMultiplePropertiesChanged ()
final void firePropertyChange (String propertyName, long oldValue, long newValue)
final void firePropertyChange (String propertyName, int oldValue, int newValue)
final void firePropertyChange (String propertyName, float oldValue, float newValue)
final void firePropertyChange (String propertyName, double oldValue, double newValue)
final void firePropertyChange (String propertyName, boolean oldValue, boolean newValue)
final void firePropertyChange (String propertyName, Object oldValue, Object newValue, boolean checkIdentity)
final void firePropertyChange (String propertyName, Object oldValue, Object newValue)
final void firePropertyChange (PropertyChangeEvent event)
final void fireVetoableChange (String propertyName, long oldValue, long newValue) throws PropertyVetoException
final void fireVetoableChange (String propertyName, float oldValue, float newValue) throws PropertyVetoException
final void fireVetoableChange (String propertyName, int oldValue, int newValue) throws PropertyVetoException
final void fireVetoableChange (String propertyName, double oldValue, double newValue) throws PropertyVetoException
final void fireVetoableChange (String propertyName, boolean oldValue, boolean newValue) throws PropertyVetoException
final void fireVetoableChange (String propertyName, Object oldValue, Object newValue) throws PropertyVetoException
final void fireVetoableChange (PropertyChangeEvent event) throws PropertyVetoException
final int getSize (ListModel aListOrNull)
void updateListModel (ListModel oldListModel, ListModel newListModel)

Protected Attributes

final ListDataListener listDataChangeHandler
ListModel listModel

Package Functions

final void fireValueChange (Object oldValue, Object newValue)

Private Member Functions

Object getSafeElementAt (int index)
int indexOf (ListModel aListModel, Object element)
int indexOf (Object element)
void initializeSelectionIndex ()

Private Attributes

Object oldSelection
int oldSelectionIndex
final PropertyChangeListener selectionChangeHandler
ValueModel selectionHolder
final PropertyChangeListener selectionIndexChangeHandler
ValueModel selectionIndexHolder

Static Private Attributes

static final int NO_SELECTION_INDEX = -1


class  ListDataChangeHandler
class  SelectionChangeHandler
class  SelectionIndexChangeHandler

The documentation for this class was generated from the following file:

Generated by  Doxygen 1.6.0   Back to index