SProgressBar


1   /*
2    * $Id: SProgressBar.java,v 1.11 2005/05/26 13:18:08 neurolabs Exp $
3    * Copyright 2000,2005 wingS development team.
4    *
5    * This file is part of wingS (http://www.j-wings.org).
6    *
7    * wingS is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU Lesser General Public License
9    * as published by the Free Software Foundation; either version 2.1
10   * of the License, or (at your option) any later version.
11   *
12   * Please see COPYING for the complete licence.
13   */
14  package org.wings;
15  
16  import org.wings.plaf.ProgressBarCG;
17  
18  import javax.swing.*;
19  import javax.swing.event.ChangeEvent  ;
20  import javax.swing.event.ChangeListener  ;
21  import java.awt.*;
22  import java.io.Serializable  ;
23  import java.text.Format  ;
24  import java.text.NumberFormat  ;
25  
26  
27  /**
28   * <!--
29   * SProgressBar.java
30   * Created: Mon Oct 28 18:55:02 2002
31   * -->
32   *
33   * @author <a HREF="mailto:armin.haaf@mercatis.de">Armin Haaf</a>
34   * @version $Revision: 1.11 $
35   */
36  public class SProgressBar extends SComponent {
37  
38      public static final String   STRING_PROPERTY = "_String_Property";
39      public static final String   STRING_PAINTED_PROPERTY = "_String_Painted_Property";
40      public static final String   BORDER_PAINTED_PROPERTY = "_Border_Painted_Property";
41      public static final String   ORIENTATION_PROPERTY = "_Orientation_Property";
42  
43  
44      /**
45       * Whether the progress bar is horizontal or vertical.
46       * The default is <code>HORIZONTAL</code>.
47       *
48       * @see #setOrientation
49       */
50      protected int orientation;
51  
52      /**
53       * Whether to display a border around the progress bar.
54       * The default is <code>true</code>.
55       *
56       * @see #setBorderPainted
57       */
58      protected boolean paintBorder;
59  
60      /**
61       * The object that holds the data for the progress bar.
62       *
63       * @see #setModel
64       */
65      protected BoundedRangeModel model;
66  
67      /**
68       * An optional string that can be displayed on the progress bar.
69       * The default is <code>null</code>. Setting this to a non-<code>null</code>
70       * value does not imply that the string will be displayed.
71       *
72       * @see #setString
73       */
74      protected String   progressString;
75  
76      /**
77       * Whether to textually display a string on the progress bar.
78       * The default is <code>false</code>.
79       * Setting this to <code>true</code> causes a textual
80       * display of the progress to be rendered on the progress bar. If
81       * the <code>progressString</code> is <code>null</code>,
82       * the percentage of completion is displayed on the progress bar.
83       * Otherwise, the <code>progressString</code> is
84       * rendered on the progress bar.
85       *
86       * @see #setStringPainted
87       */
88      protected boolean paintString;
89  
90      /**
91       * The default minimum for a progress bar is 0.
92       */
93      static final private int defaultMinimum = 0;
94      /**
95       * The default maximum for a progress bar is 100.
96       */
97      static final private int defaultMaximum = 100;
98      /**
99       * The default orientation for a progress bar is <code>HORIZONTAL</code>.
100      */
101     static final private int defaultOrientation = SConstants.HORIZONTAL;
102 
103     /**
104      * Only one <code>ChangeEvent</code> is needed per instance since the
105      * event's only interesting property is the immutable source, which
106      * is the progress bar.
107      */
108     protected transient ChangeEvent   changeEvent = null;
109 
110     /**
111      * Listens for change events sent by the progress bar's model,
112      * redispatching them
113      * to change-event listeners registered upon
114      * this progress bar.
115      *
116      * @see #createChangeListener
117      */
118     protected ChangeListener   changeListener = null;
119 
120     /**
121      * Format used when displaying percent complete.
122      */
123     private transient Format   format;
124 
125     /**
126      * Whether the progress bar is indeterminate (<code>true</code>) or
127      * normal (<code>false</code>); the default is <code>false</code>.
128      *
129      * @see #setIndeterminate
130      * @since 1.4
131      */
132     private boolean indeterminate;
133 
134     /**
135      * The color in which the border is painted
136      */
137     private Color borderColor;
138 
139     /**
140      * The color in which the filled region is painted
141      */
142     private Color filledColor;
143 
144     /**
145      * The color in which the unfilled region is painted
146      */
147     private Color unfilledColor;
148 
149     /**
150      * The Dimension of the ProgressBar. We can't use the component size.
151      */
152     private SDimension progressBarDimension;
153 
154     /**
155      * Creates a horizontal progress bar
156      * that displays a border but no progress string.
157      * The initial and minimum values are 0,
158      * and the maximum is 100.
159      *
160      * @see #setOrientation
161      * @see #setBorderPainted
162      * @see #setStringPainted
163      * @see #setString
164      * @see #setIndeterminate
165      */
166     public SProgressBar() {
167         this(defaultOrientation);
168     }
169 
170     /**
171      * Creates a progress bar with the specified orientation,
172      * which can be
173      * either <code>SProgressBar.VERTICAL</code> or
174      * <code>SProgressBar.HORIZONTAL</code>.
175      * By default, a border is painted but a progress string is not.
176      * The initial and minimum values are 0,
177      * and the maximum is 100.
178      *
179      * @param orient the desired orientation of the progress bar
180      * @see #setOrientation
181      * @see #setBorderPainted
182      * @see #setStringPainted
183      * @see #setString
184      * @see #setIndeterminate
185      */
186     public SProgressBar(int orient) {
187         this(orient, defaultMinimum, defaultMaximum);
188     }
189 
190 
191     /**
192      * Creates a horizontal progress bar
193      * with the specified minimum and maximum.
194      * Sets the initial value of the progress bar to the specified minimum.
195      * By default, a border is painted but a progress string is not.
196      * The <code>BoundedRangeModel</code> that holds the progress bar's data
197      * handles any issues that may arise from improperly setting the
198      * minimum, initial, and maximum values on the progress bar.
199      *
200      * @param min the minimum value of the progress bar
201      * @param max the maximum value of the progress bar
202      * @see BoundedRangeModel
203      * @see #setOrientation
204      * @see #setBorderPainted
205      * @see #setStringPainted
206      * @see #setString
207      * @see #setIndeterminate
208      */
209     public SProgressBar(int min, int max) {
210         this(defaultOrientation, min, max);
211     }
212 
213 
214     /**
215      * Creates a progress bar using the specified orientation,
216      * minimum, and maximum.
217      * By default, a border is painted but a progress string is not.
218      * Sets the initial value of the progress bar to the specified minimum.
219      * The <code>BoundedRangeModel</code> that holds the progress bar's data
220      * handles any issues that may arise from improperly setting the
221      * minimum, initial, and maximum values on the progress bar.
222      *
223      * @param orient the desired orientation of the progress bar
224      * @param min    the minimum value of the progress bar
225      * @param max    the maximum value of the progress bar
226      * @see BoundedRangeModel
227      * @see #setOrientation
228      * @see #setBorderPainted
229      * @see #setStringPainted
230      * @see #setString
231      * @see #setIndeterminate
232      */
233     public SProgressBar(int orient, int min, int max) {
234         // Creating the model this way is a bit simplistic, but
235         //  I believe that it is the the most common usage of this
236         //  component - it's what people will expect.
237         setModel(new DefaultBoundedRangeModel(min, 0, min, max));
238 
239         setOrientation(orient);      // documented with set/getOrientation()
240         setBorderPainted(true);      // documented with is/setBorderPainted()
241         setStringPainted(false);     // see setStringPainted
242         setString(null);             // see getString
243         setIndeterminate(false);     // see setIndeterminate
244     }
245 
246 
247     /**
248      * Creates a horizontal progress bar
249      * that uses the specified model
250      * to hold the progress bar's data.
251      * By default, a border is painted but a progress string is not.
252      *
253      * @param newModel the data model for the progress bar
254      * @see #setOrientation
255      * @see #setBorderPainted
256      * @see #setStringPainted
257      * @see #setString
258      * @see #setIndeterminate
259      */
260     public SProgressBar(BoundedRangeModel newModel) {
261         setModel(newModel);
262 
263         setOrientation(defaultOrientation);  // see setOrientation()
264         setBorderPainted(true);              // see setBorderPainted()
265         setStringPainted(false);             // see setStringPainted
266         setString(null);                     // see getString
267         setIndeterminate(false);             // see setIndeterminate
268     }
269 
270 
271     /**
272      * Returns <code>SProgressBar.VERTICAL</code> or
273      * <code>SProgressBar.HORIZONTAL</code>, depending on the orientation
274      * of the progress bar. The default orientation is
275      * <code>HORIZONTAL</code>.
276      *
277      * @return <code>HORIZONTAL</code> or <code>VERTICAL</code>
278      * @see #setOrientation
279      */
280     public int getOrientation() {
281         return orientation;
282     }
283 
284 
285     /**
286      * Sets the progress bar's orientation to <code>newOrientation</code>,
287      * which must be <code>SProgressBar.VERTICAL</code> or
288      * <code>SProgressBar.HORIZONTAL</code>. The default orientation
289      * is <code>HORIZONTAL</code>.
290      *
291      * @param newOrientation <code>HORIZONTAL</code> or <code>VERTICAL</code>
292      * @throws IllegalArgumentException if <code>newOrientation</code>
293      *                                  is an illegal value
294      * @see #getOrientation
295      */
296     public void setOrientation(int newOrientation) {
297         if (orientation != newOrientation) {
298             switch (newOrientation) {
299                 case SConstants.VERTICAL:
300                 case SConstants.HORIZONTAL:
301                     int oldOrientation = orientation;
302                     orientation = newOrientation;
303                     reloadIfChange(oldOrientation, newOrientation);
304                     break;
305                 default:
306                     throw new IllegalArgumentException  (newOrientation +
307                             " is not a legal orientation");
308             }
309         }
310     }
311 
312 
313     /**
314      * Returns the value of the <code>stringPainted</code> property.
315      *
316      * @return the value of the <code>stringPainted</code> property
317      * @see #setStringPainted
318      * @see #setString
319      */
320     public boolean isStringPainted() {
321         return paintString;
322     }
323 
324 
325     /**
326      * Sets the value of the <code>stringPainted</code> property,
327      * which determines whether the progress bar
328      * should render a progress string.
329      * The default is <code>false</code>:
330      * no string is painted.
331      * Some look and feels might not support progress strings
332      * or might support them only when the progress bar is in determinate mode.
333      *
334      * @param b <code>true</code> if the progress bar should render a string
335      * @see #isStringPainted
336      * @see #setString
337      */
338     public void setStringPainted(boolean b) {
339         //PENDING: specify that string not painted when in indeterminate mode?
340         //         or just leave that to the L&F?
341         boolean oldValue = paintString;
342         paintString = b;
343         reloadIfChange(oldValue, paintString);
344     }
345 
346 
347     /**
348      * Returns the current value of the progress string.
349      * If you are providing a custom progress string
350      * by overriding this method,
351      * make sure your implementation calls <code>setString</code> before
352      * calling <code>super.getString</code>.
353      *
354      * @return the value of the percent string
355      * @see #setString
356      */
357     public String   getString() {
358         if (progressString != null) {
359             return progressString;
360         } else {
361             if (format == null) {
362                 format = NumberFormat.getPercentInstance();
363             }
364             return format.format(new Double  (getPercentComplete()));
365         }
366     }
367 
368     /**
369      * Sets the value of the progress string. By default,
370      * this string is <code>null</code>.
371      * If you have provided a custom progress string and want to revert to
372      * the built-in behavior, set the string back to <code>null</code>.
373      * If you are providing a custom progress string
374      * by overriding this method,
375      * make sure that you call <code>setString</code> before
376      * calling <code>getString</code>.
377      * The progress string is painted only if
378      * the <code>isStringPainted</code> method returns <code>true</code>.
379      *
380      * @param s the value of the percent string
381      * @see #getString
382      * @see #setStringPainted
383      * @see #isStringPainted
384      */
385     public void setString(String   s) {
386         String   oldValue = progressString;
387         progressString = s;
388         reloadIfChange(oldValue, progressString);
389     }
390 
391     /**
392      * Returns the percent complete for the progress bar.
393      * Note that this number is between 0.0 and 1.0.
394      *
395      * @return the percent complete for this progress bar
396      */
397     public double getPercentComplete() {
398         long span = model.getMaximum() - model.getMinimum();
399         double currentValue = model.getValue();
400         double pc = (currentValue - model.getMinimum()) / span;
401         return pc;
402     }
403 
404     /**
405      * Returns the <code>borderPainted</code> property.
406      *
407      * @return the value of the <code>borderPainted</code> property
408      * @see #setBorderPainted
409      */
410     public boolean isBorderPainted() {
411         return paintBorder;
412     }
413 
414     /**
415      * Sets the <code>borderPainted</code> property, which is
416      * <code>true</code> if the progress bar should paint its border.
417      * The default value for this property is <code>true</code>.
418      * Some look and feels might not implement painted borders;
419      * they will ignore this property.
420      *
421      * @param b <code>true</code> if the progress bar
422      *          should paint its border;
423      *          otherwise, <code>false</code>
424      * @see #isBorderPainted
425      */
426     public void setBorderPainted(boolean b) {
427         boolean oldValue = paintBorder;
428         paintBorder = b;
429         reloadIfChange(oldValue, paintBorder);
430     }
431 
432     /**
433      * Set the color in which the border is painted, if the border is painted
434      *
435      * @param c a <code>Color</code> value
436      */
437     public void setBorderColor(Color c) {
438         borderColor = c;
439     }
440 
441     /**
442      * Returns the color in which the border is painted, if the border is painted
443      *
444      * @return a <code>Color</code> value
445      */
446     public Color getBorderColor() {
447         return borderColor;
448     }
449 
450     /**
451      * Sets the color in which the fille region is painted
452      *
453      * @param c a <code>Color</code> value
454      */
455     public void setFilledColor(Color c) {
456         filledColor = c;
457     }
458 
459     /**
460      * Returns the color in which the fille region is painted
461      */
462     public Color getFilledColor() {
463         return filledColor;
464     }
465 
466     /**
467      * Sets the color in which the unfilled region is painted
468      *
469      * @param c a <code>Color</code> value
470      */
471     public void setUnfilledColor(Color c) {
472         unfilledColor = c;
473     }
474 
475     /**
476      * Returns the color in which the unfilled region is painted
477     */
478     public Color getUnfilledColor() {
479         return unfilledColor;
480     }
481 
482     /**
483      * Sets the look-and-feel object that renders this component.
484      *
485      * @param cg a <code>ProgressBarCG</code> object
486      */
487     public void setCG(ProgressBarCG cg) {
488         super.setCG(cg);
489     }
490 
491     /* We pass each Change event to the listeners with the
492      * the progress bar as the event source.
493      * <p>
494      * <strong>Warning:</strong>
495      * Serialized objects of this class will not be compatible with
496      * future Swing releases. The current serialization support is
497      * appropriate for short term storage or RMI between applications running
498      * the same version of Swing.  As of 1.4, support for long term storage
499      * of all JavaBeans<sup><font size="-2">TM</font></sup>
500      * has been added to the <code>java.beans</code> package.
501      * Please see {@link java.beans.XMLEncoder}.
502      */
503     private class ModelListener implements ChangeListener  , Serializable   {
504         public void stateChanged(ChangeEvent   e) {
505             reload();
506             fireStateChanged();
507         }
508     }
509 
510     /**
511      * Subclasses that want to handle change events
512      * from the model differently
513      * can override this to return
514      * an instance of a custom <code>ChangeListener</code> implementation.
515      *
516      * @see #changeListener
517      * @see javax.swing.event.ChangeListener
518      * @see javax.swing.BoundedRangeModel
519      */
520     protected ChangeListener   createChangeListener() {
521         return new ModelListener();
522     }
523 
524     /**
525      * Adds the specified <code>ChangeListener</code> to the progress bar.
526      *
527      * @param l the <code>ChangeListener</code> to add
528      */
529     public void addChangeListener(ChangeListener   l) {
530         addEventListener(ChangeListener  .class, l);
531     }
532 
533     /**
534      * Removes a <code>ChangeListener</code> from the progress bar.
535      *
536      * @param l the <code>ChangeListener</code> to remove
537      */
538     public void removeChangeListener(ChangeListener   l) {
539         removeEventListener(ChangeListener  .class, l);
540     }
541 
542     /**
543      * Returns an array of all the <code>ChangeListener</code>s added
544      * to this progress bar with <code>addChangeListener</code>.
545      *
546      * @return all of the <code>ChangeListener</code>s added or an empty
547      *         array if no listeners have been added
548      * @since 1.4
549      */
550     public ChangeListener  [] getChangeListeners() {
551         return (ChangeListener  []) getListeners(ChangeListener  .class);
552     }
553 
554     /**
555      * Notifies all listeners that have registered interest in
556      * <code>ChangeEvent</code>s.
557      * The event instance
558      * is created if necessary.
559      *
560      * @see javax.swing.event.EventListenerList
561      */
562     protected void fireStateChanged() {
563         // Guaranteed to return a non-null array
564         Object  [] listeners = getListenerList();
565         // Process the listeners last to first, notifying
566         // those that are interested in this event
567         for (int i = listeners.length - 2; i >= 0; i -= 2) {
568             if (listeners[i] == ChangeListener  .class) {
569                 // Lazily create the event:
570                 if (changeEvent == null)
571                     changeEvent = new ChangeEvent  (this);
572                 ((ChangeListener  ) listeners[i + 1]).stateChanged(changeEvent);
573             }
574         }
575     }
576 
577     /**
578      * Returns the data model used by this progress bar.
579      *
580      * @return the <code>BoundedRangeModel</code> currently in use
581      * @see BoundedRangeModel
582      */
583     public BoundedRangeModel getModel() {
584         return model;
585     }
586 
587     /**
588      * Sets the data model used by the <code>SProgressBar</code>.
589      *
590      * @param newModel the <code>BoundedRangeModel</code> to use
591      * description: The data model used by the SProgressBar.
592      */
593     public void setModel(BoundedRangeModel newModel) {
594         // PENDING(???) setting the same model to multiple bars is broken; listeners
595         BoundedRangeModel oldModel = getModel();
596 
597         if (newModel != oldModel) {
598             if (oldModel != null) {
599                 oldModel.removeChangeListener(changeListener);
600                 changeListener = null;
601             }
602 
603             model = newModel;
604 
605             if (newModel != null) {
606                 changeListener = createChangeListener();
607                 newModel.addChangeListener(changeListener);
608             }
609 
610             if (model != null) {
611                 model.setExtent(0);
612             }
613             reload();
614         }
615     }
616 
617 
618     /* All of the model methods are implemented by delegation. */
619 
620     /**
621      * Returns the progress bar's current value,
622      * which is stored in the progress bar's <code>BoundedRangeModel</code>.
623      * The value is always between the
624      * minimum and maximum values, inclusive. By default, the
625      * value is initialized to be equal to the minimum value.
626      *
627      * @return the current value of the progress bar
628      * @see #setValue
629      * @see BoundedRangeModel#getValue
630      */
631     public int getValue() { return getModel().getValue(); }
632 
633     /**
634      * Returns the progress bar's minimum value,
635      * which is stored in the progress bar's <code>BoundedRangeModel</code>.
636      * By default, the minimum value is <code>0</code>.
637      *
638      * @return the progress bar's minimum value
639      * @see #setMinimum
640      * @see BoundedRangeModel#getMinimum
641      */
642     public int getMinimum() { return getModel().getMinimum(); }
643 
644     /**
645      * Returns the progress bar's maximum value,
646      * which is stored in the progress bar's <code>BoundedRangeModel</code>.
647      * By default, the maximum value is <code>100</code>.
648      *
649      * @return the progress bar's maximum value
650      * @see #setMaximum
651      * @see BoundedRangeModel#getMaximum
652      */
653     public int getMaximum() { return getModel().getMaximum(); }
654 
655     /**
656      * Sets the progress bar's current value
657      * (stored in the progress bar's data model) to <code>n</code>.
658      * The data model (a <code>BoundedRangeModel</code> instance)
659      * handles any mathematical
660      * issues arising from assigning faulty values.
661      * <p/>
662      * If the new value is different from the previous value,
663      * all change listeners are notified.
664      *
665      * @param n the new value
666      * description: The progress bar's current value.
667      * @see #getValue
668      * @see BoundedRangeModel#setValue
669      */
670     public void setValue(int n) {
671         BoundedRangeModel brm = getModel();
672         int oldValue = brm.getValue();
673         brm.setValue(n);
674     }
675 
676     /**
677      * Sets the progress bar's minimum value
678      * (stored in the progress bar's data model) to <code>n</code>.
679      * The data model (a <code>BoundedRangeModel</code> instance)
680      * handles any mathematical
681      * issues arising from assigning faulty values.
682      * <p/>
683      * If the minimum value is different from the previous minimum,
684      * all change listeners are notified.
685      *
686      * @param n the new minimum
687      * description: The progress bar's minimum value.
688      * @see #getMinimum
689      * @see #addChangeListener
690      * @see BoundedRangeModel#setMinimum
691      */
692     public void setMinimum(int n) { getModel().setMinimum(n); }
693 
694     /**
695      * Sets the progress bar's maximum value
696      * (stored in the progress bar's data model) to <code>n</code>.
697      * The underlying <code>BoundedRangeModel</code> handles any mathematical
698      * issues arising from assigning faulty values.
699      * <p/>
700      * If the maximum value is different from the previous maximum,
701      * all change listeners are notified.
702      *
703      * @param n the new maximum
704      * description: The progress bar's maximum value.
705      * @see #getMaximum
706      * @see #addChangeListener
707      * @see BoundedRangeModel#setMaximum
708      */
709     public void setMaximum(int n) { getModel().setMaximum(n); }
710 
711     /**
712      * Sets the <code>indeterminate</code> property of the progress bar,
713      * which determines whether the progress bar is in determinate
714      * or indeterminate mode.
715      * By default, the progress bar is determinate
716      * and this method returns <code>false</code>.
717      * An indeterminate progress bar continuously displays animation
718      * indicating that an operation of unknown length is occurring.
719      * By default, this property is <code>false</code>.
720      * Some look and feels might not support indeterminate progress bars;
721      * they will ignore this property.
722      * <p/>
723      * <p/>
724      * <p/>
725      * See
726      * <a HREF="http://java.sun.com/docs/books/tutorial/uiswing/components/progress.html" target="_top">How to Monitor Progress</a>
727      * for examples of using indeterminate progress bars.
728      *
729      * @param newValue <code>true</code> if the progress bar
730      *                 should change to indeterminate mode;
731      *                 <code>false</code> if it should revert to normal.
732      * @see #isIndeterminate()
733      * @see javax.swing.plaf.basic.BasicProgressBarUI
734      * @since 1.4
735      */
736     public void setIndeterminate(boolean newValue) {
737         boolean oldValue = indeterminate;
738         indeterminate = newValue;
739     }
740 
741     /**
742      * Returns the value of the <code>indeterminate</code> property.
743      *
744      * @return the value of the <code>indeterminate</code> property
745      * or normal (false)?
746      * @see #setIndeterminate
747      * @since 1.4
748      */
749     public boolean isIndeterminate() {
750         return indeterminate;
751     }
752 
753     /**
754      * sets the size of the ProgressBar
755      * @param dimension the size as dimension
756      */
757     public void setProgressBarDimension(SDimension dimension) {
758         progressBarDimension = dimension;
759         
760     }
761 
762     /**
763      * @return the size as dimension if it has been set, else null
764      */
765     public SDimension getProgressBarDimension() {
766         return progressBarDimension;
767     }
768     
769 
770 
771 }// SProgressBar
772 
773
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags