Source for javax.swing.JProgressBar

   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: }