1 /*
   2  * Copyright (c) 1997, 2014, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.swing.table;
  27 
  28 import java.util.Enumeration;
  29 import javax.swing.event.ChangeEvent;
  30 import javax.swing.event.*;
  31 import javax.swing.*;
  32 
  33 
  34 /**
  35  * Defines the requirements for a table column model object suitable for
  36  * use with <code>JTable</code>.
  37  *
  38  * @author Alan Chung
  39  * @author Philip Milne
  40  * @see DefaultTableColumnModel
  41  */
  42 public interface TableColumnModel
  43 {
  44 //
  45 // Modifying the model
  46 //
  47 
  48     /**
  49      *  Appends <code>aColumn</code> to the end of the
  50      *  <code>tableColumns</code> array.
  51      *  This method posts a <code>columnAdded</code>
  52      *  event to its listeners.
  53      *
  54      * @param   aColumn         the <code>TableColumn</code> to be added
  55      * @see     #removeColumn
  56      */
  57     public void addColumn(TableColumn aColumn);
  58 
  59     /**
  60      *  Deletes the <code>TableColumn</code> <code>column</code> from the
  61      *  <code>tableColumns</code> array.  This method will do nothing if
  62      *  <code>column</code> is not in the table's column list.
  63      *  This method posts a <code>columnRemoved</code>
  64      *  event to its listeners.
  65      *
  66      * @param   column          the <code>TableColumn</code> to be removed
  67      * @see     #addColumn
  68      */
  69     public void removeColumn(TableColumn column);
  70 
  71     /**
  72      * Moves the column and its header at <code>columnIndex</code> to
  73      * <code>newIndex</code>.  The old column at <code>columnIndex</code>
  74      * will now be found at <code>newIndex</code>.  The column that used
  75      * to be at <code>newIndex</code> is shifted left or right
  76      * to make room.  This will not move any columns if
  77      * <code>columnIndex</code> equals <code>newIndex</code>.  This method
  78      * posts a <code>columnMoved</code> event to its listeners.
  79      *
  80      * @param   columnIndex                     the index of column to be moved
  81      * @param   newIndex                        index of the column's new location
  82      * @exception IllegalArgumentException      if <code>columnIndex</code> or
  83      *                                          <code>newIndex</code>
  84      *                                          are not in the valid range
  85      */
  86     public void moveColumn(int columnIndex, int newIndex);
  87 
  88     /**
  89      * Sets the <code>TableColumn</code>'s column margin to
  90      * <code>newMargin</code>.  This method posts
  91      * a <code>columnMarginChanged</code> event to its listeners.
  92      *
  93      * @param   newMargin       the width, in pixels, of the new column margins
  94      * @see     #getColumnMargin
  95      */
  96     public void setColumnMargin(int newMargin);
  97 
  98 //
  99 // Querying the model
 100 //
 101 
 102     /**
 103      * Returns the number of columns in the model.
 104      * @return the number of columns in the model
 105      */
 106     public int getColumnCount();
 107 
 108     /**
 109      * Returns an <code>Enumeration</code> of all the columns in the model.
 110      * @return an <code>Enumeration</code> of all the columns in the model
 111      */
 112     public Enumeration<TableColumn> getColumns();
 113 
 114     /**
 115      * Returns the index of the first column in the table
 116      * whose identifier is equal to <code>identifier</code>,
 117      * when compared using <code>equals</code>.
 118      *
 119      * @param           columnIdentifier        the identifier object
 120      * @return          the index of the first table column
 121      *                  whose identifier is equal to <code>identifier</code>
 122      * @exception IllegalArgumentException      if <code>identifier</code>
 123      *                          is <code>null</code>, or no
 124      *                          <code>TableColumn</code> has this
 125      *                          <code>identifier</code>
 126      * @see             #getColumn
 127      */
 128     public int getColumnIndex(Object columnIdentifier);
 129 
 130     /**
 131      * Returns the <code>TableColumn</code> object for the column at
 132      * <code>columnIndex</code>.
 133      *
 134      * @param   columnIndex     the index of the desired column
 135      * @return  the <code>TableColumn</code> object for
 136      *                          the column at <code>columnIndex</code>
 137      */
 138     public TableColumn getColumn(int columnIndex);
 139 
 140     /**
 141      * Returns the width between the cells in each column.
 142      * @return the margin, in pixels, between the cells
 143      */
 144     public int getColumnMargin();
 145 
 146     /**
 147      * Returns the index of the column that lies on the
 148      * horizontal point, <code>xPosition</code>;
 149      * or -1 if it lies outside the any of the column's bounds.
 150      *
 151      * In keeping with Swing's separable model architecture, a
 152      * TableColumnModel does not know how the table columns actually appear on
 153      * screen.  The visual presentation of the columns is the responsibility
 154      * of the view/controller object using this model (typically JTable).  The
 155      * view/controller need not display the columns sequentially from left to
 156      * right.  For example, columns could be displayed from right to left to
 157      * accommodate a locale preference or some columns might be hidden at the
 158      * request of the user.  Because the model does not know how the columns
 159      * are laid out on screen, the given <code>xPosition</code> should not be
 160      * considered to be a coordinate in 2D graphics space.  Instead, it should
 161      * be considered to be a width from the start of the first column in the
 162      * model.  If the column index for a given X coordinate in 2D space is
 163      * required, <code>JTable.columnAtPoint</code> can be used instead.
 164      *
 165      * @param xPosition  width from the start of the first column in
 166      * the model.
 167      *
 168      * @return  the index of the column; or -1 if no column is found
 169      * @see javax.swing.JTable#columnAtPoint
 170      */
 171     public int getColumnIndexAtX(int xPosition);
 172 
 173     /**
 174      * Returns the total width of all the columns.
 175      * @return the total computed width of all columns
 176      */
 177     public int getTotalColumnWidth();
 178 
 179 //
 180 // Selection
 181 //
 182 
 183     /**
 184      * Sets whether the columns in this model may be selected.
 185      * @param flag   true if columns may be selected; otherwise false
 186      * @see #getColumnSelectionAllowed
 187      */
 188     public void setColumnSelectionAllowed(boolean flag);
 189 
 190     /**
 191      * Returns true if columns may be selected.
 192      * @return true if columns may be selected
 193      * @see #setColumnSelectionAllowed
 194      */
 195     public boolean getColumnSelectionAllowed();
 196 
 197     /**
 198      * Returns an array of indicies of all selected columns.
 199      * @return an array of integers containing the indicies of all
 200      *          selected columns; or an empty array if nothing is selected
 201      */
 202     public int[] getSelectedColumns();
 203 
 204     /**
 205      * Returns the number of selected columns.
 206      *
 207      * @return the number of selected columns; or 0 if no columns are selected
 208      */
 209     public int getSelectedColumnCount();
 210 
 211     /**
 212      * Sets the selection model.
 213      *
 214      * @param newModel  a <code>ListSelectionModel</code> object
 215      * @see #getSelectionModel
 216      */
 217     public void setSelectionModel(ListSelectionModel newModel);
 218 
 219     /**
 220      * Returns the current selection model.
 221      *
 222      * @return a <code>ListSelectionModel</code> object
 223      * @see #setSelectionModel
 224      */
 225     public ListSelectionModel getSelectionModel();
 226 
 227 //
 228 // Listener
 229 //
 230 
 231     /**
 232      * Adds a listener for table column model events.
 233      *
 234      * @param x  a <code>TableColumnModelListener</code> object
 235      */
 236     public void addColumnModelListener(TableColumnModelListener x);
 237 
 238     /**
 239      * Removes a listener for table column model events.
 240      *
 241      * @param x  a <code>TableColumnModelListener</code> object
 242      */
 243     public void removeColumnModelListener(TableColumnModelListener x);
 244 }