libjava/javax/swing/JProgressBar.java

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