org.jdesktop.swingx.table
Class TableColumnExt

java.lang.Object
  extended by javax.swing.table.TableColumn
      extended by 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.

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, org.jdesktop.swingx.decorator.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