libjava/classpath/javax/swing/JProgressBar.java

   1 /* JProgressBar.java --
   2    Copyright (C) 2002, 2004, 2005  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;
  40
  41 import java.awt.Graphics;
  42
  43 import javax.accessibility.Accessible;
  44 import javax.accessibility.AccessibleContext;
  45 import javax.accessibility.AccessibleRole;
  46 import javax.accessibility.AccessibleStateSet;
  47 import javax.accessibility.AccessibleValue;
  48 import javax.swing.border.Border;
  49 import javax.swing.event.ChangeEvent;
  50 import javax.swing.event.ChangeListener;
  51 import javax.swing.plaf.ProgressBarUI;
  52
  53 /**
  54  * The ProgressBar is a widget that displays in two modes. In
  55  * determinate mode, it displays fills a percentage of its bar
  56  * based on its current value. In indeterminate mode, it creates
  57  * box and bounces it between its bounds.
  58  *
  59  * <p>
  60  * JProgressBars have the following properties:
  61  * </p>
  62  *
  63  * <table>
  64  * <tr><th> Property         </th><th> Stored in   </th><th> Bound? </th></tr>
  65  * <tr><td> borderPainted    </td><td> progressBar </td><td> yes    </td></tr>
  66  * <tr><td> changeListeners  </td><td> progressBar </td><td> no     </td></tr>
  67  * <tr><td> indeterminate    </td><td> progressBar </td><td> yes    </td></tr>
  68  * <tr><td> maximum          </td><td> model       </td><td> no     </td></tr>
  69  * <tr><td> minimum          </td><td> model       </td><td> no     </td></tr>
  70  * <tr><td> model            </td><td> progressBar </td><td> no     </td></tr>
  71  * <tr><td> orientation      </td><td> progressBar </td><td> yes    </td></tr>
  72  * <tr><td> percentComplete  </td><td> progressBar </td><td> no     </td></tr>
  73  * <tr><td> string           </td><td> progressBar </td><td> yes    </td></tr>
  74  * <tr><td> stringPainted    </td><td> progressBar </td><td> yes    </td></tr>
  75  * <tr><td> value            </td><td> model       </td><td> no     </td></tr>
  76  * </table>
  77  */
  78 public class JProgressBar extends JComponent implements SwingConstants,
  79                                                         Accessible
  80 {
  81   /**
  82    * AccessibleJProgressBar
  83    */
  84   // FIXME: This inner class is a complete stub and needs to be implemented
  85   // properly.
  86   protected class AccessibleJProgressBar extends AccessibleJComponent
  87     implements AccessibleValue
  88   {
  89     private static final long serialVersionUID = -2938130009392721813L;
  90
  91     /**
  92      * Constructor AccessibleJProgressBar
  93      */
  94     protected AccessibleJProgressBar()
  95     {
  96       // Nothing to do here.
  97     }
  98
  99     /**
 100      * getAccessibleStateSet
 101      *
 102      * @return AccessibleStateSet
 103      */
 104     public AccessibleStateSet getAccessibleStateSet()
 105     {
 106       return null;
 107     }
 108
 109     /**
 110      * getAccessibleRole
 111      *
 112      * @return AccessibleRole
 113      */
 114     public AccessibleRole getAccessibleRole()
 115     {
 116       return AccessibleRole.PROGRESS_BAR;
 117     }
 118
 119     /**
 120      * getAccessibleValue
 121      *
 122      * @return AccessibleValue
 123      */
 124     public AccessibleValue getAccessibleValue()
 125     {
 126       return null;
 127     }
 128
 129     /**
 130      * getCurrentAccessibleValue
 131      *
 132      * @return Number
 133      */
 134     public Number getCurrentAccessibleValue()
 135     {
 136       return null;
 137     }
 138
 139     /**
 140      * setCurrentAccessibleValue
 141      *
 142      * @param value0 TODO
 143      *
 144      * @return boolean
 145      */
 146     public boolean setCurrentAccessibleValue(Number value0)
 147     {
 148       return false;
 149     }
 150
 151     /**
 152      * getMinimumAccessibleValue
 153      *
 154      * @return Number
 155      */
 156     public Number getMinimumAccessibleValue()
 157     {
 158       return null;
 159     }
 160
 161     /**
 162      * getMaximumAccessibleValue
 163      *
 164      * @return Number
 165      */
 166     public Number getMaximumAccessibleValue()
 167     {
 168       return null;
 169     }
 170   }
 171
 172   private static final long serialVersionUID = 1980046021813598781L;
 173
 174   /** Whether the ProgressBar is determinate. */
 175   private transient boolean indeterminate = false;
 176
 177   /** The orientation of the ProgressBar */
 178   protected int orientation = HORIZONTAL;
 179
 180   /** Whether borders should be painted. */
 181   protected boolean paintBorder = true;
 182
 183   /** The model describing this ProgressBar. */
 184   protected BoundedRangeModel model;
 185
 186   /** The string that is displayed by the ProgressBar. */
 187   protected String progressString;
 188
 189   /** Whether the string should be painted. */
 190   protected boolean paintString = false;
 191
 192   /** The static changeEvent passed to all ChangeListeners. */
 193   protected transient ChangeEvent changeEvent;
 194
 195   /** The ChangeListener that listens to the model. */
 196   protected ChangeListener changeListener;
 197
 198   /**
 199    * Creates a new horizontally oriented JProgressBar object
 200    * with a minimum of 0 and a maximum of 100.
 201    */
 202   public JProgressBar()
 203   {
 204     this(HORIZONTAL, 0, 100);
 205   }
 206
 207   /**
 208    * Creates a new JProgressBar object with a minimum of 0,
 209    * a maximum of 100, and the given orientation.
 210    *
 211    * @param orientation The orientation of the JProgressBar.
 212    *
 213    * @throws IllegalArgumentException if <code>orientation</code> is not either
 214    *         {@link #HORIZONTAL} or {@link #VERTICAL}.
 215    */
 216   public JProgressBar(int orientation)
 217   {
 218     this(orientation, 0, 100);
 219   }
 220
 221   /**
 222    * Creates a new horizontally oriented JProgressBar object
 223    * with the given minimum and maximum.
 224    *
 225    * @param minimum The minimum of the JProgressBar.
 226    * @param maximum The maximum of the JProgressBar.
 227    */
 228   public JProgressBar(int minimum, int maximum)
 229   {
 230     this(HORIZONTAL, minimum, maximum);
 231   }
 232
 233   /**
 234    * Creates a new JProgressBar object with the given minimum,
 235    * maximum, and orientation.
 236    *
 237    * @param minimum The minimum of the JProgressBar.
 238    * @param maximum The maximum of the JProgressBar.
 239    * @param orientation The orientation of the JProgressBar.
 240    *
 241    * @throws IllegalArgumentException if <code>orientation</code> is not either
 242    *         {@link #HORIZONTAL} or {@link #VERTICAL}.
 243    */
 244   public JProgressBar(int orientation, int minimum, int maximum)
 245   {
 246     model = new DefaultBoundedRangeModel(minimum, 0, minimum, maximum);
 247     if (orientation != HORIZONTAL && orientation != VERTICAL)
 248       throw new IllegalArgumentException(orientation + " is not a legal orientation");
 249     setOrientation(orientation);
 250     changeListener = createChangeListener();
 251     model.addChangeListener(changeListener);
 252     updateUI();
 253   }
 254
 255   /**
 256    * Creates a new horizontally oriented JProgressBar object
 257    * with the given model.
 258    *
 259    * @param model The model to be used with the JProgressBar.
 260    */
 261   public JProgressBar(BoundedRangeModel model)
 262   {
 263     this.model = model;
 264     changeListener = createChangeListener();
 265     if (model != null)
 266       model.addChangeListener(changeListener);
 267     updateUI();
 268   }
 269
 270   /**
 271    * This method returns the current value of the JProgressBar.
 272    *
 273    * @return The current value of the JProgressBar.
 274    */
 275   public int getValue()
 276   {
 277     return model.getValue();
 278   }
 279
 280   /**
 281    * This method sets the value of the JProgressBar.
 282    *
 283    * @param value The value of the JProgressBar.
 284    */
 285   public void setValue(int value)
 286   {
 287     model.setValue(value);
 288   }
 289
 290   /**
 291    * This method paints the border of the JProgressBar
 292    *
 293    * @param graphics The graphics object to paint with.
 294    */
 295   protected void paintBorder(Graphics graphics)
 296   {
 297     Border border = getBorder();
 298     if (paintBorder && border != null)
 299       border.paintBorder(this, graphics, 0, 0,
 300                          getWidth(),
 301                          getHeight());
 302   }
 303
 304   /**
 305    * This method returns the orientation of the JProgressBar.
 306    *
 307    * @return The orientation of the JProgressBar.
 308    */
 309   public int getOrientation()
 310   {
 311     return orientation;
 312   }
 313
 314   /**
 315    * This method changes the orientation property. The orientation of the
 316    * JProgressBar can be either horizontal or vertical.
 317    *
 318    * @param orientation The orientation of the JProgressBar.
 319    */
 320   public void setOrientation(int orientation)
 321   {
 322     if (orientation != VERTICAL && orientation != HORIZONTAL)
 323       throw new IllegalArgumentException("orientation must be one of VERTICAL or HORIZONTAL");
 324     if (this.orientation != orientation)
 325       {
 326         int oldOrientation = this.orientation;
 327         this.orientation = orientation;
 328         firePropertyChange("orientation", oldOrientation,
 329                            this.orientation);
 330       }
 331   }
 332
 333   /**
 334    * This method returns whether the progressString will be painted.
 335    *
 336    * @return Whether the string is painted.
 337    */
 338   public boolean isStringPainted()
 339   {
 340     return paintString;
 341   }
 342
 343   /**
 344    * This method changes the stringPainted property.
 345    *
 346    * @param painted Whether the string is painted.
 347    */
 348   public void setStringPainted(boolean painted)
 349   {
 350     if (paintString != painted)
 351       {
 352         boolean oldPainted = paintString;
 353         paintString = painted;
 354         firePropertyChange("stringPainted", oldPainted,
 355                            paintString);
 356       }
 357   }
 358
 359   /**
 360    * This method returns the string that is painted if the
 361    * stringPainted property is set to true. If there is no
 362    * string set, it will return a string containing the
 363    * JProgressBar's value as a percent.
 364    *
 365    * @return The string that is painted.
 366    */
 367   public String getString()
 368   {
 369     if (progressString != null)
 370       return progressString;
 371     else
 372       return (int) (getPercentComplete() * 100) + "%";
 373   }
 374
 375   /**
 376    * This method changes the string property. The string
 377    * given will be the one painted. If you want to
 378    * revert to the default string given, set the
 379    * string to null.
 380    *
 381    * @param string The string to be painted.
 382    */
 383   public void setString(String string)
 384   {
 385     if (((string == null || progressString == null) &&
 386         string != progressString) || (string != null &&
 387         ! string.equals(progressString)))
 388       {
 389         String oldString = progressString;
 390         progressString = string;
 391         firePropertyChange("string", oldString, progressString);
 392       }
 393   }
 394
 395   /**
 396    * This method returns the percent of the bar
 397    * that is "complete". (This is the amount value / (max - min)).
 398    *
 399    * @return DOCUMENT ME!
 400    */
 401   public double getPercentComplete()
 402   {
 403     if (getMaximum() == getMinimum())
 404       return 1.0;
 405     else
 406       return (double) (model.getValue() - model.getMinimum()) / (model
 407                                                                  .getMaximum()
 408              - model.getMinimum());
 409   }
 410
 411   /**
 412    * This method returns whether the border is painted.
 413    *
 414    * @return Whether the border is painted.
 415    */
 416   public boolean isBorderPainted()
 417   {
 418     return paintBorder;
 419   }
 420
 421   /**
 422    * This method changes the borderPainted property.
 423    *
 424    * @param painted Whether the border is painted.
 425    */
 426   public void setBorderPainted(boolean painted)
 427   {
 428     if (painted != paintBorder)
 429       {
 430         boolean oldPainted = paintBorder;
 431         paintBorder = painted;
 432         firePropertyChange("borderPainted", oldPainted,
 433                            paintBorder);
 434       }
 435   }
 436
 437   /**
 438    * This method returns the JProgressBar's UI delegate.
 439    *
 440    * @return This JProgressBar's UI delegate.
 441    */
 442   public ProgressBarUI getUI()
 443   {
 444     return (ProgressBarUI) ui;
 445   }
 446
 447   /**
 448    * This method changes the UI property for this JProgressBar.
 449    *
 450    * @param ui The new UI delegate.
 451    */
 452   public void setUI(ProgressBarUI ui)
 453   {
 454     super.setUI(ui);
 455   }
 456
 457   /**
 458    * This method reverts the UI delegate for this JProgressBar
 459    * to the default for this Look and Feel.
 460    */
 461   public void updateUI()
 462   {
 463     setUI((ProgressBarUI) UIManager.getUI(this));
 464     invalidate();
 465   }
 466
 467   /**
 468    * This method returns the identifier to allow the UIManager
 469    * to pick the correct class to act as the UI for
 470    * this JProgressBar.
 471    *
 472    * @return The UIClassID: "ProgressBarUI".
 473    */
 474   public String getUIClassID()
 475   {
 476     return "ProgressBarUI";
 477   }
 478
 479   /**
 480    * This method returns a ChangeListener that gets registered
 481    * model. By default, the ChangeListener, propagates the
 482    * ChangeEvents to the ChangeListeners of the JProgressBar.
 483    *
 484    * @return A new ChangeListener.
 485    */
 486   protected ChangeListener createChangeListener()
 487   {
 488     return new ChangeListener()
 489       {
 490         public void stateChanged(ChangeEvent ce)
 491         {
 492           fireStateChanged();
 493         }
 494       };
 495   }
 496
 497   /**
 498    * This method adds a ChangeListener to this JProgressBar.
 499    *
 500    * @param listener The ChangeListener to add to this JProgressBar.
 501    */
 502   public void addChangeListener(ChangeListener listener)
 503   {
 504     listenerList.add(ChangeListener.class, listener);
 505   }
 506
 507   /**
 508    * This method removes a ChangeListener from this JProgressBar.
 509    *
 510    * @param listener The ChangeListener to remove from this JProgressBar.
 511    */
 512   public void removeChangeListener(ChangeListener listener)
 513   {
 514     listenerList.remove(ChangeListener.class, listener);
 515   }
 516
 517   /**
 518    * This method returns an array of all ChangeListeners listening to this
 519    * progress bar.
 520    *
 521    * @return An array of ChangeListeners listening to this progress bar.
 522    */
 523   public ChangeListener[] getChangeListeners()
 524   {
 525     return (ChangeListener[]) listenerList.getListeners(ChangeListener.class);
 526   }
 527
 528   /**
 529    * This method is called when the JProgressBar receives a ChangeEvent
 530    * from its model. This simply propagates the event (changing the source
 531    * to the JProgressBar) to the JProgressBar's listeners.
 532    */
 533   protected void fireStateChanged()
 534   {
 535     Object[] changeListeners = listenerList.getListenerList();
 536     if (changeEvent == null)
 537       changeEvent = new ChangeEvent(this);
 538     for (int i = changeListeners.length - 2; i >= 0; i -= 2)
 539       {
 540         if (changeListeners[i] == ChangeListener.class)
 541           ((ChangeListener) changeListeners[i + 1]).stateChanged(changeEvent);
 542       }
 543   }
 544
 545   /**
 546    * This method returns the model used with this JProgressBar.
 547    *
 548    * @return The model used with this JProgressBar.
 549    */
 550   public BoundedRangeModel getModel()
 551   {
 552     return model;
 553   }
 554
 555   /**
 556    * This method changes the model property for this JProgressBar.
 557    *
 558    * @param model The model to use with this JProgressBar.
 559    */
 560   public void setModel(BoundedRangeModel model)
 561   {
 562     if (model != this.model)
 563       {
 564         this.model.removeChangeListener(changeListener);
 565         this.model = model;
 566         this.model.addChangeListener(changeListener);
 567         fireStateChanged();
 568       }
 569   }
 570
 571   /**
 572    * This method returns the minimum value of this JProgressBar.
 573    *
 574    * @return The minimum value of this JProgressBar.
 575    */
 576   public int getMinimum()
 577   {
 578     return model.getMinimum();
 579   }
 580
 581   /**
 582    * This method sets the minimum value of this JProgressBar.
 583    *
 584    * @param minimum The minimum value of this JProgressBar.
 585    */
 586   public void setMinimum(int minimum)
 587   {
 588     model.setMinimum(minimum);
 589   }
 590
 591   /**
 592    * This method returns the maximum value of this JProgressBar.
 593    *
 594    * @return The maximum value of this JProgressBar.
 595    */
 596   public int getMaximum()
 597   {
 598     return model.getMaximum();
 599   }
 600
 601   /**
 602    * This method sets the maximum value of this JProgressBar.
 603    *
 604    * @param maximum The maximum value of this JProgressBar.
 605    */
 606   public void setMaximum(int maximum)
 607   {
 608     model.setMaximum(maximum);
 609   }
 610
 611   /**
 612    * This method returns a string that can be used to
 613    * describe this JProgressBar. This method is usually
 614    * only used for debugging purposes.
 615    *
 616    * @return A string that describes this JProgressBar.
 617    */
 618   protected String paramString()
 619   {
 620     return "JProgressBar";
 621   }
 622
 623   /**
 624    * This method changes the indeterminate property. If the
 625    * JProgressBar is determinate, it paints a percentage
 626    * of the bar described by its value. If it is indeterminate,
 627    * it simply bounces a box between the ends of the bar; the
 628    * value of the JProgressBar is ignored.
 629    *
 630    * @param newValue Whether the JProgressBar is indeterminate.
 631    */
 632   public void setIndeterminate(boolean newValue)
 633   {
 634     if (indeterminate != newValue)
 635       {
 636         boolean olddeter = indeterminate;
 637         indeterminate = newValue;
 638         firePropertyChange("indeterminate", olddeter,
 639                            indeterminate);
 640       }
 641   }
 642
 643   /**
 644    * This method returns whether the JProgressBar is indeterminate.
 645    *
 646    * @return Whether this JProgressBar is indeterminate.
 647    */
 648   public boolean isIndeterminate()
 649   {
 650     return indeterminate;
 651   }
 652
 653   /**
 654    * DOCUMENT ME!
 655    *
 656    * @return DOCUMENT ME!
 657    */
 658   public AccessibleContext getAccessibleContext()
 659   {
 660     if (accessibleContext == null)
 661       accessibleContext = new AccessibleJProgressBar();
 662
 663     return accessibleContext;
 664   }
 665 }