libjava/java/awt/Scrollbar.java

   1 /* Scrollbar.java -- AWT Scrollbar widget
   2    Copyright (C) 1999, 2000, 2001, 2002 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
  39 package java.awt;
  40
  41 import java.awt.peer.ScrollbarPeer;
  42 import java.awt.peer.ComponentPeer;
  43
  44 import java.awt.event.AdjustmentListener;
  45 import java.awt.event.AdjustmentEvent;
  46
  47 /**
  48   * This class implements a scrollbar widget.
  49   *
  50   * @author Aaron M. Renn (arenn@urbanophile.com)
  51   * @author Tom Tromey <tromey@cygnus.com>
  52   */
  53 public class Scrollbar extends Component implements Adjustable,
  54                                                     java.io.Serializable
  55 {
  56
  57 // FIXME: Serialization readObject/writeObject
  58
  59 /*
  60  * Static Variables
  61  */
  62
  63 /**
  64   * Constant indicating that a scrollbar is horizontal.
  65   */
  66 public static final int HORIZONTAL = 0;
  67
  68 /**
  69   * Constant indicating that a scrollbar is vertical.
  70   */
  71 public static final int VERTICAL = 1;
  72
  73 // Serialization Constant
  74 private static final long serialVersionUID = 8451667562882310543L;
  75
  76 /*************************************************************************/
  77
  78 /**
  79   * @serial The amount by which the value of the scrollbar is changed
  80   * when incrementing in line mode.
  81   */
  82 private int lineIncrement;
  83
  84 /**
  85   * @serial The amount by which the value of the scrollbar is changed
  86   * when incrementing in page mode.
  87   */
  88 private int pageIncrement;
  89
  90 /**
  91   * @serial The maximum value for this scrollbar
  92   */
  93 private int maximum;
  94
  95 /**
  96   * @serial The minimum value for this scrollbar
  97   */
  98 private int minimum;
  99
 100 /**
 101   * @serial The orientation of this scrollbar, which will be either
 102   * the <code>HORIZONTAL</code> or <code>VERTICAL</code> constant
 103   * from this class.
 104   */
 105 private int orientation;
 106
 107 /**
 108   * @serial The current value of this scrollbar.
 109   */
 110 private int value;
 111
 112 /**
 113   * @serial The width of the scrollbar's thumb, which is relative
 114   * to the minimum and maximum value of the scrollbar.
 115   */
 116 private int visibleAmount;
 117
 118 // List of AdjustmentListener's.
 119 private AdjustmentListener adjustment_listeners;
 120
 121 /*************************************************************************/
 122
 123 /*
 124  * Constructors
 125  */
 126
 127 /**
 128   * Initializes a new instance of <code>Scrollbar</code> with a
 129   * veritical orientation and default values for all other parameters.
 130   */
 131 public
 132 Scrollbar()
 133 {
 134   this(VERTICAL);
 135 }
 136
 137 /*************************************************************************/
 138
 139 /**
 140   * Initializes a new instance of <code>Scrollbar</code> with the
 141   * specified orientation and default values for all other parameters.
 142   * The orientation must be either the constant <code>HORIZONTAL</code> or
 143   * <code>VERTICAL</code> from this class.  An incorrect value will throw
 144   * an exception.
 145   *
 146   * @param orientation The orientation of this scrollbar.
 147   *
 148   * @exception IllegalArgumentException If the orientation value is not valid.
 149   */
 150 public
 151 Scrollbar(int orientation) throws IllegalArgumentException
 152 {
 153   this(orientation, 0, 10, 0, 100);
 154 }
 155
 156 /*************************************************************************/
 157
 158 /**
 159   * Initializes a new instance of <code>Scrollbar</code> with the
 160   * specified parameters.  The orientation must be either the constant
 161   * <code>HORIZONTAL</code> or <code>VERTICAL</code>.  An incorrect value
 162   * will throw an exception.  Inconsistent values for other parameters
 163   * are silently corrected to valid values.
 164   *
 165   * @param orientation The orientation of this scrollbar.
 166   * @param value The initial value of the scrollbar.
 167   * @param visibleAmount The width of the scrollbar thumb.
 168   * @param minimum The minimum value of the scrollbar.
 169   * @param maximum The maximum value of the scrollbar.
 170   *
 171   * @exception IllegalArgumentException If the orientation value is not valid.
 172   */
 173 public
 174 Scrollbar(int orientation, int value, int visibleAmount, int minimum,
 175           int maximum) throws IllegalArgumentException
 176 {
 177   if ((orientation != HORIZONTAL) && (orientation != VERTICAL))
 178     throw new IllegalArgumentException("Bad orientation value: "
 179                                        + orientation);
 180
 181   this.orientation = orientation;
 182
 183   setValues(value, visibleAmount, minimum, maximum);
 184
 185   // Default is 1 according to online docs.
 186   lineIncrement = 1;
 187
 188   pageIncrement = (maximum - minimum) / 5;
 189   if (pageIncrement == 0)
 190     pageIncrement = 1;
 191 }
 192
 193 /*************************************************************************/
 194
 195 /*
 196  * Instance Methods
 197  */
 198
 199 /**
 200   * Returns the orientation constant for this object.
 201   *
 202   * @return The orientation constant for this object.
 203   */
 204 public int
 205 getOrientation()
 206 {
 207   return(orientation);
 208 }
 209
 210 /*************************************************************************/
 211
 212 /**
 213   * Sets the orientation of this scrollbar to the specified value.  This
 214   * value must be either the constant <code>HORIZONTAL</code> or
 215   * <code>VERTICAL</code> from this class or an exception will be thrown.
 216   *
 217   * @param orientation The new orientation value.
 218   *
 219   * @exception IllegalArgumentException If the orientation value is not valid.
 220   */
 221 public void
 222 setOrientation(int orientation)
 223 {
 224   if ((orientation != HORIZONTAL) && (orientation != VERTICAL))
 225     throw new IllegalArgumentException("Bad orientation value: "
 226                                        + orientation);
 227
 228   // FIXME: Communicate to peer?  Or must this be called before peer creation?
 229   this.orientation = orientation;
 230 }
 231
 232 /*************************************************************************/
 233
 234 /**
 235   * Returns the current value for this scrollbar.
 236   *
 237   * @return The current value for this scrollbar.
 238   */
 239 public int
 240 getValue()
 241 {
 242   return(value);
 243 }
 244
 245 /*************************************************************************/
 246
 247 /**
 248   * Sets the current value for this scrollbar to the specified value.
 249   * If this is inconsistent with the minimum and maximum values for this
 250   * scrollbar, the value is silently adjusted.
 251   *
 252   * @param value The new value for this scrollbar.
 253   */
 254 public void
 255 setValue(int value)
 256 {
 257   setValues(value, visibleAmount, minimum, maximum);
 258 }
 259
 260 /*************************************************************************/
 261
 262 /**
 263   * Returns the maximum value for this scrollbar.
 264   *
 265   * @return The maximum value for this scrollbar.
 266   */
 267 public int
 268 getMaximum()
 269 {
 270   return(maximum);
 271 }
 272
 273 /*************************************************************************/
 274
 275 /**
 276   * Sets the maximum value for this scrollbar to the specified value.
 277   * If the value is less than the current minimum value, it is silent
 278   * set to equal the minimum value.
 279   *
 280   * @param maximum The new maximum value for this scrollbar.
 281   */
 282 public void
 283 setMaximum(int maximum)
 284 {
 285   setValues(value, visibleAmount, minimum, maximum);
 286 }
 287
 288 /*************************************************************************/
 289
 290 /**
 291   * Returns the minimum value for this scrollbar.
 292   *
 293   * @return The minimum value for this scrollbar.
 294   */
 295 public int
 296 getMinimum()
 297 {
 298   return(minimum);
 299 }
 300
 301 /*************************************************************************/
 302
 303 /**
 304   * Sets the minimum value for this scrollbar to the specified value.  If
 305   * this is not consistent with the current value and maximum, it is
 306   * silently adjusted to be consistent.
 307   *
 308   * @param minimum The new minimum value for this scrollbar.
 309   */
 310 public void
 311 setMinimum(int minimum)
 312 {
 313   setValues(value, visibleAmount, minimum, maximum);
 314 }
 315
 316 /*************************************************************************/
 317
 318 /**
 319   * Returns the width of the scrollbar's thumb, in units relative to the
 320   * maximum and minimum value of the scrollbar.
 321   *
 322   * @return The width of the scrollbar's thumb.
 323   */
 324 public int
 325 getVisibleAmount()
 326 {
 327   return(visibleAmount);
 328 }
 329
 330 /*************************************************************************/
 331
 332 /**
 333   * Returns the width of the scrollbar's thumb, in units relative to the
 334   * maximum and minimum value of the scrollbar.
 335   *
 336   * @return The width of the scrollbar's thumb.
 337   *
 338   * @deprecated This method is deprecated in favor of
 339   * <code>getVisibleAmount()</code>.
 340   */
 341 public int
 342 getVisible()
 343 {
 344   return(getVisibleAmount());
 345 }
 346
 347 /*************************************************************************/
 348
 349 /**
 350   * Sets the width of the scrollbar's thumb, in units relative to the
 351   * maximum and minimum value of the scrollbar.
 352   *
 353   * @param visibileAmount The new visible amount value of the scrollbar.
 354   */
 355 public void
 356 setVisibleAmount(int visibleAmount)
 357 {
 358   setValues(value, visibleAmount, minimum, maximum);
 359 }
 360
 361 /*************************************************************************/
 362
 363 /**
 364   * Sets the current value, visible amount, minimum, and maximum for this
 365   * scrollbar.  These values are adjusted to be internally consistent
 366   * if necessary.
 367   *
 368   * @param value The new value for this scrollbar.
 369   * @param visibleAmount The new visible amount for this scrollbar.
 370   * @param minimum The new minimum value for this scrollbar.
 371   * @param maximum The new maximum value for this scrollbar.
 372   */
 373 public synchronized void
 374 setValues(int value, int visibleAmount, int minimum, int maximum)
 375 {
 376   if (maximum < minimum)
 377     maximum = minimum;
 378
 379   if (value < minimum)
 380     value = minimum;
 381
 382   if (value > maximum)
 383     value = maximum;
 384
 385   if (visibleAmount > value)
 386     visibleAmount = value;
 387
 388   this.value = value;
 389   this.visibleAmount = visibleAmount;
 390   this.minimum = minimum;
 391   this.maximum = maximum;
 392
 393   ScrollbarPeer sp = (ScrollbarPeer)getPeer();
 394   if (sp != null)
 395     sp.setValues(value, visibleAmount, minimum, maximum);
 396
 397   int range = maximum - minimum;
 398   if (lineIncrement > range)
 399     {
 400       if (range == 0)
 401         lineIncrement = 1;
 402       else
 403         lineIncrement = range;
 404
 405       if (sp != null)
 406         sp.setLineIncrement(lineIncrement);
 407     }
 408
 409   if (pageIncrement > range)
 410     {
 411       if (range == 0)
 412         pageIncrement = 1;
 413       else
 414         pageIncrement = range;
 415
 416       if (sp != null)
 417         sp.setPageIncrement(pageIncrement);
 418     }
 419 }
 420
 421 /*************************************************************************/
 422
 423 /**
 424   * Returns the value added or subtracted when the user activates the scrollbar
 425   * scroll by a "unit" amount.
 426   *
 427   * @return The unit increment value.
 428   */
 429 public int
 430 getUnitIncrement()
 431 {
 432   return(lineIncrement);
 433 }
 434
 435 /*************************************************************************/
 436
 437 /**
 438   * Returns the value added or subtracted when the user selects the scrollbar
 439   * scroll by a "unit" amount control.
 440   *
 441   * @return The unit increment value.
 442   *
 443   * @deprecated This method is deprecated in favor of
 444   * <code>getUnitIncrement()</code>.
 445   */
 446 public int
 447 getLineIncrement()
 448 {
 449   return(lineIncrement);
 450 }
 451
 452 /*************************************************************************/
 453
 454 /**
 455   * Sets the value added or subtracted to the scrollbar value when the
 456   * user selects the scroll by a "unit" amount control.
 457   *
 458   * @param unitIncrement The new unit increment amount.
 459   */
 460 public synchronized void
 461 setUnitIncrement(int unitIncrement)
 462 {
 463   if (unitIncrement < 0)
 464     throw new IllegalArgumentException("Unit increment less than zero.");
 465
 466   int range = maximum - minimum;
 467   if (unitIncrement > range)
 468     {
 469       if (range == 0)
 470         unitIncrement = 1;
 471       else
 472         unitIncrement = range;
 473     }
 474
 475   if (unitIncrement == lineIncrement)
 476     return;
 477
 478   lineIncrement = unitIncrement;
 479
 480   ScrollbarPeer sp = (ScrollbarPeer)getPeer();
 481   if (sp != null)
 482     sp.setLineIncrement(lineIncrement);
 483 }
 484
 485 /*************************************************************************/
 486
 487 /**
 488   * Sets the value added or subtracted to the scrollbar value when the
 489   * user selects the scroll by a "unit" amount control.
 490   *
 491   * @param lineIncrement The new unit increment amount.
 492   *
 493   * @deprecated This method is deprecated in favor of
 494   * <code>setUnitIncrement()</code>.
 495   */
 496 public void
 497 setLineIncrement(int lineIncrement)
 498 {
 499   setUnitIncrement(lineIncrement);
 500 }
 501
 502 /*************************************************************************/
 503
 504 /**
 505   * Returns the value added or subtracted when the user activates the scrollbar
 506   * scroll by a "block" amount.
 507   *
 508   * @return The block increment value.
 509   */
 510 public int
 511 getBlockIncrement()
 512 {
 513   return(pageIncrement);
 514 }
 515
 516 /*************************************************************************/
 517
 518 /**
 519   * Returns the value added or subtracted when the user selects the scrollbar
 520   * scroll by a "block" amount control.
 521   *
 522   * @return The block increment value.
 523   *
 524   * @deprecated This method is deprecated in favor of
 525   * <code>getBlockIncrement()</code>.
 526   */
 527 public int
 528 getPageIncrement()
 529 {
 530   return(pageIncrement);
 531 }
 532
 533 /*************************************************************************/
 534
 535 /**
 536   * Sets the value added or subtracted to the scrollbar value when the
 537   * user selects the scroll by a "block" amount control.
 538   *
 539   * @param blockIncrement The new block increment amount.
 540   */
 541 public synchronized void
 542 setBlockIncrement(int blockIncrement)
 543 {
 544   if (blockIncrement < 0)
 545     throw new IllegalArgumentException("Block increment less than zero.");
 546
 547   int range = maximum - minimum;
 548   if (blockIncrement > range)
 549     {
 550       if (range == 0)
 551         blockIncrement = 1;
 552       else
 553         blockIncrement = range;
 554     }
 555
 556   if (blockIncrement == pageIncrement)
 557     return;
 558
 559   pageIncrement = blockIncrement;
 560
 561   ScrollbarPeer sp = (ScrollbarPeer)getPeer();
 562   if (sp != null)
 563     sp.setPageIncrement(pageIncrement);
 564 }
 565
 566 /*************************************************************************/
 567
 568 /**
 569   * Sets the value added or subtracted to the scrollbar value when the
 570   * user selects the scroll by a "block" amount control.
 571   *
 572   * @param pageIncrement The new block increment amount.
 573   *
 574   * @deprecated This method is deprecated in favor of
 575   * <code>setBlockIncrement()</code>.
 576   */
 577 public void
 578 setPageIncrement(int pageIncrement)
 579 {
 580   setBlockIncrement(pageIncrement);
 581 }
 582
 583 /*************************************************************************/
 584
 585 /**
 586   * Notifies this object to create its native peer.
 587   */
 588 public synchronized void
 589 addNotify()
 590 {
 591   if (peer == null)
 592     peer = getToolkit ().createScrollbar (this);
 593   super.addNotify ();
 594 }
 595
 596 /*************************************************************************/
 597
 598 /**
 599   * Adds a new adjustment listener to the list of registered listeners
 600   * for this object.
 601   *
 602   * @param listener The listener to add.
 603   */
 604 public synchronized void
 605 addAdjustmentListener(AdjustmentListener listener)
 606 {
 607   adjustment_listeners = AWTEventMulticaster.add(adjustment_listeners, listener);
 608   enableEvents(AWTEvent.ADJUSTMENT_EVENT_MASK);
 609 }
 610
 611 /*************************************************************************/
 612
 613 /**
 614   * Removes the specified listener from the list of registered listeners
 615   * for this object.
 616   *
 617   * @param listener The listener to remove.
 618   */
 619 public synchronized void
 620 removeAdjustmentListener(AdjustmentListener listener)
 621 {
 622   adjustment_listeners = AWTEventMulticaster.remove(adjustment_listeners,
 623                                                     listener);
 624 }
 625
 626 /*************************************************************************/
 627
 628 /**
 629   * Processes events for this scrollbar.  It does this by calling
 630   * <code>processAdjustmentEvent()</code> if the event is an instance of
 631   * <code>AdjustmentEvent</code>, otherwise it calls the superclass to
 632   * process the event.
 633   *
 634   * @param event The event to process.
 635   */
 636 protected void
 637 processEvent(AWTEvent event)
 638 {
 639   if (event instanceof AdjustmentEvent)
 640     processAdjustmentEvent((AdjustmentEvent)event);
 641   else
 642     super.processEvent(event);
 643 }
 644
 645 /*************************************************************************/
 646
 647 /**
 648   * Processes adjustment events for this object by dispatching them to
 649   * any registered listeners.  Note that this method will only be called
 650   * if adjustment events are enabled.  This will happen automatically if
 651   * any listeners are registered.  Otherwise, it can be enabled by a
 652   * call to <code>enableEvents()</code>.
 653   *
 654   * @param event The event to process.
 655   */
 656 protected void
 657 processAdjustmentEvent(AdjustmentEvent event)
 658 {
 659   if (adjustment_listeners != null)
 660     adjustment_listeners.adjustmentValueChanged(event);
 661 }
 662
 663 void
 664 dispatchEventImpl(AWTEvent e)
 665 {
 666   if (e.id <= AdjustmentEvent.ADJUSTMENT_LAST
 667       && e.id >= AdjustmentEvent.ADJUSTMENT_FIRST
 668       && (adjustment_listeners != null
 669           || (eventMask & AWTEvent.ADJUSTMENT_EVENT_MASK) != 0))
 670     processEvent(e);
 671   else
 672     super.dispatchEventImpl(e);
 673 }
 674
 675 /*************************************************************************/
 676
 677 /**
 678   * Returns a debugging string for this object.
 679   *
 680   * @return A debugging string for this object.
 681   */
 682 protected String
 683 paramString()
 684 {
 685   return("value=" + getValue() + ",visibleAmount=" +
 686          getVisibleAmount() + ",minimum=" + getMinimum()
 687          + ",maximum=" + getMaximum()
 688          + ",pageIncrement=" + pageIncrement
 689          + ",lineIncrement=" + lineIncrement
 690          + ",orientation=" + (orientation == HORIZONTAL
 691                               ? "HORIZONTAL" : "VERTICAL")
 692          + super.paramString());
 693 }
 694
 695 } // class Scrollbar
 696