libjava/javax/swing/JScrollBar.java

   1 /* JScrollBar.java --
   2    Copyright (C) 2002, 2004 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 package javax.swing;
  39
  40 import java.awt.Adjustable;
  41 import java.awt.Dimension;
  42 import java.awt.event.AdjustmentEvent;
  43 import java.awt.event.AdjustmentListener;
  44
  45 import javax.accessibility.Accessible;
  46 import javax.accessibility.AccessibleContext;
  47 import javax.accessibility.AccessibleRole;
  48 import javax.accessibility.AccessibleStateSet;
  49 import javax.accessibility.AccessibleValue;
  50 import javax.swing.event.ChangeEvent;
  51 import javax.swing.event.ChangeListener;
  52 import javax.swing.plaf.ScrollBarUI;
  53
  54
  55 /**
  56  * The JScrollBar. Two buttons control how the values that the
  57  * scroll bar can take. You can also drag the thumb or click the track
  58  * to move the scroll bar. Typically, the JScrollBar is used with
  59  * other components to translate the value of the bar to the viewable
  60  * contents of the other components.
  61  */
  62 public class JScrollBar extends JComponent implements Adjustable, Accessible
  63 {
  64   /**
  65    * DOCUMENT ME!
  66    */
  67   protected class AccessibleJScrollBar extends JComponent.AccessibleJComponent
  68     implements AccessibleValue
  69   {
  70     private static final long serialVersionUID = -7758162392045586663L;
  71
  72     /**
  73      * Creates a new AccessibleJSlider object.
  74      *
  75      * @param value0 DOCUMENT ME!
  76      */
  77     protected AccessibleJScrollBar()
  78     {
  79       super();
  80     }
  81
  82     /**
  83      * DOCUMENT ME!
  84      *
  85      * @return DOCUMENT ME!
  86      */
  87     public AccessibleStateSet getAccessibleStateSet()
  88     {
  89       return null;
  90     }
  91
  92     /**
  93      * DOCUMENT ME!
  94      *
  95      * @return DOCUMENT ME!
  96      */
  97     public AccessibleRole getAccessibleRole()
  98     {
  99       return null;
 100     }
 101
 102     /**
 103      * DOCUMENT ME!
 104      *
 105      * @return DOCUMENT ME!
 106      */
 107     public AccessibleValue getAccessibleValue()
 108     {
 109       return null;
 110     }
 111
 112     /**
 113      * DOCUMENT ME!
 114      *
 115      * @return DOCUMENT ME!
 116      */
 117     public Number getCurrentAccessibleValue()
 118     {
 119       return null;
 120     }
 121
 122     /**
 123      * setCurrentAccessibleValue
 124      *
 125      * @param value0 TODO
 126      *
 127      * @return boolean
 128      */
 129     public boolean setCurrentAccessibleValue(Number value0)
 130     {
 131       return false;
 132     }
 133
 134     /**
 135      * getMinimumAccessibleValue
 136      *
 137      * @return Number
 138      */
 139     public Number getMinimumAccessibleValue()
 140     {
 141       return null;
 142     }
 143
 144     /**
 145      * getMaximumAccessibleValue
 146      *
 147      * @return Number
 148      */
 149     public Number getMaximumAccessibleValue()
 150     {
 151       return null;
 152     }
 153   }
 154
 155   private static final long serialVersionUID = -8195169869225066566L;
 156
 157   /** Fired in a PropertyChangeEvent when the "blockIncrement" changes. */
 158   public static final String BLOCK_INCREMENT_CHANGED_PROPERTY = "blockIncrement";
 159
 160   /** Fired in a PropertyChangeEvent when the "model" changes. */
 161   public static final String MODEL_CHANGED_PROPERTY = "model";
 162
 163   /** Fired in a PropertyChangeEvent when the "orientation" changes. */
 164   public static final String ORIENTATION_CHANGED_PROPERTY = "orientation";
 165
 166   /** Fired in a PropertyChangeEvent when the "unitIncrement" changes. */
 167   public static final String UNIT_INCREMENT_CHANGED_PROPERTY = "unitIncrement";
 168
 169   /** How much the thumb moves when moving in a block. */
 170   protected int blockIncrement = 10;
 171
 172   /** The model that holds the scroll bar's data. */
 173   protected BoundedRangeModel model;
 174
 175   /** The orientation of the scroll bar. */
 176   protected int orientation = SwingConstants.VERTICAL;
 177
 178   /** How much the thumb moves when moving in a unit. */
 179   protected int unitIncrement = 1;
 180
 181   /** The ChangeListener that listens to the model. */
 182   private transient ChangeListener changeListener;
 183
 184   /** The ChangeEvent that's fired. */
 185   private transient ChangeEvent changeEvent;
 186
 187   /**
 188    * Creates a new horizontal JScrollBar object with a minimum
 189    * of 0, a maxmium of 100, a value of 0 and an extent of 10.
 190    */
 191   public JScrollBar()
 192   {
 193     this(SwingConstants.VERTICAL, 0, 10, 0, 100);
 194   }
 195
 196   /**
 197    * Creates a new JScrollBar object with a minimum of 0, a
 198    * maximum of 100, a value of 0, an extent of 10 and the given
 199    * orientation.
 200    *
 201    * @param orientation The orientation of the JScrollBar.
 202    */
 203   public JScrollBar(int orientation)
 204   {
 205     this(orientation, 0, 10, 0, 100);
 206   }
 207
 208   /**
 209    * Creates a new JScrollBar object with the given orientation,
 210    * value, min, max, and extent.
 211    *
 212    * @param orientation The orientation to use.
 213    * @param value The value to use.
 214    * @param extent The extent to use.
 215    * @param min The minimum value of the scrollbar.
 216    * @param max The maximum value of the scrollbar.
 217    */
 218   public JScrollBar(int orientation, int value, int extent, int min, int max)
 219   {
 220     model = new DefaultBoundedRangeModel(value, extent, min, max);
 221     if (orientation != SwingConstants.HORIZONTAL
 222         && orientation != SwingConstants.VERTICAL)
 223       throw new IllegalArgumentException(orientation
 224                                          + " is not a legal orientation");
 225     this.orientation = orientation;
 226     changeListener = createChangeListener();
 227     model.addChangeListener(changeListener);
 228     updateUI();
 229   }
 230
 231   /**
 232    * This method sets the UI of this scrollbar to
 233    * the given UI.
 234    *
 235    * @param ui The UI to use with this scrollbar.
 236    */
 237   public void setUI(ScrollBarUI ui)
 238   {
 239     super.setUI(ui);
 240   }
 241
 242   /**
 243    * This method returns the UI that is being used
 244    * with this scrollbar.
 245    *
 246    * @return The scrollbar's current UI.
 247    */
 248   public ScrollBarUI getUI()
 249   {
 250     return (ScrollBarUI) ui;
 251   }
 252
 253   /**
 254    * This method changes the UI to be the
 255    * default for the current look and feel.
 256    */
 257   public void updateUI()
 258   {
 259     setUI((ScrollBarUI) UIManager.getUI(this));
 260     invalidate();
 261     repaint();
 262   }
 263
 264   /**
 265    * This method returns an identifier to
 266    * choose the correct UI delegate for the
 267    * scrollbar.
 268    *
 269    * @return The identifer to choose the UI delegate; "ScrollBarUI"
 270    */
 271   public String getUIClassID()
 272   {
 273     return "ScrollBarUI";
 274   }
 275
 276   /**
 277    * This method returns the orientation of the scrollbar.
 278    *
 279    * @return The orientation of the scrollbar.
 280    */
 281   public int getOrientation()
 282   {
 283     return orientation;
 284   }
 285
 286   /**
 287    * This method sets the orientation of the scrollbar.
 288    *
 289    * @param orientation The orientation of the scrollbar.
 290    */
 291   public void setOrientation(int orientation)
 292   {
 293     if (orientation != SwingConstants.HORIZONTAL
 294         && orientation != SwingConstants.VERTICAL)
 295       throw new IllegalArgumentException("orientation must be one of HORIZONTAL or VERTICAL");
 296     if (orientation != this.orientation)
 297       {
 298         int oldOrientation = this.orientation;
 299         this.orientation = orientation;
 300         firePropertyChange(ORIENTATION_CHANGED_PROPERTY, oldOrientation,
 301                            this.orientation);
 302       }
 303   }
 304
 305   /**
 306    * This method returns the model being used with
 307    * the scrollbar.
 308    *
 309    * @return The scrollbar's model.
 310    */
 311   public BoundedRangeModel getModel()
 312   {
 313     return model;
 314   }
 315
 316   /**
 317    * This method sets the model to use with
 318    * the scrollbar.
 319    *
 320    * @param newModel The new model to use with the scrollbar.
 321    */
 322   public void setModel(BoundedRangeModel newModel)
 323   {
 324     if (model != newModel)
 325       {
 326         BoundedRangeModel oldModel = model;
 327         model = newModel;
 328         oldModel.removeChangeListener(changeListener);
 329         model.addChangeListener(changeListener);
 330         firePropertyChange(MODEL_CHANGED_PROPERTY, oldModel, model);
 331       }
 332   }
 333
 334   /**
 335    * This method returns how much the scrollbar's value
 336    * should change for a unit increment depending on the
 337    * given direction.
 338    *
 339    * @param direction The direction to scroll in.
 340    *
 341    * @return The amount the scrollbar's value will change given the direction.
 342    */
 343   public int getUnitIncrement(int direction)
 344   {
 345     return direction * unitIncrement;
 346   }
 347
 348   /**
 349    * This method sets the unitIncrement property.
 350    *
 351    * @param unitIncrement The new unitIncrement.
 352    */
 353   public void setUnitIncrement(int unitIncrement)
 354   {
 355     if (unitIncrement != this.unitIncrement)
 356       {
 357         int oldInc = this.unitIncrement;
 358         this.unitIncrement = unitIncrement;
 359         firePropertyChange(UNIT_INCREMENT_CHANGED_PROPERTY, oldInc,
 360                            this.unitIncrement);
 361       }
 362   }
 363
 364   /**
 365    * The method returns how much the scrollbar's value
 366    * should change for a block increment depending on
 367    * the given direction.
 368    *
 369    * @param direction The direction to scroll in.
 370    *
 371    * @return The amount the scrollbar's value will change given the direction.
 372    */
 373   public int getBlockIncrement(int direction)
 374   {
 375     return direction * blockIncrement;
 376   }
 377
 378   /**
 379    * This method sets the blockIncrement property.
 380    *
 381    * @param blockIncrement The new blockIncrement.
 382    */
 383   public void setBlockIncrement(int blockIncrement)
 384   {
 385     if (blockIncrement != this.blockIncrement)
 386       {
 387         int oldInc = this.blockIncrement;
 388         this.blockIncrement = blockIncrement;
 389         firePropertyChange(BLOCK_INCREMENT_CHANGED_PROPERTY, oldInc,
 390                            this.blockIncrement);
 391       }
 392   }
 393
 394   /**
 395    * This method returns the unitIncrement.
 396    *
 397    * @return The unitIncrement.
 398    */
 399   public int getUnitIncrement()
 400   {
 401     return unitIncrement;
 402   }
 403
 404   /**
 405    * This method returns the blockIncrement.
 406    *
 407    * @return The blockIncrement.
 408    */
 409   public int getBlockIncrement()
 410   {
 411     return blockIncrement;
 412   }
 413
 414   /**
 415    * This method returns the value of the scrollbar.
 416    *
 417    * @return The value of the scrollbar.
 418    */
 419   public int getValue()
 420   {
 421     return model.getValue();
 422   }
 423
 424   /**
 425    * This method changes the value of the scrollbar.
 426    *
 427    * @param value The new value of the scrollbar.
 428    */
 429   public void setValue(int value)
 430   {
 431     if (isEnabled() && value != getValue())
 432     {
 433       model.setValue(value);
 434       fireAdjustmentValueChanged(AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 435                                  AdjustmentEvent.TRACK, value);
 436     }
 437   }
 438
 439   /**
 440    * This method returns the visible amount (AKA extent).
 441    * The visible amount can be used by UI delegates to
 442    * determine the size of the thumb.
 443    *
 444    * @return The visible amount (AKA extent).
 445    */
 446   public int getVisibleAmount()
 447   {
 448     return model.getExtent();
 449   }
 450
 451   /**
 452    * This method sets the visible amount (AKA extent).
 453    *
 454    * @param extent The visible amount (AKA extent).
 455    */
 456   public void setVisibleAmount(int extent)
 457   {
 458     if (extent != getVisibleAmount())
 459     {
 460       model.setExtent(extent);
 461       fireAdjustmentValueChanged(AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 462                                  AdjustmentEvent.TRACK, extent);
 463     }
 464   }
 465
 466   /**
 467    * This method returns the minimum value of the scrollbar.
 468    *
 469    * @return The minimum value of the scrollbar.
 470    */
 471   public int getMinimum()
 472   {
 473     return model.getMinimum();
 474   }
 475
 476   /**
 477    * This method sets the minimum value of the scrollbar.
 478    *
 479    * @param minimum The minimum value of the scrollbar.
 480    */
 481   public void setMinimum(int minimum)
 482   {
 483     if (minimum != getMinimum())
 484     {
 485       model.setMinimum(minimum);
 486       fireAdjustmentValueChanged(AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 487                                  AdjustmentEvent.TRACK, minimum);
 488     }
 489   }
 490
 491   /**
 492    * This method returns the maximum value of the scrollbar.
 493    *
 494    * @return The maximum value of the scrollbar.
 495    */
 496   public int getMaximum()
 497   {
 498     return model.getMaximum();
 499   }
 500
 501   /**
 502    * This method sets the maximum value of the scrollbar.
 503    *
 504    * @param maximum The maximum value of the scrollbar.
 505    */
 506   public void setMaximum(int maximum)
 507   {
 508     if (maximum != getMaximum())
 509     {
 510       model.setMaximum(maximum);
 511       fireAdjustmentValueChanged(AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 512                                  AdjustmentEvent.TRACK, maximum);
 513     }
 514   }
 515
 516   /**
 517    * This method returns the model's isAjusting value.
 518    *
 519    * @return The model's isAdjusting value.
 520    */
 521   public boolean getValueIsAdjusting()
 522   {
 523     return model.getValueIsAdjusting();
 524   }
 525
 526   /**
 527    * This method sets the model's isAdjusting value.
 528    *
 529    * @param b The new isAdjusting value.
 530    */
 531   public void setValueIsAdjusting(boolean b)
 532   {
 533     model.setValueIsAdjusting(b);
 534   }
 535
 536   /**
 537    * This method sets the value, extent, minimum and
 538    * maximum.
 539    *
 540    * @param newValue The new value.
 541    * @param newExtent The new extent.
 542    * @param newMin The new minimum.
 543    * @param newMax The new maximum.
 544    */
 545   public void setValue(int newValue, int newExtent, int newMin, int newMax)
 546   {
 547     if (!isEnabled())
 548       newValue = model.getValue();
 549     // It seems to be that on any change the value is fired.
 550     if (newValue != getValue() || newExtent != getVisibleAmount() ||
 551         newMin != getMinimum() || newMax != getMaximum())
 552     {
 553       model.setRangeProperties(newValue, newExtent, newMin, newMax,
 554                                model.getValueIsAdjusting());
 555       fireAdjustmentValueChanged(AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 556                                  AdjustmentEvent.TRACK, newValue);
 557     }
 558   }
 559
 560   /**
 561    * This method creates a new ChangeListener.
 562    *
 563    * @return A new ChangeListener.
 564    */
 565   private ChangeListener createChangeListener()
 566   {
 567     return new ChangeListener()
 568       {
 569         public void stateChanged(ChangeEvent e)
 570         {
 571           fireStateChanged();
 572         }
 573       };
 574   }
 575
 576   /**
 577    * This method is called whenever the model fires a ChangeEvent. It should
 578    * propagate the ChangeEvent to its listeners with a new ChangeEvent that
 579    * identifies the scroll bar as the source.
 580    */
 581   private void fireStateChanged()
 582   {
 583     Object[] changeListeners = listenerList.getListenerList();
 584     if (changeEvent == null)
 585       changeEvent = new ChangeEvent(this);
 586     for (int i = changeListeners.length - 2; i >= 0; i -= 2)
 587       {
 588         if (changeListeners[i] == ChangeListener.class)
 589           ((ChangeListener) changeListeners[i + 1]).stateChanged(changeEvent);
 590       }
 591   }
 592
 593   /**
 594    * This method adds a ChangeListener to the scroll bar.
 595    *
 596    * @param listener The listener to add.
 597    */
 598   public void addChangeListener(ChangeListener listener)
 599   {
 600     listenerList.add(ChangeListener.class, listener);
 601   }
 602
 603   /**
 604    * This method removes a ChangeListener from the scroll bar.
 605    *
 606    * @param listener The listener to remove.
 607    */
 608   public void removeChangeListener(ChangeListener listener)
 609   {
 610     listenerList.remove(ChangeListener.class, listener);
 611   }
 612
 613   /**
 614    * This method returns an array of all ChangeListeners listening to this
 615    * scroll bar.
 616    *
 617    * @return An array of ChangeListeners listening to this scroll bar.
 618    */
 619   public ChangeListener[] getChangeListeners()
 620   {
 621     return (ChangeListener[]) listenerList.getListeners(ChangeListener.class);
 622   }
 623
 624   /**
 625    * This method adds an AdjustmentListener to the scroll bar.
 626    *
 627    * @param listener The listener to add.
 628    */
 629   public void addAdjustmentListener(AdjustmentListener listener)
 630   {
 631     listenerList.add(AdjustmentListener.class, listener);
 632   }
 633
 634   /**
 635    * This method removes an AdjustmentListener from the scroll bar.
 636    *
 637    * @param listener The listener to remove.
 638    */
 639   public void removeAdjustmentListener(AdjustmentListener listener)
 640   {
 641     listenerList.remove(AdjustmentListener.class, listener);
 642   }
 643
 644   /**
 645    * This method returns an arry of all AdjustmentListeners listening to
 646    * this scroll bar.
 647    *
 648    * @return An array of AdjustmentListeners listening to this scroll bar.
 649    */
 650   public AdjustmentListener[] getAdjustmentListeners()
 651   {
 652     return (AdjustmentListener[]) listenerList.getListeners(AdjustmentListener.class);
 653   }
 654
 655   /**
 656    * This method is called to fired AdjustmentEvents to the listeners
 657    * of this scroll bar. All AdjustmentEvents that are fired
 658    * will have an ID of ADJUSTMENT_VALUE_CHANGED and a type of
 659    * TRACK.
 660    *
 661    * @param id The ID of the adjustment event.
 662    * @param type The Type of change.
 663    * @param value The new value for the property that was changed..
 664    */
 665   protected void fireAdjustmentValueChanged(int id, int type, int value)
 666   {
 667     Object[] adjustmentListeners = listenerList.getListenerList();
 668     AdjustmentEvent adjustmentEvent = new AdjustmentEvent(this,
 669                                             AdjustmentEvent.ADJUSTMENT_VALUE_CHANGED,
 670                                             AdjustmentEvent.TRACK,
 671                                             value);
 672     for (int i = adjustmentListeners.length - 2; i >= 0; i -= 2)
 673       {
 674         if (adjustmentListeners[i] == AdjustmentListener.class)
 675           ((AdjustmentListener) adjustmentListeners[i + 1]).adjustmentValueChanged(adjustmentEvent);
 676       }
 677   }
 678
 679   /**
 680    * This method returns the minimum size for this scroll bar.
 681    *
 682    * @return The minimum size.
 683    */
 684   public Dimension getMinimumSize()
 685   {
 686     return ui.getMinimumSize(this);
 687   }
 688
 689   /**
 690    * This method returns the maximum size for this scroll bar.
 691    *
 692    * @return The maximum size.
 693    */
 694   public Dimension getMaximumSize()
 695   {
 696     return ui.getMaximumSize(this);
 697   }
 698
 699   /**
 700    * This method overrides the setEnabled in JComponent.
 701    * When the scroll bar is disabled, the knob cannot
 702    * be moved.
 703    *
 704    * @param x Whether the scrollbar is enabled.
 705    */
 706   public void setEnabled(boolean x)
 707   {
 708     // nothing special needs to be done here since we
 709     // just check the enabled setting before changing the value.
 710     super.setEnabled(x);
 711   }
 712
 713   /**
 714    * A string that describes this JScrollBar. Normally only used
 715    * for debugging.
 716    *
 717    * @return A string describing this JScrollBar.
 718    */
 719   protected String paramString()
 720   {
 721     return "JScrollBar";
 722   }
 723
 724   /**
 725    * DOCUMENT ME!
 726    *
 727    * @return DOCUMENT ME!
 728    */
 729   public AccessibleContext getAccessibleContext()
 730   {
 731     if (accessibleContext == null)
 732       accessibleContext = new AccessibleJScrollBar();
 733     return accessibleContext;
 734   }
 735 }