org.jdesktop.swingx.table
Class ColumnControlButton

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by javax.swing.AbstractButton
                  extended by javax.swing.JButton
                      extended by org.jdesktop.swingx.table.ColumnControlButton
All Implemented Interfaces:
ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, SwingConstants

public class ColumnControlButton
extends JButton

A component to allow interactive customization of JXTable's columns. It's main purpose is to allow toggling of table columns' visibility. Additionally, arbitrary configuration actions can be exposed.

This component is installed in the JXTable's trailing corner, if enabled:


 table.setColumnControlVisible(true);
 
From the perspective of a JXTable, the component's behaviour is opaque. Typically, the button's action is to popup a component for user interaction.

This class is responsible for handling/providing/updating the lists of actions and to keep all action's state in synch with Table-/Column state. The visible behaviour of the popup is delegated to a ColumnControlPopup.

See Also:
TableColumnExt, TableColumnModelExt, JXTable.setColumnControl(javax.swing.JComponent), Serialized Form

Nested Class Summary
 class ColumnControlButton.ColumnVisibilityAction
          A specialized Action which takes care of keeping in synch with TableColumn state.
 class ColumnControlButton.DefaultColumnControlPopup
          A default implementation of ColumnControlPopup.
 
Nested classes/interfaces inherited from class javax.swing.JButton
JButton.AccessibleJButton
 
Nested classes/interfaces inherited from class javax.swing.AbstractButton
AbstractButton.AccessibleAbstractButton, AbstractButton.ButtonChangeListener
 
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static String COLUMN_CONTROL_BUTTON_ICON_KEY
          the key for looking up the control's icon in the UIManager.
static String COLUMN_CONTROL_BUTTON_MARGIN_KEY
          the key for looking up the control's margin in the UIManager.
static String COLUMN_CONTROL_MARKER
          Marker to auto-recognize actions which should be added to the popup.
protected  ColumnControlPopup popup
          exposed for testing.
 
Fields inherited from class javax.swing.AbstractButton
actionListener, BORDER_PAINTED_CHANGED_PROPERTY, changeEvent, changeListener, CONTENT_AREA_FILLED_CHANGED_PROPERTY, DISABLED_ICON_CHANGED_PROPERTY, DISABLED_SELECTED_ICON_CHANGED_PROPERTY, FOCUS_PAINTED_CHANGED_PROPERTY, HORIZONTAL_ALIGNMENT_CHANGED_PROPERTY, HORIZONTAL_TEXT_POSITION_CHANGED_PROPERTY, ICON_CHANGED_PROPERTY, itemListener, MARGIN_CHANGED_PROPERTY, MNEMONIC_CHANGED_PROPERTY, model, MODEL_CHANGED_PROPERTY, PRESSED_ICON_CHANGED_PROPERTY, ROLLOVER_ENABLED_CHANGED_PROPERTY, ROLLOVER_ICON_CHANGED_PROPERTY, ROLLOVER_SELECTED_ICON_CHANGED_PROPERTY, SELECTED_ICON_CHANGED_PROPERTY, TEXT_CHANGED_PROPERTY, VERTICAL_ALIGNMENT_CHANGED_PROPERTY, VERTICAL_TEXT_POSITION_CHANGED_PROPERTY
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, 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 javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
ColumnControlButton(JXTable table)
          Creates a column control button for the table.
ColumnControlButton(JXTable table, Icon icon)
          Creates a column control button for the table.
 
Method Summary
protected  void addAdditionalActionItems()
          Adds additional actions to the popup.
protected  void addVisibilityActionItems()
          Adds visibility actions into the popup view.
 void applyComponentOrientation(ComponentOrientation o)
          Sets the ComponentOrientation property of this container and all components contained within it.
protected  boolean canControl()
          Method to check if we can control column visibility POST: if true we can be sure to have an extended TableColumnModel
protected  void clearAll()
          removes all components from the popup, making sure to release all columnVisibility actions.
protected  void clearColumnVisibilityActions()
          Releases actions and clears list of actions.
protected  ColumnControlPopup createColumnControlPopup()
          Factory method to return a ColumnControlPopup.
protected  TableColumnModelListener createColumnModelListener()
          Creates the listener to columnModel.
protected  ColumnControlButton.ColumnVisibilityAction createColumnVisibilityAction(TableColumn column)
          Creates and returns a ColumnVisibilityAction for the given TableColumn.
protected  PropertyChangeListener createTablePropertyChangeListener()
          Creates the listener to table's property changes.
protected  void createVisibilityActions()
          Creates and adds a ColumnVisiblityAction for every column that should be togglable via the column control.
protected  List<Action> getAdditionalActions()
          creates and returns a list of additional Actions to add to the popup.
protected  List getColumnControlActionKeys()
          Looks up and returns action keys to access actions in the table's actionMap which should be included into the popup.
protected  ColumnControlPopup getColumnControlPopup()
          Returns to popup component for user interaction.
protected  TableColumnModelListener getColumnModelListener()
          Returns the listener to table's column model.
protected  List<ColumnControlButton.ColumnVisibilityAction> getColumnVisibilityActions()
          Lazyly creates and returns the List of visibility actions.
protected  PropertyChangeListener getTablePropertyChangeListener()
          Returns the listener to table's property changes.
protected  boolean isColumnControlActionKey(Object actionKey)
          Here: true if a String key starts with #COLUMN_CONTROL_MARKER.
protected  void populatePopup()
          Populates the popup from scratch.
 void togglePopup()
          Toggles the popup component's visibility.
protected  void updateActionUI()
          Updates the action properties provided by the LAF.
protected  void updateButtonUI()
          Updates this button's properties provided by the LAF.
protected  void updateFromColumnModelChange(TableColumnModel oldModel)
          Adjusts internal state after table's column model property has changed.
protected  void updateFromTableEnabledChanged()
          Synchs this button's enabled with table's enabled.
 void updateUI()
          Resets the UI property to a value from the current look and feel.
 
Methods inherited from class javax.swing.JButton
getAccessibleContext, getUIClassID, isDefaultButton, isDefaultCapable, paramString, removeNotify, setDefaultCapable
 
Methods inherited from class javax.swing.AbstractButton
actionPropertyChanged, addActionListener, addChangeListener, addImpl, addItemListener, checkHorizontalKey, checkVerticalKey, configurePropertiesFromAction, createActionListener, createActionPropertyChangeListener, createChangeListener, createItemListener, doClick, doClick, fireActionPerformed, fireItemStateChanged, fireStateChanged, getAction, getActionCommand, getActionListeners, getChangeListeners, getDisabledIcon, getDisabledSelectedIcon, getDisplayedMnemonicIndex, getHideActionText, getHorizontalAlignment, getHorizontalTextPosition, getIcon, getIconTextGap, getItemListeners, getLabel, getMargin, getMnemonic, getModel, getMultiClickThreshhold, getPressedIcon, getRolloverIcon, getRolloverSelectedIcon, getSelectedIcon, getSelectedObjects, getText, getUI, getVerticalAlignment, getVerticalTextPosition, imageUpdate, init, isBorderPainted, isContentAreaFilled, isFocusPainted, isRolloverEnabled, isSelected, paintBorder, removeActionListener, removeChangeListener, removeItemListener, setAction, setActionCommand, setBorderPainted, setContentAreaFilled, setDisabledIcon, setDisabledSelectedIcon, setDisplayedMnemonicIndex, setEnabled, setFocusPainted, setHideActionText, setHorizontalAlignment, setHorizontalTextPosition, setIcon, setIconTextGap, setLabel, setLayout, setMargin, setMnemonic, setMnemonic, setModel, setMultiClickThreshhold, setPressedIcon, setRolloverEnabled, setRolloverIcon, setRolloverSelectedIcon, setSelected, setSelectedIcon, setText, setUI, setVerticalAlignment, setVerticalTextPosition
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addPropertyChangeListener, addPropertyChangeListener, 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, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, 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, hide, 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, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, 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, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

COLUMN_CONTROL_MARKER

public static final String COLUMN_CONTROL_MARKER
Marker to auto-recognize actions which should be added to the popup.

See Also:
Constant Field Values

COLUMN_CONTROL_BUTTON_ICON_KEY

public static final String COLUMN_CONTROL_BUTTON_ICON_KEY
the key for looking up the control's icon in the UIManager. Typically, it's LAF dependent.

See Also:
Constant Field Values

COLUMN_CONTROL_BUTTON_MARGIN_KEY

public static final String COLUMN_CONTROL_BUTTON_MARGIN_KEY
the key for looking up the control's margin in the UIManager. Typically, it's LAF dependent.

See Also:
Constant Field Values

popup

protected ColumnControlPopup popup
exposed for testing.

Constructor Detail

ColumnControlButton

public ColumnControlButton(JXTable table)
Creates a column control button for the table. Uses the default icon as provided by the addon.

Parameters:
table - the JXTable controlled by this component

ColumnControlButton

public ColumnControlButton(JXTable table,
                           Icon icon)
Creates a column control button for the table. The button uses the given icon and has no text.

Parameters:
table - the JXTable controlled by this component
icon - the Icon to show
Method Detail

updateUI

public void updateUI()
Description copied from class: javax.swing.JButton
Resets the UI property to a value from the current look and feel.

Overrides:
updateUI in class JButton
See Also:
JComponent.updateUI()

updateButtonUI

protected void updateButtonUI()
Updates this button's properties provided by the LAF. Here: overwrites the action's small_icon with the icon from the ui if the current icon is null or a UIResource.


updateActionUI

protected void updateActionUI()
Updates the action properties provided by the LAF. Here: overwrites the action's small_icon with the icon from the ui if the current icon is null or a UIResource.


togglePopup

public void togglePopup()
Toggles the popup component's visibility. This method is called by this control's default action.

Here: delegates to getControlPopup().


applyComponentOrientation

public void applyComponentOrientation(ComponentOrientation o)
Description copied from class: java.awt.Container
Sets the ComponentOrientation property of this container and all components contained within it.

Overrides:
applyComponentOrientation in class Container
Parameters:
o - the new component orientation of this container and the components contained within it.
See Also:
Component.setComponentOrientation(java.awt.ComponentOrientation), Component.getComponentOrientation()

getColumnControlPopup

protected ColumnControlPopup getColumnControlPopup()
Returns to popup component for user interaction. Lazily creates the component if necessary.

Returns:
the ColumnControlPopup for showing the items, guaranteed to be not null.
See Also:
createColumnControlPopup()

createColumnControlPopup

protected ColumnControlPopup createColumnControlPopup()
Factory method to return a ColumnControlPopup. Subclasses can override to hook custom implementations.

Returns:
the ColumnControlPopup used.

updateFromColumnModelChange

protected void updateFromColumnModelChange(TableColumnModel oldModel)
Adjusts internal state after table's column model property has changed. Handles cleanup of listeners to the old/new columnModel (Note, that it listens to the column model only if it can control column visibility). Updates content of popup.

Parameters:
oldModel - the old TableColumnModel we had been listening to.

updateFromTableEnabledChanged

protected void updateFromTableEnabledChanged()
Synchs this button's enabled with table's enabled.


canControl

protected boolean canControl()
Method to check if we can control column visibility POST: if true we can be sure to have an extended TableColumnModel

Returns:
boolean to indicate if controlling the visibility state is possible.

populatePopup

protected void populatePopup()
Populates the popup from scratch. If applicable, creates and adds column visibility actions. Always adds additional actions.


clearAll

protected void clearAll()
removes all components from the popup, making sure to release all columnVisibility actions.


clearColumnVisibilityActions

protected void clearColumnVisibilityActions()
Releases actions and clears list of actions.


addVisibilityActionItems

protected void addVisibilityActionItems()
Adds visibility actions into the popup view. Here: delegates the list of actions to the DefaultColumnControlPopup.

PRE: columnVisibilityActions populated before calling this.


addAdditionalActionItems

protected void addAdditionalActionItems()
Adds additional actions to the popup. Here: delegates the list of actions as returned by #getAdditionalActions() to the DefaultColumnControlPopup. Does nothing if #getColumnActions() is empty.


createVisibilityActions

protected void createVisibilityActions()
Creates and adds a ColumnVisiblityAction for every column that should be togglable via the column control.

Here: all table columns contained in the TableColumnModel - visible and invisible columns - to createColumnVisibilityAction and adds all not null return values.

PRE: canControl()

See Also:
createColumnVisibilityAction(javax.swing.table.TableColumn)

createColumnVisibilityAction

protected ColumnControlButton.ColumnVisibilityAction createColumnVisibilityAction(TableColumn column)
Creates and returns a ColumnVisibilityAction for the given TableColumn. The return value might be null, f.i. if the column should not be allowed to be toggled.

Parameters:
column - the TableColumn to use for the action
Returns:
a ColumnVisibilityAction to use for the given column, may be null.

getColumnVisibilityActions

protected List<ColumnControlButton.ColumnVisibilityAction> getColumnVisibilityActions()
Lazyly creates and returns the List of visibility actions.

Returns:
the list of visibility actions, guaranteed to be != null.

getAdditionalActions

protected List<Action> getAdditionalActions()
creates and returns a list of additional Actions to add to the popup. Here: the actions are looked up in the table's actionMap according to the keys as returned from #getColumnControlActionKeys();

Returns:
a list containing all additional actions to include into the popup.

getColumnControlActionKeys

protected List getColumnControlActionKeys()
Looks up and returns action keys to access actions in the table's actionMap which should be included into the popup. Here: all keys with isColumnControlActionKey(key). The list is sorted by those keys.

Returns:
the action keys of table's actionMap entries whose action should be included into the popup.

isColumnControlActionKey

protected boolean isColumnControlActionKey(Object actionKey)
Here: true if a String key starts with #COLUMN_CONTROL_MARKER.

Parameters:
actionKey - a key in the table's actionMap.
Returns:
a boolean to indicate whether the given actionKey maps to an action which should be included into the popup.

getTablePropertyChangeListener

protected PropertyChangeListener getTablePropertyChangeListener()
Returns the listener to table's property changes. The listener is lazily created if necessary.

Returns:
the PropertyChangeListener for use with the table, guaranteed to be not null.

createTablePropertyChangeListener

protected PropertyChangeListener createTablePropertyChangeListener()
Creates the listener to table's property changes. Subclasses are free to roll their own.

Implementation note: this listener reacts to table's enabled and columnModel properties and calls the respective updateFromXX methodes.

Returns:
the PropertyChangeListener for use with the table.

getColumnModelListener

protected TableColumnModelListener getColumnModelListener()
Returns the listener to table's column model. The listener is lazily created if necessary.

Returns:
the TableColumnModelListener for use with the table's column model, guaranteed to be not null.

createColumnModelListener

protected TableColumnModelListener createColumnModelListener()
Creates the listener to columnModel. Subclasses are free to roll their own.

Implementation note: this listener reacts to "real" columnRemoved/-Added by populating the popups content from scratch.

Returns:
the TableColumnModelListener for use with the table's columnModel.