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