KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > wings > 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 JavaDoc;
20 import javax.swing.event.ChangeListener JavaDoc;
21 import java.awt.*;
22 import java.io.Serializable JavaDoc;
23 import java.text.Format JavaDoc;
24 import java.text.NumberFormat JavaDoc;
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 JavaDoc STRING_PROPERTY = "_String_Property";
39     public static final String JavaDoc STRING_PAINTED_PROPERTY = "_String_Painted_Property";
40     public static final String JavaDoc BORDER_PAINTED_PROPERTY = "_Border_Painted_Property";
41     public static final String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc changeListener = null;
119
120     /**
121      * Format used when displaying percent complete.
122      */

123     private transient Format JavaDoc 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 JavaDoc(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 JavaDoc 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 JavaDoc(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 JavaDoc s) {
386         String JavaDoc 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 JavaDoc, Serializable JavaDoc {
504         public void stateChanged(ChangeEvent JavaDoc 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 JavaDoc 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 JavaDoc l) {
530         addEventListener(ChangeListener JavaDoc.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 JavaDoc l) {
539         removeEventListener(ChangeListener JavaDoc.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 JavaDoc[] getChangeListeners() {
551         return (ChangeListener JavaDoc[]) getListeners(ChangeListener JavaDoc.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 JavaDoc[] 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 JavaDoc.class) {
569                 // Lazily create the event:
570
if (changeEvent == null)
571                     changeEvent = new ChangeEvent JavaDoc(this);
572                 ((ChangeListener JavaDoc) 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
Popular Tags