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

com::jgoodies::binding::list::SelectionInList Class Reference

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

com::jgoodies::binding::list::ListHolder 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 List. Provides bound bean properties for the list, 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 SelectionInList uses three ValueModels to hold the list, 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 SelectionInList with other ValueModels; for example you can use the SelectionInList's selection holder as bean channel for a PresentationModel. See the Binding tutorial classes for examples on how to connect a SelectionInList 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 SelectionInList supports only Lists as content of its List holder. The SelectionInListModel supports ListModels as content of its ListModel holder. The SelectionInList 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 SelectionInList 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 SelectionInList. 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.

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 inherits 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 list holder holds instances of List, 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.

Author:
Karsten Lentzsch
Version:
Revision
1.20

See also:
SelectionInListModel

ValueModel

List

ListModel

com.jgoodies.binding.adapter.ComboBoxAdapter

com.jgoodies.binding.adapter.AbstractTableAdapter

com.jgoodies.binding.beans.ExtendedPropertyChangeSupport

com.jgoodies.binding.beans.Model

com.jgoodies.binding.value.ValueHolder

Since:
1.5

Definition at line 156 of file SelectionInList.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 List getList ()
final ListDataListener[] getListDataListeners ()
final ValueModel getListHolder ()
final synchronized
PropertyChangeListener[] 
getPropertyChangeListeners (String propertyName)
final synchronized
PropertyChangeListener[] 
getPropertyChangeListeners ()
Object getSelection ()
ValueModel getSelectionHolder ()
int getSelectionIndex ()
ValueModel getSelectionIndexHolder ()
final int getSize ()
Object getValue ()
final synchronized
VetoableChangeListener[] 
getVetoableChangeListeners (String propertyName)
final synchronized
VetoableChangeListener[] 
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)
 SelectionInList (ValueModel listHolder, ValueModel selectionHolder, ValueModel selectionIndexHolder)
 SelectionInList (ValueModel listHolder, ValueModel selectionHolder)
 SelectionInList (ValueModel listHolder)
 SelectionInList (List list, ValueModel selectionHolder, ValueModel selectionIndexHolder)
 SelectionInList (List list, ValueModel selectionHolder)
 SelectionInList (List list)
 SelectionInList (Object[] listItems, ValueModel selectionHolder, ValueModel selectionIndexHolder)
 SelectionInList (Object[] listItems, ValueModel selectionHolder)
 SelectionInList (Object[] listItems)
 SelectionInList ()
final void setList (List newList)
final void setListHolder (ValueModel newListHolder)
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 = "list"
static final String PROPERTYNAME_LIST_HOLDER = "listHolder"
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

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 (List aListOrNull)
void updateList (List oldList, List newList)

Protected Attributes

List list

Package Functions

final void fireValueChange (Object oldValue, Object newValue)

Private Member Functions

Object getSafeElementAt (int index)
int indexOf (List aList, 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

Classes

class  SelectionChangeHandler
class  SelectionIndexChangeHandler

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

Generated by  Doxygen 1.6.0   Back to index