/* * $Id: TableColumnModelExt.java 3000 2008-07-30 16:43:15Z kleopatra $ * * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle, * Santa Clara, California 95054, U.S.A. All rights reserved. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ package org.jdesktop.swingx.table; import java.util.List; import javax.swing.event.TableColumnModelListener; import javax.swing.table.TableColumn; import javax.swing.table.TableColumnModel; import org.jdesktop.swingx.JXTable; import org.jdesktop.swingx.event.TableColumnModelExtListener; /** * An extension of TableColumnModel suitable for use with * JXTable. It extends the notion of columns considered as part * of the view realm to include invisible columns. Conceptually, there are * several sets of "columns": * *
    *
  1. model columns: all columns of a TableModel. They are but * a virtual concept, characterizable f.i. by (model) column index, (model) * column name. *
  2. view columns: all TableColumnExt objects added to the * TableColumnModelExt, each typically created and configured in * relation to a model column. These can be regarded as a kind of subset of the * model columns (not literally, obviously). Each view column belongs to exactly * one of the following (real) subsets: * *
* * This class manages the view columns and automatically takes care of keeping * track of their location in the visible/hidden subset, triggering the * corresponding changes in interested views. Typically, a view column's * visibility can be toggled by user interaction, f.i. via a ColumnControlButton. *

* An example to programmatically hide * the first visible column in the column model: * * 


 * TableColumnExt columnExt = columnModel.getColumnExt(0);
 * if (columnExt != null) {
 *     columnExt.setVisible(false);
 * }
 *
* * Note that it is principally allowed to add standard TableColumns. * Practically, it doesn't make much sense to do so - they will always be * visible. *

* * While individual visible columns can be requested by both column identifier * and column index, the latter is not available for hidden columns. An example * to programmatically guarantee that the view column which corresponds to the * first column in the associated TableModel. * * 


 * List<TableColumn> columns = colModel.getColumns(true);
 * for (TableColumn column : columns) {
 *     if (column.getModelIndex() == 0) {
 *         if (column instanceof TableColumnExt) {
 *             ((TableColumnExt) column).setVisible(false);
 *         }
 *         return;
 *     }
 * }
 *
* * Alternatively, the column could be requested directly by identifier. By * default the column's headerValue is returned as identifier, if none is set. * * 

 * Object identifier = tableModel.getColumnName(0);
 * TableColumnExt columnExt = columnModel.getColumnExt(identifier);
 * if (columnExt != null) {
 *     columnExt.setVisible(false);
 * }
 *
* * Relying on default identifiers is inherently brittle (headerValues might * change f.i. with Locales), so explicit configuration of columns with * identifiers is strongly recommended. A custom ColumnFactory * helps to automate column configuration. *

* * * This class guarantees to notify registered * TableColumnModelListeners of type * TableColumnModelExtListener about propertyChanges fired by * contained TableColumns. * An example of a client which adjusts itself based on * headerValue property of visible columns: * 


 * TableColumnModelExtListener l = new TableColumnModelExtListener() {
 * 
 *     public void columnPropertyChange(PropertyChangeEvent event) {
 *         if ("headerValue".equals(event.getPropertyName())) {
 *             TableColumn column = (TableColumn) event.getSource();
 *             if ((column instanceof TableColumnExt)
 *                     && !((TableColumnExt) column).isVisible()) {
 *                 return;
 *             }
 *             resizeAndRepaint();
 *         }
 *     }
 * 
 *     public void columnAdded(TableColumnModelEvent e) {
 *     }
 * 
 *     public void columnMarginChanged(ChangeEvent e) {
 *     }
 * 
 *     public void columnMoved(TableColumnModelEvent e) {
 *     }
 * 
 *     public void columnRemoved(TableColumnModelEvent e) {
 *     }
 * 
 *     public void columnSelectionChanged(ListSelectionEvent e) {
 *     }
 * 
 * };
 * columnModel.addColumnModelListener(l);
 *
* * * @author Richard Bair * @author Jeanette Winzenburg * * @see DefaultTableColumnModelExt * @see TableColumnExt * @see TableColumnModelExtListener * @see ColumnControlButton * @see JXTable#setColumnControlVisible * @see ColumnFactory * */ public interface TableColumnModelExt extends TableColumnModel { /** * Returns the number of contained columns. The count includes or excludes invisible * columns, depending on whether the includeHidden is true or * false, respectively. If false, this method returns the same count as * getColumnCount(). * * @param includeHidden a boolean to indicate whether invisible columns * should be included * @return the number of contained columns, including or excluding the * invisible as specified. */ public int getColumnCount(boolean includeHidden); /** * Returns a List of contained TableColumns. * Includes or excludes invisible columns, depending on whether the * includeHidden is true or false, respectively. If false, an * Iterator over the List is equivalent to the * Enumeration returned by getColumns(). *

* * NOTE: the order of columns in the List depends on whether or not the * invisible columns are included, in the former case it's the insertion * order in the latter it's the current order of the visible columns. * * @param includeHidden a boolean to indicate whether invisible columns * should be included * @return a List of contained columns. */ public List getColumns(boolean includeHidden); /** * Returns the first TableColumnExt with the given * identifier. The return value is null if there is no contained * column with identifier or if the column with identifier is not * of type TableColumnExt. The returned column * may be visible or hidden. * * @param identifier the object used as column identifier * @return first TableColumnExt with the given identifier or * null if none is found */ public TableColumnExt getColumnExt(Object identifier); /** * Returns the TableColumnExt at view position * columnIndex. The return value is null, if the * column at position columnIndex is not of type * TableColumnExt. * The returned column is visible. * * @param columnIndex the index of the column desired * @return the TableColumnExt object that matches the column * index * @throws ArrayIndexOutOfBoundsException if columnIndex out of allowed * range, that is if * (columnIndex < 0) || (columnIndex >= getColumnCount()). */ public TableColumnExt getColumnExt(int columnIndex); /** * Adds a listener for table column model events. This enhances super's * behaviour in that it guarantees to notify listeners of type * TableColumnModelListenerExt about property changes of contained columns. * * @param x a TableColumnModelListener object */ public void addColumnModelListener(TableColumnModelListener x); }