libjava/classpath/javax/swing/table/TableColumn.java

   1 /* TableColumn.java --
   2    Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.swing.table;
  40
  41 import java.awt.Component;
  42 import java.awt.Dimension;
  43 import java.beans.PropertyChangeEvent;
  44 import java.beans.PropertyChangeListener;
  45 import java.io.Serializable;
  46
  47 import javax.swing.event.SwingPropertyChangeSupport;
  48
  49 /**
  50  * Represents the attributes of a column in a table, including the column index,
  51  * width, minimum width, preferred width and maximum width.
  52  *
  53  * @author      Andrew Selkirk
  54  */
  55 public class TableColumn
  56   implements Serializable
  57 {
  58   static final long serialVersionUID = -6113660025878112608L;
  59
  60   /**
  61    * The name for the <code>columnWidth</code> property (this field is
  62    * obsolete and no longer used).  Note also that the typo in the value
  63    * string is deliberate, to match the specification.
  64    */
  65   public static final String COLUMN_WIDTH_PROPERTY = "columWidth";
  66
  67   /**
  68    * The name for the <code>headerValue</code> property.
  69    */
  70   public static final String HEADER_VALUE_PROPERTY = "headerValue";
  71
  72   /**
  73    * The name for the <code>headerRenderer</code> property.
  74    */
  75   public static final String HEADER_RENDERER_PROPERTY = "headerRenderer";
  76
  77   /**
  78    * The name for the <code>cellRenderer</code> property.
  79    */
  80   public static final String CELL_RENDERER_PROPERTY = "cellRenderer";
  81
  82   /**
  83    * The index of the corresponding column in the table model.
  84    */
  85   protected int modelIndex;
  86
  87   /**
  88    * The identifier for the column.
  89    */
  90   protected Object identifier;
  91
  92   /**
  93    * The current width for the column.
  94    */
  95   protected int width;
  96
  97   /**
  98    * The minimum width for the column.
  99    */
 100   protected int minWidth = 15;
 101
 102   /**
 103    * The preferred width for the column.
 104    */
 105   private int preferredWidth;
 106
 107   /**
 108    * The maximum width for the column.
 109    */
 110   protected int maxWidth = Integer.MAX_VALUE;
 111
 112   /**
 113    * The renderer for the column header.
 114    */
 115   protected TableCellRenderer headerRenderer;
 116
 117   /**
 118    * The value for the column header.
 119    */
 120   protected Object headerValue;
 121
 122   /**
 123    * The renderer for the regular cells in this column.
 124    */
 125   protected TableCellRenderer cellRenderer;
 126
 127   /**
 128    * An editor for the regular cells in this column.
 129    */
 130   protected TableCellEditor cellEditor;
 131
 132   /**
 133    * A flag that determines whether or not the column is resizable (the default
 134    * is <code>true</code>).
 135    */
 136   protected boolean isResizable = true;
 137
 138   /**
 139    * resizedPostingDisableCount
 140    *
 141    * @deprecated 1.3
 142    */
 143   protected transient int resizedPostingDisableCount;
 144
 145   /**
 146    * A storage and notification mechanism for property change listeners.
 147    */
 148   private SwingPropertyChangeSupport changeSupport =
 149     new SwingPropertyChangeSupport(this);
 150
 151   /**
 152    * Creates a new <code>TableColumn</code> that maps to column 0 in the
 153    * related table model.  The default width is <code>75</code> units.
 154    */
 155   public TableColumn()
 156   {
 157     this(0, 75, null, null);
 158   }
 159
 160   /**
 161    * Creates a new <code>TableColumn</code> that maps to the specified column
 162    * in the related table model.  The default width is <code>75</code> units.
 163    *
 164    * @param modelIndex the index of the column in the model
 165    */
 166   public TableColumn(int modelIndex)
 167   {
 168     this(modelIndex, 75, null, null);
 169   }
 170
 171   /**
 172    * Creates a new <code>TableColumn</code> that maps to the specified column
 173    * in the related table model, and has the specified <code>width</code>.
 174    *
 175    * @param modelIndex the index of the column in the model
 176    * @param width the width
 177    */
 178   public TableColumn(int modelIndex, int width)
 179   {
 180     this(modelIndex, width, null, null);
 181   }
 182
 183   /**
 184    * Creates a new <code>TableColumn</code> that maps to the specified column
 185    * in the related table model, and has the specified <code>width</code>,
 186    * <code>cellRenderer</code> and <code>cellEditor</code>.
 187    *
 188    * @param modelIndex the index of the column in the model
 189    * @param width the width
 190    * @param cellRenderer the cell renderer (<code>null</code> permitted).
 191    * @param cellEditor the cell editor (<code>null</code> permitted).
 192    */
 193   public TableColumn(int modelIndex, int width,
 194                      TableCellRenderer cellRenderer, TableCellEditor cellEditor)
 195   {
 196     this.modelIndex = modelIndex;
 197     this.width = width;
 198     this.preferredWidth = width;
 199     this.cellRenderer = cellRenderer;
 200     this.cellEditor = cellEditor;
 201     this.headerValue = null;
 202     this.identifier = null;
 203   }
 204
 205   /**
 206    * Sets the index of the column in the related {@link TableModel} that this
 207    * <code>TableColumn</code> maps to, and sends a {@link PropertyChangeEvent}
 208    * (with the property name 'modelIndex') to all registered listeners.
 209    *
 210    * @param modelIndex the column index in the model.
 211    *
 212    * @see #getModelIndex()
 213    */
 214   public void setModelIndex(int modelIndex)
 215   {
 216     if (this.modelIndex != modelIndex)
 217       {
 218         int oldValue = this.modelIndex;
 219         this.modelIndex = modelIndex;
 220         changeSupport.firePropertyChange("modelIndex", oldValue, modelIndex);
 221       }
 222   }
 223
 224   /**
 225    * Returns the index of the column in the related {@link TableModel} that
 226    * this <code>TableColumn</code> maps to.
 227    *
 228    * @return the model index.
 229    *
 230    * @see #setModelIndex(int)
 231    */
 232   public int getModelIndex()
 233   {
 234     return modelIndex;
 235   }
 236
 237   /**
 238    * Sets the identifier for the column and sends a {@link PropertyChangeEvent}
 239    * (with the property name 'identifier') to all registered listeners.
 240    *
 241    * @param identifier the identifier (<code>null</code> permitted).
 242    *
 243    * @see #getIdentifier()
 244    */
 245   public void setIdentifier(Object identifier)
 246   {
 247     if (this.identifier != identifier)
 248       {
 249         Object oldValue = this.identifier;
 250         this.identifier = identifier;
 251         changeSupport.firePropertyChange("identifier", oldValue, identifier);
 252       }
 253   }
 254
 255   /**
 256    * Returns the identifier for the column, or {@link #getHeaderValue()} if the
 257    * identifier is <code>null</code>.
 258    *
 259    * @return The identifier (or {@link #getHeaderValue()} if the identifier is
 260    *         <code>null</code>).
 261    */
 262   public Object getIdentifier()
 263   {
 264     if (identifier == null)
 265       return getHeaderValue();
 266     return identifier;
 267   }
 268
 269   /**
 270    * Sets the header value and sends a {@link PropertyChangeEvent} (with the
 271    * property name {@link #HEADER_VALUE_PROPERTY}) to all registered listeners.
 272    *
 273    * @param headerValue the value of the header (<code>null</code> permitted).
 274    *
 275    * @see #getHeaderValue()
 276    */
 277   public void setHeaderValue(Object headerValue)
 278   {
 279     if (this.headerValue == headerValue)
 280       return;
 281
 282     Object oldValue = this.headerValue;
 283     this.headerValue = headerValue;
 284     changeSupport.firePropertyChange(HEADER_VALUE_PROPERTY, oldValue,
 285                                      headerValue);
 286   }
 287
 288   /**
 289    * Returns the header value.
 290    *
 291    * @return the value of the header.
 292    *
 293    * @see #getHeaderValue()
 294    */
 295   public Object getHeaderValue()
 296   {
 297     return headerValue;
 298   }
 299
 300   /**
 301    * Sets the renderer for the column header and sends a
 302    * {@link PropertyChangeEvent} (with the property name
 303    * {@link #HEADER_RENDERER_PROPERTY}) to all registered listeners.
 304    *
 305    * @param renderer the header renderer (<code>null</code> permitted).
 306    *
 307    * @see #getHeaderRenderer()
 308    */
 309   public void setHeaderRenderer(TableCellRenderer renderer)
 310   {
 311     if (headerRenderer == renderer)
 312       return;
 313
 314     TableCellRenderer oldRenderer = headerRenderer;
 315     headerRenderer = renderer;
 316     changeSupport.firePropertyChange(HEADER_RENDERER_PROPERTY, oldRenderer,
 317                                      headerRenderer);
 318   }
 319
 320   /**
 321    * Returns the renderer for the column header.
 322    *
 323    * @return The renderer for the column header (possibly <code>null</code>).
 324    *
 325    * @see #setHeaderRenderer(TableCellRenderer)
 326    */
 327   public TableCellRenderer getHeaderRenderer()
 328   {
 329     return headerRenderer;
 330   }
 331
 332   /**
 333    * Sets the renderer for cells in this column and sends a
 334    * {@link PropertyChangeEvent} (with the property name
 335    * {@link #CELL_RENDERER_PROPERTY}) to all registered listeners.
 336    *
 337    * @param renderer the cell renderer (<code>null</code> permitted).
 338    *
 339    * @see #getCellRenderer()
 340    */
 341   public void setCellRenderer(TableCellRenderer renderer)
 342   {
 343     if (cellRenderer == renderer)
 344       return;
 345
 346     TableCellRenderer oldRenderer = cellRenderer;
 347     cellRenderer = renderer;
 348     changeSupport.firePropertyChange(CELL_RENDERER_PROPERTY, oldRenderer,
 349                                      cellRenderer);
 350   }
 351
 352   /**
 353    * Returns the renderer for the table cells in this column.
 354    *
 355    * @return The cell renderer (possibly <code>null</code>).
 356    *
 357    * @see #setCellRenderer(TableCellRenderer)
 358    */
 359   public TableCellRenderer getCellRenderer()
 360   {
 361     return cellRenderer;
 362   }
 363
 364   /**
 365    * Sets the cell editor for the column and sends a {@link PropertyChangeEvent}
 366    * (with the property name 'cellEditor') to all registered listeners.
 367    *
 368    * @param cellEditor the cell editor (<code>null</code> permitted).
 369    *
 370    * @see #getCellEditor()
 371    */
 372   public void setCellEditor(TableCellEditor cellEditor)
 373   {
 374     if (this.cellEditor != cellEditor)
 375       {
 376         TableCellEditor oldValue = this.cellEditor;
 377         this.cellEditor = cellEditor;
 378         changeSupport.firePropertyChange("cellEditor", oldValue, cellEditor);
 379       }
 380   }
 381
 382   /**
 383    * Returns the cell editor for the column (the default value is
 384    * <code>null</code>).
 385    *
 386    * @return The cell editor (possibly <code>null</code>).
 387    *
 388    * @see #setCellEditor(TableCellEditor)
 389    */
 390   public TableCellEditor getCellEditor()
 391   {
 392     return cellEditor;
 393   }
 394
 395   /**
 396    * Sets the width for the column and sends a {@link PropertyChangeEvent}
 397    * (with the property name 'width') to all registered listeners.  If the new
 398    * width falls outside the range getMinWidth() to getMaxWidth() it is
 399    * adjusted to the appropriate boundary value.
 400    *
 401    * @param newWidth the width.
 402    *
 403    * @see #getWidth()
 404    */
 405   public void setWidth(int newWidth)
 406   {
 407     int oldWidth = width;
 408
 409     if (newWidth < minWidth)
 410       width = minWidth;
 411     else if (newWidth > maxWidth)
 412       width = maxWidth;
 413     else
 414       width = newWidth;
 415
 416     if (width == oldWidth)
 417       return;
 418
 419     // We do have a constant field COLUMN_WIDTH_PROPERTY,
 420     // however, tests show that the actual fired property name is 'width'
 421     // and even Sun's API docs say that this constant field is obsolete and
 422     // not used.
 423     changeSupport.firePropertyChange("width", oldWidth, width);
 424   }
 425
 426   /**
 427    * Returns the width for the column (the default value is <code>75</code>).
 428    *
 429    * @return The width.
 430    *
 431    * @see #setWidth(int)
 432    */
 433   public int getWidth()
 434   {
 435     return width;
 436   }
 437
 438   /**
 439    * Sets the preferred width for the column and sends a
 440    * {@link PropertyChangeEvent} (with the property name 'preferredWidth') to
 441    * all registered listeners.  If necessary, the supplied value will be
 442    * adjusted to fit in the range {@link #getMinWidth()} to
 443    * {@link #getMaxWidth()}.
 444    *
 445    * @param preferredWidth  the preferred width.
 446    *
 447    * @see #getPreferredWidth()
 448    */
 449   public void setPreferredWidth(int preferredWidth)
 450   {
 451     int oldPrefWidth = this.preferredWidth;
 452
 453     if (preferredWidth < minWidth)
 454       this.preferredWidth = minWidth;
 455     else if (preferredWidth > maxWidth)
 456       this.preferredWidth = maxWidth;
 457     else
 458       this.preferredWidth = preferredWidth;
 459
 460     changeSupport.firePropertyChange("preferredWidth", oldPrefWidth,
 461                                      this.preferredWidth);
 462   }
 463
 464   /**
 465    * Returns the preferred width for the column (the default value is
 466    * <code>75</code>).
 467    *
 468    * @return The preferred width.
 469    *
 470    * @see #setPreferredWidth(int)
 471    */
 472   public int getPreferredWidth()
 473   {
 474     return preferredWidth;
 475   }
 476
 477   /**
 478    * Sets the minimum width for the column and sends a
 479    * {@link PropertyChangeEvent} (with the property name 'minWidth') to all
 480    * registered listeners.  If the current <code>width</code> and/or
 481    * <code>preferredWidth</code> are less than the new minimum width, they are
 482    * adjusted accordingly.
 483    *
 484    * @param minWidth  the minimum width (negative values are treated as 0).
 485    *
 486    * @see #getMinWidth()
 487    */
 488   public void setMinWidth(int minWidth)
 489   {
 490     if (minWidth < 0)
 491       minWidth = 0;
 492     if (this.minWidth != minWidth)
 493       {
 494         if (width < minWidth)
 495           setWidth(minWidth);
 496         if (preferredWidth < minWidth)
 497           setPreferredWidth(minWidth);
 498         int oldValue = this.minWidth;
 499         this.minWidth = minWidth;
 500         changeSupport.firePropertyChange("minWidth", oldValue, minWidth);
 501       }
 502   }
 503
 504   /**
 505    * Returns the <code>TableColumn</code>'s minimum width (the default value
 506    * is <code>15</code>).
 507    *
 508    * @return The minimum width.
 509    *
 510    * @see #setMinWidth(int)
 511    */
 512   public int getMinWidth()
 513   {
 514     return minWidth;
 515   }
 516
 517   /**
 518    * Sets the maximum width for the column and sends a
 519    * {@link PropertyChangeEvent} (with the property name 'maxWidth') to all
 520    * registered listeners.  If the current <code>width</code> and/or
 521    * <code>preferredWidth</code> are greater than the new maximum width, they
 522    * are adjusted accordingly.
 523    *
 524    * @param maxWidth the maximum width.
 525    *
 526    * @see #getMaxWidth()
 527    */
 528   public void setMaxWidth(int maxWidth)
 529   {
 530     if (this.maxWidth != maxWidth)
 531       {
 532         if (width > maxWidth)
 533           setWidth(maxWidth);
 534         if (preferredWidth > maxWidth)
 535           setPreferredWidth(maxWidth);
 536         int oldValue = this.maxWidth;
 537         this.maxWidth = maxWidth;
 538         changeSupport.firePropertyChange("maxWidth", oldValue, maxWidth);
 539        }
 540   }
 541
 542   /**
 543    * Returns the maximum width for the column (the default value is
 544    * {@link Integer#MAX_VALUE}).
 545    *
 546    * @return The maximum width for the column.
 547    *
 548    * @see #setMaxWidth(int)
 549    */
 550   public int getMaxWidth()
 551   {
 552     return maxWidth;
 553   }
 554
 555   /**
 556    * Sets the flag that controls whether or not the column is resizable, and
 557    * sends a {@link PropertyChangeEvent} (with the property name 'isResizable')
 558    * to all registered listeners.
 559    *
 560    * @param isResizable <code>true</code> if this column is resizable,
 561    * <code>false</code> otherwise.
 562    *
 563    * @see #getResizable()
 564    */
 565   public void setResizable(boolean isResizable)
 566   {
 567     if (this.isResizable != isResizable)
 568       {
 569         this.isResizable = isResizable;
 570         changeSupport.firePropertyChange("isResizable", !this.isResizable,
 571             isResizable);
 572       }
 573   }
 574
 575   /**
 576    * Returns the flag that controls whether or not the column is resizable.
 577    *
 578    * @return <code>true</code> if this column is resizable,
 579    * <code>false</code> otherwise.
 580    *
 581    * @see #setResizable(boolean)
 582    */
 583   public boolean getResizable()
 584   {
 585     return isResizable;
 586   }
 587
 588   /**
 589    * Sets the minimum, maximum, preferred and current width to match the
 590    * minimum, maximum and preferred width of the header renderer component.
 591    * If there is no header renderer component, this method does nothing.
 592    */
 593   public void sizeWidthToFit()
 594   {
 595     if (headerRenderer == null)
 596       return;
 597     Component c = headerRenderer.getTableCellRendererComponent(null,
 598         getHeaderValue(), false, false, 0, 0);
 599     Dimension min = c.getMinimumSize();
 600     Dimension max = c.getMaximumSize();
 601     Dimension pref = c.getPreferredSize();
 602     setMinWidth(min.width);
 603     setMaxWidth(max.width);
 604     setPreferredWidth(pref.width);
 605     setWidth(pref.width);
 606   }
 607
 608   /**
 609    * This method is empty, unused and deprecated.
 610    * @deprecated 1.3
 611    */
 612   public void disableResizedPosting()
 613   {
 614     // Does nothing
 615   }
 616
 617   /**
 618    * This method is empty, unused and deprecated.
 619    * @deprecated 1.3
 620    */
 621   public void enableResizedPosting()
 622   {
 623     // Does nothing
 624   }
 625
 626   /**
 627    * Adds a listener so that it receives {@link PropertyChangeEvent}
 628    * notifications from this column.  The properties defined by the column are:
 629    * <ul>
 630    * <li><code>width</code> - see {@link #setWidth(int)};</li>
 631    * <li><code>preferredWidth</code> - see {@link #setPreferredWidth(int)};</li>
 632    * <li><code>minWidth</code> - see {@link #setMinWidth(int)};</li>
 633    * <li><code>maxWidth</code> - see {@link #setMaxWidth(int)};</li>
 634    * <li><code>modelIndex</code> - see {@link #setModelIndex(int)};</li>
 635    * <li><code>isResizable</code> - see {@link #setResizable(boolean)};</li>
 636    * <li><code>cellRenderer</code> - see
 637    *   {@link #setCellRenderer(TableCellRenderer)};</li>
 638    * <li><code>cellEditor</code> - see
 639    *   {@link #setCellEditor(TableCellEditor)};</li>
 640    * <li><code>headerRenderer</code> - see
 641    *   {@link #setHeaderRenderer(TableCellRenderer)};</li>
 642    * <li><code>headerValue</code> - see {@link #setHeaderValue(Object)};</li>
 643    * <li><code>identifier</code> - see {@link #setIdentifier(Object)}.</li>
 644    * </ul>
 645    *
 646    * @param listener the listener to add (<code>null</code> is ignored).
 647    *
 648    * @see #removePropertyChangeListener(PropertyChangeListener)
 649    */
 650   public synchronized void addPropertyChangeListener(
 651       PropertyChangeListener listener)
 652   {
 653     changeSupport.addPropertyChangeListener(listener);
 654   }
 655
 656   /**
 657    * Removes a listener so that it no longer receives
 658    * {@link PropertyChangeEvent} notifications from this column.  If
 659    * <code>listener</code> is not registered with the column, or is
 660    * <code>null</code>, this method does nothing.
 661    *
 662    * @param listener the listener to remove (<code>null</code> is ignored).
 663    */
 664   public synchronized void removePropertyChangeListener(
 665       PropertyChangeListener listener)
 666   {
 667     changeSupport.removePropertyChangeListener(listener);
 668   }
 669
 670   /**
 671    * Returns the property change listeners for this <code>TableColumn</code>.
 672    * An empty array is returned if there are currently no listeners registered.
 673    *
 674    * @return The property change listeners registered with this column.
 675    *
 676    * @since 1.4
 677    */
 678   public PropertyChangeListener[] getPropertyChangeListeners()
 679   {
 680     return changeSupport.getPropertyChangeListeners();
 681   }
 682
 683   /**
 684    * Creates and returns a default renderer for the column header (in this case,
 685    * a new instance of {@link DefaultTableCellRenderer}).
 686    *
 687    * @return A default renderer for the column header.
 688    */
 689   protected TableCellRenderer createDefaultHeaderRenderer()
 690   {
 691     return new DefaultTableCellRenderer();
 692   }
 693 }