org.jdesktop.swingx.table
Class TableColumnExt

java.lang.Object
  javax.swing.table.TableColumn
      org.jdesktop.swingx.table.TableColumnExt

All Implemented Interfaces:

Serializable, UIDependent

public class TableColumnExt
extends TableColumn
implements UIDependent

TableColumn extension for enhanced view column configuration. The general drift is to strengthen the TableColumn abstraction as the place to configure and dynamically update view column properties, covering a broad range of customization requirements. Using collaborators are expected to listen to property changes and update themselves accordingly.

A functionality enhancement is the notion of column visibility: TableColumnModelExt manages sets of visible/hidden TableColumnExts controlled by the columns' visible property. Typically, users can toggle column visibility at runtime, f.i. through a dedicated control in the upper trailing corner of a JScrollPane.

A prominent group of properties allows fine-grained, per-column control of corresponding Table/-Header features.

• Sorting: sortable controls whether this column should be sortable by user's sort gestures; Comparator can hold a column specific type.
• Editing: editable controls whether cells of this column should be accessible to in-table editing.
• Tooltip: toolTipText holds the column tooltip which is shown when hovering over the column's header.
• Highlighter: highlighters holds the column highlighters; these are applied to the renderer after the table highlighters. Any modification of the list of contained Highlighters (setting them, adding one or removing one) will result in a PropertyChangeEvent being fired for "highlighters". State changes on contained Highlighters will result in a PropertyChangeEvent for "highlighterStateChanged".

Analogous to JComponent, this class supports per-instance "client" properties. They are meant as a small-scale extension mechanism. They are similar to regular bean properties in that registered PropertyChangeListeners are notified about changes. TODO: example?

A TableColumnExt implements UIDependent, that is it takes over responsibility to update LAF dependent properties of contained elements when messaged with updateUI. This implementation updates its Highlighters, Cell-/HeaderRenderer and CellEditor.

TODO: explain prototype (sizing, collaborator-used-by ColumnFactory (?))

See Also:

TableColumnModelExt, ColumnFactory, UIDependent, JComponent.putClientProperty(java.lang.Object, java.lang.Object), Serialized Form

Field Summary

protected Hashtable<Object,Object>	clientProperties storage for client properties.
protected Comparator	comparator per-column comparator
protected CompoundHighlighter	compoundHighlighter The compound highlighter for the column.
protected boolean	editable per-column editable property.
protected Object	prototypeValue prototype property.
protected boolean	sortable per-column sortable property.
protected boolean	visible visible property.

Fields inherited from class javax.swing.table.TableColumn

CELL_RENDERER_PROPERTY, cellEditor, cellRenderer, COLUMN_WIDTH_PROPERTY, HEADER_RENDERER_PROPERTY, HEADER_VALUE_PROPERTY, headerRenderer, headerValue, identifier, isResizable, maxWidth, minWidth, modelIndex, resizedPostingDisableCount, width

Constructor Summary

TableColumnExt()
Creates new table view column with a model index = 0.

TableColumnExt(int modelIndex)
Creates new table view column with the specified model index.

TableColumnExt(int modelIndex, int width)
Creates new table view column with the specified model index and column width.

TableColumnExt(int modelIndex, int width, TableCellRenderer cellRenderer, TableCellEditor cellEditor)
Creates new table view column with the specified model index, column width, cell renderer and cell editor.

TableColumnExt(TableColumnExt columnExt)
Instantiates a new table view column with all properties copied from the given original.

Method Summary

void	addHighlighter(Highlighter highlighter) Appends a Highlighter to the end of the list of used Highlighters.
protected void	copyClientPropertiesFrom(TableColumnExt original) Copies all clientProperties of this TableColumnExt to the target column.
protected void	copyFrom(TableColumnExt original) Copies properties from original.
protected ChangeListener	createHighlighterChangeListener() Creates and returns the ChangeListener observing Highlighters.
protected void	firePropertyChange(String propertyName, Object oldValue, Object newValue) Notifies registered PropertyChangeListeners about property changes.
Object	getClientProperty(Object key) Returns the value of the property with the specified key.
Comparator	getComparator() Returns the comparator to use for the column.
protected CompoundHighlighter	getCompoundHighlighter() Returns the CompoundHighlighter assigned to the table, null if none.
protected ChangeListener	getHighlighterChangeListener() Returns the ChangeListener to use with highlighters.
Highlighter[]	getHighlighters() Returns the Highlighters used by this table.
Object	getPrototypeValue() Returns the prototypeValue property.
boolean	getResizable() Returns true if the user can resize the TableColumn's width, false otherwise.
String	getTitle() Convenience method which returns the headerValue property after converting it to a string.
String	getToolTipText() Returns the text of to display in the column's tool tip.
boolean	isEditable() Returns the per-column editable property.
boolean	isSortable() Returns the sortable property.
boolean	isVisible() Returns the visible property.
void	putClientProperty(Object key, Object value) Sets the client property "key" to value.
void	removeHighlighter(Highlighter highlighter) Removes the given Highlighter.
void	setComparator(Comparator comparator) Sets the comparator to use for this column.
void	setEditable(boolean editable) Sets the editable property.
void	setHighlighters(Highlighter... highlighters) Sets the Highlighters to the table, replacing any old settings.
void	setPrototypeValue(Object value) Sets the prototypeValue property.
void	setSortable(boolean sortable) Sets the sortable property.
void	setTitle(String title) Sets the title of this view column.
void	setToolTipText(String toolTipText) Registers the text to display in the column's tool tip.
void	setVisible(boolean visible) Sets the visible property.
void	updateUI() Update ui of owned ui-dependent parts.

Methods inherited from class javax.swing.table.TableColumn

addPropertyChangeListener, createDefaultHeaderRenderer, disableResizedPosting, enableResizedPosting, getCellEditor, getCellRenderer, getHeaderRenderer, getHeaderValue, getIdentifier, getMaxWidth, getMinWidth, getModelIndex, getPreferredWidth, getPropertyChangeListeners, getWidth, removePropertyChangeListener, setCellEditor, setCellRenderer, setHeaderRenderer, setHeaderValue, setIdentifier, setMaxWidth, setMinWidth, setModelIndex, setPreferredWidth, setResizable, setWidth, sizeWidthToFit

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

visible

protected boolean visible

visible property. Initialized to true.

prototypeValue

protected Object prototypeValue

prototype property.

comparator

protected Comparator comparator

per-column comparator

sortable

protected boolean sortable

per-column sortable property. Initialized to true.

editable

protected boolean editable

per-column editable property. Initialized to true.

clientProperties

protected Hashtable<Object,Object> clientProperties

storage for client properties.

compoundHighlighter

protected CompoundHighlighter compoundHighlighter

The compound highlighter for the column.

Constructor Detail

TableColumnExt

public TableColumnExt()

Creates new table view column with a model index = 0.

TableColumnExt

public TableColumnExt(int modelIndex)

Creates new table view column with the specified model index.

Parameters:

modelIndex - index of table model column to which this view column is bound.

TableColumnExt

public TableColumnExt(int modelIndex,
                      int width)

Creates new table view column with the specified model index and column width.

Parameters:

modelIndex - index of table model column to which this view column is bound.

width - pixel width of view column

TableColumnExt

public TableColumnExt(int modelIndex,
                      int width,
                      TableCellRenderer cellRenderer,
                      TableCellEditor cellEditor)

Creates new table view column with the specified model index, column width, cell renderer and cell editor.

Parameters:

modelIndex - index of table model column to which this view column is bound.

width - pixel width of view column

cellRenderer - the cell renderer which will render all cells in this view column

cellEditor - the cell editor which will edit cells in this view column

TableColumnExt

public TableColumnExt(TableColumnExt columnExt)

Instantiates a new table view column with all properties copied from the given original.

Parameters:

columnExt - the column to copy properties from

See Also:

copyFrom(TableColumnExt)

Method Detail

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:

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:

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...)

getCompoundHighlighter

protected CompoundHighlighter getCompoundHighlighter()

Returns the CompoundHighlighter assigned to the table, null if none. PENDING: open up for subclasses again?.

Returns:

the CompoundHighlighter assigned to the table.

getHighlighterChangeListener

protected ChangeListener getHighlighterChangeListener()

Returns the ChangeListener to use with highlighters. Lazily creates the listener.

Returns:

the ChangeListener for observing changes of highlighters, guaranteed to be not-null

createHighlighterChangeListener

protected ChangeListener createHighlighterChangeListener()

Creates and returns the ChangeListener observing Highlighters.

Here: repaints the table on receiving a stateChanged.

Returns:

the ChangeListener defining the reaction to changes of highlighters.

getResizable

public boolean getResizable()

Returns true if the user can resize the TableColumn's width, false otherwise. This is a usability override: it takes into account the case where it's principally allowed to resize the column but not possible because the column has fixed size.

Overrides:

getResizable in class TableColumn

Returns:

a boolean indicating whether the user can resize this column.

See Also:

TableColumn.setResizable(boolean)

setEditable

public void setEditable(boolean editable)

Sets the editable property. This property allows to mark all cells in a column as read-only, independent of the per-cell editability as returned by the TableModel.isCellEditable. If the cell is read-only in the model layer, this property will have no effect.

Parameters:

editable - boolean indicating whether or not the user may edit cell values in this view column

See Also:

isEditable(), JXTable.isCellEditable(int, int), TableModel.isCellEditable(int, int)

isEditable

public boolean isEditable()

Returns the per-column editable property. The default is true.

Returns:

boolean indicating whether or not the user may edit cell values in this view column

See Also:

setEditable(boolean)

setPrototypeValue

public void setPrototypeValue(Object value)

Sets the prototypeValue property. The value should be of a type which corresponds to the column's class as defined by the table model. If non-null, the JXTable instance will use this property to calculate and set the initial preferredWidth of the column. Note that this initial preferredWidth will be overridden if the user resizes columns directly.

Parameters:

value - Object containing the value of the prototype to be used to calculate the initial preferred width of the column

See Also:

getPrototypeValue(), JXTable.getPreferredScrollableViewportSize()

getPrototypeValue

public Object getPrototypeValue()

Returns the prototypeValue property. The default is null.

Returns:

Object containing the value of the prototype to be used to calculate the initial preferred width of the column

See Also:

setPrototypeValue(java.lang.Object)

setComparator

public void setComparator(Comparator comparator)

Sets the comparator to use for this column. JXTable sorting api respects this property by passing it on to the SortController.

Parameters:

comparator - a custom comparator to use in interactive sorting.

See Also:

getComparator(), SortController, SortKey

getComparator

public Comparator getComparator()

Returns the comparator to use for the column. The default is null.

Returns:

Comparator to use for this column

See Also:

setComparator(java.util.Comparator)

setSortable

public void setSortable(boolean sortable)

Sets the sortable property. JXTable sorting api respects this property by disabling interactive sorting on this column if false.

Parameters:

sortable - boolean indicating whether or not this column can be sorted in the table

See Also:

isSortable()

isSortable

public boolean isSortable()

Returns the sortable property. The default value is true.

Returns:

boolean indicating whether this view column is sortable

See Also:

setSortable(boolean)

setToolTipText

public void setToolTipText(String toolTipText)

Registers the text to display in the column's tool tip. Typically, this is used by JXTableHeader to display when the mouse cursor lingers over the column's header cell.

Parameters:

toolTipText - text to show.

See Also:

setToolTipText(String)

getToolTipText

public String getToolTipText()

Returns the text of to display in the column's tool tip. The default is null.

Returns:

the text of the column ToolTip.

See Also:

setToolTipText(String)

setTitle

public void setTitle(String title)

Sets the title of this view column. This is a convenience wrapper for setHeaderValue.

Parameters:

title - String containing the title of this view column

getTitle

public String getTitle()

Convenience method which returns the headerValue property after converting it to a string.

Returns:

String containing the title of this view column or null if no headerValue is set.

setVisible

public void setVisible(boolean visible)

Sets the visible property. This property controls whether or not this view column is currently visible in the table.

Parameters:

visible - boolean indicating whether or not this view column is visible in the table

See Also:

setVisible(boolean)

isVisible

public boolean isVisible()

Returns the visible property. The default is true.

Returns:

boolean indicating whether or not this view column is visible in the table

See Also:

setVisible(boolean)

putClientProperty

public void putClientProperty(Object key,
                              Object value)

Sets the client property "key" to value. If value is null this method will remove the property. Changes to client properties are reported with PropertyChange events. The name of the property (for the sake of PropertyChange events) is key.toString().

The get/putClientProperty methods provide access to a per-instance hashtable, which is intended for small scale extensions of TableColumn.

Parameters:

key - Object which is used as key to retrieve value

value - Object containing value of client property

Throws:

IllegalArgumentException - if key is null

See Also:

getClientProperty(java.lang.Object), JComponent.putClientProperty(java.lang.Object, java.lang.Object)

getClientProperty

public Object getClientProperty(Object key)

Returns the value of the property with the specified key. Only properties added with putClientProperty will return a non-null value.

Parameters:

key - Object which is used as key to retrieve value

Returns:

Object containing value of client property or null

See Also:

putClientProperty(java.lang.Object, java.lang.Object)

copyFrom

protected void copyFrom(TableColumnExt original)

Copies properties from original. Handles all properties except modelIndex, width, cellRenderer, cellEditor. Called from copy constructor.

Parameters:

original - the tableColumn to copy from

See Also:

TableColumnExt(TableColumnExt)

copyClientPropertiesFrom

protected void copyClientPropertiesFrom(TableColumnExt original)

Copies all clientProperties of this TableColumnExt to the target column.

Parameters:

original - the target column.

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)

Notifies registered PropertyChangeListeners about property changes. This method must be invoked internally whe any of the enhanced properties changed.

Implementation note: needed to replicate super functionality because super's field propertyChangeSupport and method fireXX are both private.

Parameters:

propertyName - name of changed property

oldValue - old value of changed property

newValue - new value of changed property

updateUI

public void updateUI()

Update ui of owned ui-dependent parts. This implementation updates the contained highlighters.

Specified by:

updateUI in interface UIDependent