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. Since the SelectionInList is a ValueModel, it is often used as bean channel. See the Binding tutorial classes for examples on how to connect a SelectionInList with a PresentationModel.
This class also implements the {@link ListModel} interface that allowsAPI 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 {@link DisplayProject.binding.adapter.ComboBoxAdapter}and {@link DisplayProject.binding.adapter.AbstractTableAdapter} respectively.These classes are part of the Binding library too.
The SelectionInList supports two list types as content of its list holder: List and ListModel. The two modes differ in how precise this class can fire events about changes to the content and structure of the list. If you use a List, this class 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. In contrast, if you use a ListModel it will report the same PropertyChangeEvent. But fine grained changes in the list model will be fired by this class to notify observes about changes in the content, added and removed elements.
If the list content doesn't change at all, or if it always changes completely, you can work well with both List content and ListModel content. 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 using a ListModel in a SelectionInList 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 select and work with the SelectionInList as soon as the ListModel gets populated. If at a later time more elements are added to the list model, the SelectionInList 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 {@link ArrayListModel} or {@link 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 {@link DisplayProject.binding.beans.ExtendedPropertyChangeSupport} allows to permanently or individually check the identity (using ==) instead of checking the equity (using #equals). Class {@link DisplayProject.binding.beans.Model} uses this extended property change support. And class {@link ValueHolder} uses it too and can be configured to always test the identity.
Since version 1.0.2 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 list holder holds instances of {@link List}or {@link 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.
@author Karsten Lentzsch @version $Revision: 1.35 $ @see ValueModel @see List @see ListModel @see DisplayProject.binding.adapter.ComboBoxAdapter @see DisplayProject.binding.adapter.AbstractTableAdapter @see DisplayProject.binding.beans.ExtendedPropertyChangeSupport @see DisplayProject.binding.beans.Model @see DisplayProject.binding.value.ValueHolder Copyright (c) 2002-2005 JGoodies Karsten Lentzsch. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name of JGoodies Karsten Lentzsch nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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. Since the SelectionInList is a ValueModel, it is often used as bean channel. See the Binding tutorial classes for examples on how to connect a SelectionInList with a PresentationModel.
This class also implements the {@link ListModel} interface that allowsAPI 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 {@link net.helipilot50.stocktrade.displayproject.binding.adapter.ComboBoxAdapter}and {@link net.helipilot50.stocktrade.displayproject.binding.adapter.AbstractTableAdapter} respectively.These classes are part of the Binding library too.
The SelectionInList supports two list types as content of its list holder: List and ListModel. The two modes differ in how precise this class can fire events about changes to the content and structure of the list. If you use a List, this class 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. In contrast, if you use a ListModel it will report the same PropertyChangeEvent. But fine grained changes in the list model will be fired by this class to notify observes about changes in the content, added and removed elements.
If the list content doesn't change at all, or if it always changes completely, you can work well with both List content and ListModel content. 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 using a ListModel in a SelectionInList 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 select and work with the SelectionInList as soon as the ListModel gets populated. If at a later time more elements are added to the list model, the SelectionInList 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 {@link ArrayListModel} or {@link 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 {@link net.helipilot50.stocktrade.displayproject.binding.beans.ExtendedPropertyChangeSupport} allows to permanently or individually check the identity (using ==) instead of checking the equity (using #equals). Class {@link net.helipilot50.stocktrade.displayproject.binding.beans.Model} uses this extended property change support. And class {@link ValueHolder} uses it too and can be configured to always test the identity.
Since version 1.0.2 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 list holder holds instances of {@link List}or {@link 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.
@author Karsten Lentzsch @version $Revision: 1.35 $ @see ValueModel @see List @see ListModel @see net.helipilot50.stocktrade.displayproject.binding.adapter.ComboBoxAdapter @see net.helipilot50.stocktrade.displayproject.binding.adapter.AbstractTableAdapter @see net.helipilot50.stocktrade.displayproject.binding.beans.ExtendedPropertyChangeSupport @see net.helipilot50.stocktrade.displayproject.binding.beans.Model @see net.helipilot50.stocktrade.displayproject.binding.value.ValueHolder Copyright (c) 2002-2005 JGoodies Karsten Lentzsch. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name of JGoodies Karsten Lentzsch nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
| |