org.jdesktop.swingx

Class JXList

java.lang.Object

java.awt.Component

java.awt.Container

javax.swing.JComponent

javax.swing.JList

org.jdesktop.swingx.JXList

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, javax.accessibility.Accessible, javax.swing.Scrollable

@JavaBean
public class JXList
extends javax.swing.JList

Enhanced List component with support for general SwingX sorting/filtering, rendering, highlighting, rollover and search functionality. List specific enhancements include ?? PENDING JW ...

Sorting and Filtering

JXList supports sorting and filtering. Changed to use core support. Usage is very similar to J/X/Table. It provides api to apply a specific sort order, to toggle the sort order and to reset a sort. Sort sequence can be configured by setting a custom comparator.

 
 list.setAutoCreateRowSorter(true);
 list.setComparator(myComparator);
 list.setSortOrder(SortOrder.DESCENDING);
 list.toggleSortOder();
 list.resetSortOrder();
 
 

JXList provides api to access items of the underlying model in view coordinates and to convert from/to model coordinates. Note: JXList needs a specific ui-delegate - BasicXListUI and subclasses - which is aware of model vs. view coordiate systems and which controls the synchronization of selection/dataModel and sorter state. SwingX comes with a subclass for Synth.

Rendering and Highlighting

As all SwingX collection views, a JXList is a HighlighterClient (PENDING JW: formally define and implement, like in AbstractTestHighlighter), that is it provides consistent api to add and remove Highlighters which can visually decorate the rendering component.

 
 
 JXList list = new JXList(new Contributors());
 // implement a custom string representation, concated from first-, lastName
 StringValue sv = new StringValue() {
     public String getString(Object value) {
        if (value instanceof Contributor) {
           Contributor contributor = (Contributor) value;
           return contributor.lastName() + ", " + contributor.firstName(); 
        }
        return StringValues.TO_STRING(value);
     }
 };
 list.setCellRenderer(new DefaultListRenderer(sv); 
 // highlight condition: gold merits
 HighlightPredicate predicate = new HighlightPredicate() {
    public boolean isHighlighted(Component renderer,
                     ComponentAdapter adapter) {
       if (!(value instanceof Contributor)) return false;              
       return ((Contributor) value).hasGold();
    }
 };
 // highlight with foreground color 
 list.addHighlighter(new PainterHighlighter(predicate, goldStarPainter);      
 
 
 

Note: to support the highlighting this implementation wraps the ListCellRenderer set by client code with a DelegatingRenderer which applies the Highlighter after delegating the default configuration to the wrappee. As a side-effect, getCellRenderer does return the wrapper instead of the custom renderer. To access the latter, client code must call getWrappedCellRenderer.

Rollover

As all SwingX collection views, a JXList supports per-cell rollover. If enabled, the component fires rollover events on enter/exit of a cell which by default is promoted to the renderer if it implements RolloverRenderer, that is simulates live behaviour. The rollover events can be used by client code as well, f.i. to decorate the rollover row using a Highlighter.

 
 
 JXList list = new JXList();
 list.setRolloverEnabled(true);
 list.setCellRenderer(new DefaultListRenderer());
 list.addHighlighter(new ColorHighlighter(HighlightPredicate.ROLLOVER_ROW, 
      null, Color.RED);      
 
 
 

Location of Trigger for ComponentPopupMenu

JXList allows access to the mouse location that triggered the showing of the componentPopupMenu. This feature allows to implement dynamic cell-context sensitive popupMenus, either in the menu actions or in a PopupMenuListener.

The example below selects the cell that was clicked, event being the PopupMenuEvent received in a PopupMenuListener.

 
 JXList list = (JXList) ((JPopupMenu) e.getSource()).getInvoker();
 Point trigger = list.getPopupTriggerLocation();
 if (trigger != null) {
     int row = list.locationToIndex(trigger);
     list.setSelectedIndex(row);
 }
 
 

Search

As all SwingX collection views, a JXList is searchable. A search action is registered in its ActionMap under the key "find". The default behaviour is to ask the SearchFactory to open a search component on this component. The default keybinding is retrieved from the SearchFactory, typically ctrl-f (or cmd-f for Mac). Client code can register custom actions and/or bindings as appropriate.

JXList provides api to vend a renderer-controlled String representation of cell content. This allows the Searchable and Highlighters to use WYSIWYM (What-You-See-Is-What-You-Match), that is pattern matching against the actual string as seen by the user.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	JXList.DelegatingRenderer A decorator for the original ListCellRenderer.

Nested classes/interfaces inherited from class javax.swing.JList

javax.swing.JList.DropLocation

Nested classes/interfaces inherited from class javax.swing.JComponent

javax.swing.JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Component

java.awt.Component.BaselineResizeBehavior

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	EXECUTE_BUTTON_ACTIONCOMMAND
static java.lang.String	uiClassID UI Class ID

Fields inherited from class javax.swing.JList

HORIZONTAL_WRAP, VERTICAL, VERTICAL_WRAP

Fields inherited from class javax.swing.JComponent

TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
JXList() Constructs a JXList with an empty model and filters disabled.
JXList(boolean autoCreateRowSorter) Constructs a JXList with an empty model and automatic creation of a RowSorter as given.
JXList(javax.swing.ListModel dataModel) Constructs a JXList that displays the elements in the specified, non-null model and automatic creation of a RowSorter disabled.
JXList(javax.swing.ListModel dataModel, boolean autoCreateRowSorter) Constructs a JXList with the specified model and automatic creation of a RowSorter as given.
JXList(java.lang.Object[] listData) Constructs a JXList that displays the elements in the specified array and automatic creation of a RowSorter disabled.
JXList(java.lang.Object[] listData, boolean autoCreateRowSorter) Constructs a JXList that displays the elements in the specified array and automatic creation of a RowSorter as given.
JXList(java.util.Vector<?> listData) Constructs a JXList that displays the elements in the specified Vector and automatic creation of a RowSorter disabled.
JXList(java.util.Vector<?> listData, boolean autoCreateRowSorter) Constructs a JXList that displays the elements in the specified Vector and filtersEnabled property.

Method Summary

Modifier and Type	Method and Description
void	addHighlighter(Highlighter highlighter) Appends a Highlighter to the end of the list of used Highlighters.
int	convertIndexToModel(int viewIndex) Convert row index from view coordinates to model coordinates accounting for the presence of sorters and filters.
int	convertIndexToView(int modelIndex) Convert index from model coordinates to view coordinates accounting for the presence of sorters and filters.
boolean	getAutoCreateRowSorter() Returns true if whenever the model changes, a new RowSorter should be created and installed as the table's sorter; otherwise, returns false.
javax.swing.ListCellRenderer	getCellRenderer()
java.util.Comparator<?>	getComparator()
java.lang.Object	getElementAt(int viewIndex) Returns the element at the given index.
int	getElementCount() Returns the number of elements in this list in view coordinates.
Highlighter[]	getHighlighters() Returns the Highlighters used by this table.
int	getNextMatch(java.lang.String prefix, int startIndex, javax.swing.text.Position.Bias bias)
java.awt.Point	getPopupLocation(java.awt.event.MouseEvent event)
java.awt.Point	getPopupTriggerLocation() Returns the location of the mouseEvent that triggered the showing of the ComponentPopupMenu.
javax.swing.RowFilter<?,?>	getRowFilter() Returns the filter of the sorter, if available and of type SortController.
javax.swing.RowSorter<? extends javax.swing.ListModel>	getRowSorter() Returns the object responsible for sorting.
Searchable	getSearchable() Returns a Searchable for this component, guaranteed to be not null.
java.lang.Object	getSelectedValue() Returns the value for the smallest selected cell index; the selected value when only a single item is selected in the list.
java.lang.Object[]	getSelectedValues() Returns an array of all the selected values, in increasing order based on their indices in the list and taking into account sourting and filtering.
javax.swing.SortOrder	getSortOrder() Returns the SortOrder.
javax.swing.SortOrder[]	getSortOrderCycle() Returns the sortOrder cycle used when toggle sorting this table's columns, guaranteed to be not null.
boolean	getSortsOnUpdates() Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.
java.lang.String	getStringAt(int row) Returns the string representation of the cell value at the given position.
java.lang.String	getUIClassID()
javax.swing.ListCellRenderer	getWrappedCellRenderer() Returns the renderer installed by client code or the default if none has been set.
void	invalidateCellSizeCache() Invalidates cell size caching in the ui delegate.
boolean	isRolloverEnabled() Returns a boolean indicating whether or not rollover support is enabled.
boolean	isSortable() Returns the table's sortable property.
void	removeHighlighter(Highlighter highlighter) Removes the given Highlighter.
void	resetSortOrder() Resets sorting of all columns.
void	setAutoCreateRowSorter(boolean autoCreateRowSorter) Specifies whether a RowSorter should be created for the list whenever its model changes.
void	setCellRenderer(javax.swing.ListCellRenderer renderer)
void	setComparator(java.util.Comparator<?> comparator) Sets the comparator to use for sorting.
void	setHighlighters(Highlighter... highlighters) Sets the Highlighters to the table, replacing any old settings.
void	setModel(javax.swing.ListModel model)
void	setRolloverEnabled(boolean rolloverEnabled) Sets the property to enable/disable rollover support.
<R extends javax.swing.ListModel> void	setRowFilter(javax.swing.RowFilter<? super R,? super java.lang.Integer> filter) Sets the filter to the sorter, if available and of type SortController.
void	setRowSorter(javax.swing.RowSorter<? extends javax.swing.ListModel> sorter) Sets the RowSorter.
void	setSearchable(Searchable searchable) Sets the Searchable for this component.
void	setSelectedValue(java.lang.Object anObject, boolean shouldScroll) Selects the specified object from the list, taking into account sorting and filtering.
void	setSortable(boolean sortable) Sets "sortable" property indicating whether or not this list isSortable.
void	setSortOrder(javax.swing.SortOrder sortOrder) Sorts the list using SortOrder.
void	setSortOrderCycle(javax.swing.SortOrder... cycle) Sets the sortorder cycle used when toggle sorting this table's columns.
void	setSortsOnUpdates(boolean sortsOnUpdates) If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked).
void	toggleSortOrder() Toggles the sort order of the list.
void	updateUI()

Methods inherited from class javax.swing.JList

addListSelectionListener, addSelectionInterval, clearSelection, ensureIndexIsVisible, getAccessibleContext, getAnchorSelectionIndex, getCellBounds, getDragEnabled, getDropLocation, getDropMode, getFirstVisibleIndex, getFixedCellHeight, getFixedCellWidth, getLastVisibleIndex, getLayoutOrientation, getLeadSelectionIndex, getListSelectionListeners, getMaxSelectionIndex, getMinSelectionIndex, getModel, getPreferredScrollableViewportSize, getPrototypeCellValue, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedIndex, getSelectedIndices, getSelectedValuesList, getSelectionBackground, getSelectionForeground, getSelectionMode, getSelectionModel, getToolTipText, getUI, getValueIsAdjusting, getVisibleRowCount, indexToLocation, isSelectedIndex, isSelectionEmpty, locationToIndex, removeListSelectionListener, removeSelectionInterval, setDragEnabled, setDropMode, setFixedCellHeight, setFixedCellWidth, setLayoutOrientation, setListData, setListData, setPrototypeCellValue, setSelectedIndex, setSelectedIndices, setSelectionBackground, setSelectionForeground, setSelectionInterval, setSelectionMode, setSelectionModel, setUI, setValueIsAdjusting, setVisibleRowCount

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

uiClassID

public static final java.lang.String uiClassID

UI Class ID

See Also:

Constant Field Values

EXECUTE_BUTTON_ACTIONCOMMAND

public static final java.lang.String EXECUTE_BUTTON_ACTIONCOMMAND

See Also:

Constant Field Values

Constructor Detail

JXList

public JXList()

Constructs a JXList with an empty model and filters disabled.

JXList

public JXList(javax.swing.ListModel dataModel)

Constructs a JXList that displays the elements in the specified, non-null model and automatic creation of a RowSorter disabled.

Parameters:

dataModel - the data model for this list

Throws:

java.lang.IllegalArgumentException - if dataModel is null

JXList

public JXList(java.lang.Object[] listData)

Constructs a JXList that displays the elements in the specified array and automatic creation of a RowSorter disabled.

Parameters:

listData - the array of Objects to be loaded into the data model

Throws:

java.lang.IllegalArgumentException - if listData is null

JXList

public JXList(java.util.Vector<?> listData)

Constructs a JXList that displays the elements in the specified Vector and automatic creation of a RowSorter disabled.

Parameters:

listData - the Vector to be loaded into the data model

Throws:

java.lang.IllegalArgumentException - if listData is null

JXList

public JXList(boolean autoCreateRowSorter)

Constructs a JXList with an empty model and automatic creation of a RowSorter as given.

Parameters:

autoCreateRowSorter - boolean to determine if a RowSorter should be created automatically.

JXList

public JXList(javax.swing.ListModel dataModel,
              boolean autoCreateRowSorter)

Constructs a JXList with the specified model and automatic creation of a RowSorter as given.

Parameters:

dataModel - the data model for this list

autoCreateRowSorter - boolean to determine if a RowSorter should be created automatically.

Throws:

java.lang.IllegalArgumentException - if dataModel is null

JXList

public JXList(java.lang.Object[] listData,
              boolean autoCreateRowSorter)

Constructs a JXList that displays the elements in the specified array and automatic creation of a RowSorter as given.

Parameters:

listData - the array of Objects to be loaded into the data model

autoCreateRowSorter - boolean to determine if a RowSorter should be created automatically.

Throws:

java.lang.IllegalArgumentException - if listData is null

JXList

public JXList(java.util.Vector<?> listData,
              boolean autoCreateRowSorter)

Constructs a JXList that displays the elements in the specified Vector and filtersEnabled property.

Parameters:

listData - the Vector to be loaded into the data model

autoCreateRowSorter - boolean to determine if a RowSorter should be created automatically.

Throws:

java.lang.IllegalArgumentException - if listData is null

Method Detail

getSearchable

public Searchable getSearchable()

Returns a Searchable for this component, guaranteed to be not null. This implementation lazily creates a ListSearchable if necessary.

Returns:

a not-null Searchable for this list.

See Also:

setSearchable(Searchable), ListSearchable

setSearchable

public void setSearchable(Searchable searchable)

Sets the Searchable for this component. If null, a default Searchable will be created and used.

Parameters:

searchable - the Searchable to use for this component, may be null to indicate using the list's default searchable.

See Also:

getSearchable()

getNextMatch

public int getNextMatch(java.lang.String prefix,
                        int startIndex,
                        javax.swing.text.Position.Bias bias)

Overridden to cope with sorting/filtering, taking over completely.

Overrides:

getNextMatch in class javax.swing.JList

setRolloverEnabled

public void setRolloverEnabled(boolean rolloverEnabled)

Sets the property to enable/disable rollover support. If enabled, the list fires property changes on per-cell mouse rollover state, i.e. when the mouse enters/leaves a list cell.

This can be enabled to show "live" rollover behaviour, f.i. the cursor over a cell rendered by a JXHyperlink.

Default value is disabled.

Parameters:

rolloverEnabled - a boolean indicating whether or not the rollover functionality should be enabled.

See Also:

isRolloverEnabled(), getLinkController(), createRolloverProducer(), RolloverRenderer

isRolloverEnabled

public boolean isRolloverEnabled()

Returns a boolean indicating whether or not rollover support is enabled.

Returns:

a boolean indicating whether or not rollover support is enabled.

See Also:

setRolloverEnabled(boolean)

getPopupLocation

public java.awt.Point getPopupLocation(java.awt.event.MouseEvent event)

Overridden for bookkeeping: the given event location is stored for later access.

Overrides:

getPopupLocation in class javax.swing.JComponent

See Also:

getPopupTriggerLocation()

getPopupTriggerLocation

public java.awt.Point getPopupTriggerLocation()

Returns the location of the mouseEvent that triggered the showing of the ComponentPopupMenu.

Returns:

the location of the mouseEvent that triggered the last showing of the ComponentPopup, or null if it was triggered by keyboard.

getAutoCreateRowSorter

public boolean getAutoCreateRowSorter()

Returns true if whenever the model changes, a new RowSorter should be created and installed as the table's sorter; otherwise, returns false.

Returns:

true if a RowSorter should be created when the model changes

Since:

1.6

setAutoCreateRowSorter

public void setAutoCreateRowSorter(boolean autoCreateRowSorter)

Specifies whether a RowSorter should be created for the list whenever its model changes.

When setAutoCreateRowSorter(true) is invoked, a RowSorter is immediately created and installed on the list. While the autoCreateRowSorter property remains true, every time the model is changed, a new RowSorter is created and set as the list's row sorter.

The default value is false.

Parameters:

autoCreateRowSorter - whether or not a RowSorter should be automatically created

getRowSorter

public javax.swing.RowSorter<? extends javax.swing.ListModel> getRowSorter()

Returns the object responsible for sorting.

Returns:

the object responsible for sorting

Since:

1.6

setRowSorter

public void setRowSorter(javax.swing.RowSorter<? extends javax.swing.ListModel> sorter)

Sets the RowSorter. RowSorter is used to provide sorting and filtering to a JXList.

This method clears the selection and resets any variable row heights.

If the underlying model of the RowSorter differs from that of this JXList undefined behavior will result.

Parameters:

sorter - the RowSorter; null turns sorting off

setSortable

public void setSortable(boolean sortable)

Sets "sortable" property indicating whether or not this list isSortable. Note: as of post-1.0 this property is propagated to the SortController. Whether or not a change triggers a re-sort is up to either the concrete controller implementation (the default doesn't) or client code. This behaviour is different from old SwingX style sorting.

Parameters:

sortable - boolean indicating whether or not this table supports sortable columns

See Also:

TableColumnExt.isSortable()

isSortable

public boolean isSortable()

Returns the table's sortable property.

Returns:

true if the table is sortable.

setSortsOnUpdates

public void setSortsOnUpdates(boolean sortsOnUpdates)

If true, specifies that a sort should happen when the underlying model is updated (rowsUpdated is invoked). For example, if this is true and the user edits an entry the location of that item in the view may change. The default is true.

Parameters:

sortsOnUpdates - whether or not to sort on update events

getSortsOnUpdates

public boolean getSortsOnUpdates()

Returns true if a sort should happen when the underlying model is updated; otherwise, returns false.

Returns:

whether or not to sort when the model is updated

setSortOrderCycle

public void setSortOrderCycle(javax.swing.SortOrder... cycle)

Sets the sortorder cycle used when toggle sorting this table's columns. This property is propagated to the SortController if controlsSorterProperties is true.

Parameters:

cycle - the sequence of zero or more not-null SortOrders to cycle through.

Throws:

java.lang.NullPointerException - if the array or any of its elements are null

getSortOrderCycle

public javax.swing.SortOrder[] getSortOrderCycle()

Returns the sortOrder cycle used when toggle sorting this table's columns, guaranteed to be not null.

Returns:

the sort order cycle used in toggle sort, not null

getComparator

public java.util.Comparator<?> getComparator()

Returns:

the comparator used.

See Also:

setComparator(Comparator)

setComparator

public void setComparator(java.util.Comparator<?> comparator)

Sets the comparator to use for sorting.

Note: as of post-1.0 the property is propagated to the SortController, if available. Whether or not a change triggers a re-sort is up to either the concrete controller implementation (the default doesn't) or client code. This behaviour is different from old SwingX style sorting.

Parameters:

comparator - the comparator to use.

setRowFilter

public <R extends javax.swing.ListModel> void setRowFilter(javax.swing.RowFilter<? super R,? super java.lang.Integer> filter)

Sets the filter to the sorter, if available and of type SortController. Does nothing otherwise.

Parameters:

filter - the filter used to determine what entries should be included

getRowFilter

public javax.swing.RowFilter<?,?> getRowFilter()

Returns the filter of the sorter, if available and of type SortController. Returns null otherwise.

PENDING JW: generics? had to remove return type from getSortController to make this compilable, so probably wrong.

Returns:

the filter used in the sorter.

resetSortOrder

public void resetSortOrder()

Resets sorting of all columns. Delegates to the SortController if available, or does nothing if not.

PENDING JW: method name - consistent in SortController and here.

toggleSortOrder

public void toggleSortOrder()

Toggles the sort order of the list. Delegates to the SortController if available, or does nothing if not.

The exact behaviour is defined by the SortController's toggleSortOrder implementation. Typically a unsorted list is sorted in ascending order, a sorted list's order is reversed.

setSortOrder

public void setSortOrder(javax.swing.SortOrder sortOrder)

Sorts the list using SortOrder. Delegates to the SortController if available, or does nothing if not.

Parameters:

sortOrder - the sort order to use.

getSortOrder

public javax.swing.SortOrder getSortOrder()

Returns the SortOrder. Delegates to the SortController if available, or returns SortOrder.UNSORTED if not.

Returns:

the current SortOrder

getElementAt

public java.lang.Object getElementAt(int viewIndex)

Returns the element at the given index. The index is in view coordinates which might differ from model coordinates if filtering is enabled and filters/sorters are active.

Parameters:

viewIndex - the index in view coordinates

Returns:

the element at the index

Throws:

java.lang.IndexOutOfBoundsException - if viewIndex < 0 or viewIndex >= getElementCount()

getSelectedValue

public java.lang.Object getSelectedValue()

Returns the value for the smallest selected cell index; the selected value when only a single item is selected in the list. When multiple items are selected, it is simply the value for the smallest selected index. Returns null if there is no selection.

This is a convenience method that simply returns the model value for getMinSelectionIndex, taking into account sorting and filtering.

Overrides:

getSelectedValue in class javax.swing.JList

Returns:

the first selected value

See Also:

JList.getMinSelectionIndex(), JList.getModel(), JList.addListSelectionListener(javax.swing.event.ListSelectionListener)

setSelectedValue

public void setSelectedValue(java.lang.Object anObject,
                             boolean shouldScroll)

Selects the specified object from the list, taking into account sorting and filtering.

Overrides:

setSelectedValue in class javax.swing.JList

Parameters:

anObject - the object to select

shouldScroll - true if the list should scroll to display the selected object, if one exists; otherwise false

getSelectedValues

public java.lang.Object[] getSelectedValues()

Returns an array of all the selected values, in increasing order based on their indices in the list and taking into account sourting and filtering.

Overrides:

getSelectedValues in class javax.swing.JList

Returns:

the selected values, or an empty array if nothing is selected

See Also:

JList.isSelectedIndex(int), JList.getModel(), JList.addListSelectionListener(javax.swing.event.ListSelectionListener)

getElementCount

public int getElementCount()

Returns the number of elements in this list in view coordinates. If filters are active this number might be less than the number of elements in the underlying model.

Returns:

number of elements in this list in view coordinates

convertIndexToModel

public int convertIndexToModel(int viewIndex)

Convert row index from view coordinates to model coordinates accounting for the presence of sorters and filters.

Parameters:

viewIndex - index in view coordinates

Returns:

index in model coordinates

Throws:

java.lang.IndexOutOfBoundsException - if viewIndex < 0 or viewIndex >= getElementCount()

convertIndexToView

public int convertIndexToView(int modelIndex)

Convert index from model coordinates to view coordinates accounting for the presence of sorters and filters.

Parameters:

modelIndex - index in model coordinates

Returns:

index in view coordinates if the model index maps to a view coordinate or -1 if not contained in the view.

setModel

public void setModel(javax.swing.ListModel model)

Sets the underlying data model. Note that if isFilterEnabled you must call getWrappedModel to access the model given here. In this case getModel returns a wrapper around the data!

Overrides:

setModel in class javax.swing.JList

Parameters:

model - the data model for this list.

setHighlighters

public void setHighlighters(Highlighter... highlighters)

Sets the Highlighters to the table, replacing any old settings. None of the given Highlighters must be null.

This is a bound property.

Note: as of version #1.257 the null constraint is enforced strictly. To remove all highlighters use this method without param.

Parameters:

highlighters - zero or more not null highlighters to use for renderer decoration.

Throws:

java.lang.NullPointerException - if array is null or array contains null values.

See Also:

getHighlighters(), addHighlighter(Highlighter), removeHighlighter(Highlighter)

getHighlighters

public Highlighter[] getHighlighters()

Returns the Highlighters used by this table. Maybe empty, but guarantees to be never null.

Returns:

the Highlighters used by this table, guaranteed to never null.

See Also:

setHighlighters(Highlighter[])

addHighlighter

public void addHighlighter(Highlighter highlighter)

Appends a Highlighter to the end of the list of used Highlighters. The argument must not be null.

Parameters:

highlighter - the Highlighter to add, must not be null.

Throws:

java.lang.NullPointerException - if Highlighter is null.

See Also:

removeHighlighter(Highlighter), setHighlighters(Highlighter[])

removeHighlighter

public void removeHighlighter(Highlighter highlighter)

Removes the given Highlighter.

Does nothing if the Highlighter is not contained.

Parameters:

highlighter - the Highlighter to remove.

See Also:

addHighlighter(Highlighter), setHighlighters(Highlighter...)

getStringAt

public java.lang.String getStringAt(int row)

Returns the string representation of the cell value at the given position.

Parameters:

row - the row index of the cell in view coordinates

Returns:

the string representation of the cell value as it will appear in the table.

getCellRenderer

public javax.swing.ListCellRenderer getCellRenderer()

Overridden to return the delegating renderer which is wrapped around the original to support highlighting. The returned renderer is of type DelegatingRenderer and guaranteed to not-null

Overrides:

getCellRenderer in class javax.swing.JList

See Also:

setCellRenderer(ListCellRenderer), JXList.DelegatingRenderer

getWrappedCellRenderer

public javax.swing.ListCellRenderer getWrappedCellRenderer()

Returns the renderer installed by client code or the default if none has been set.

Returns:

the wrapped renderer.

See Also:

setCellRenderer(ListCellRenderer)

setCellRenderer

public void setCellRenderer(javax.swing.ListCellRenderer renderer)

Overridden to wrap the given renderer in a DelegatingRenderer to support highlighting.

Note: the wrapping implies that the renderer returned from the getCellRenderer is not the renderer as given here, but the wrapper. To access the original, use getWrappedCellRenderer.

Overrides:

setCellRenderer in class javax.swing.JList

See Also:

getWrappedCellRenderer(), getCellRenderer()

invalidateCellSizeCache

public void invalidateCellSizeCache()

Invalidates cell size caching in the ui delegate. May do nothing if there's no safe (i.e. without reflection) way to message the delegate.

This implementation calls the corresponding method on BasicXListUI if available, does nothing otherwise.

updateUI

public void updateUI()

Overridden to update renderer and Highlighters.

Overrides:

updateUI in class javax.swing.JList

getUIClassID

public java.lang.String getUIClassID()

Overrides:

getUIClassID in class javax.swing.JList