diff options
Diffstat (limited to 'javax/swing/JProgressBar.java')
-rw-r--r-- | javax/swing/JProgressBar.java | 462 |
1 files changed, 308 insertions, 154 deletions
diff --git a/javax/swing/JProgressBar.java b/javax/swing/JProgressBar.java index db936f64a..ed2d0088d 100644 --- a/javax/swing/JProgressBar.java +++ b/javax/swing/JProgressBar.java @@ -53,15 +53,14 @@ import javax.swing.event.ChangeListener; import javax.swing.plaf.ProgressBarUI; /** - * The ProgressBar is a widget that displays in two modes. In - * determinate mode, it displays fills a percentage of its bar - * based on its current value. In indeterminate mode, it creates - * box and bounces it between its bounds. - * + * A component that displays a visual indicator of the progress of a task. The + * component has two modes: determinate and indeterminate. In determinate mode, + * the <code>JProgressBar</code> fills a percentage of its bar based on its + * current value. In indeterminate mode, it creates box and bounces it between + * its bounds. * <p> - * JProgressBars have the following properties: + * This component has the following properties: * </p> - * * <table> * <tr><th> Property </th><th> Stored in </th><th> Bound? </th></tr> * <tr><td> borderPainted </td><td> progressBar </td><td> yes </td></tr> @@ -193,33 +192,67 @@ public class JProgressBar extends JComponent implements SwingConstants, private static final long serialVersionUID = 1980046021813598781L; - /** Whether the ProgressBar is determinate. */ + /** + * A flag that determines the mode (<code>true</code> for indeterminate, + * <code>false</code> for determinate). + */ private transient boolean indeterminate = false; - /** The orientation of the ProgressBar. Always set by constructor. */ + /** + * The orientation of the <code>JProgressBar</code> + * ({@link SwingConstants#HORIZONTAL} or {@link SwingConstants#VERTICAL}). + * Defaults to {@link SwingConstants#HORIZONTAL}. + * @see #setOrientation(int) + */ protected int orientation; - /** Whether borders should be painted. */ + /** + * A flag the controls whether or not the component's border is painted. + * The default is <code>true</code>. + * @see #setBorderPainted(boolean) + */ protected boolean paintBorder = true; - /** The model describing this ProgressBar. */ + /** + * The model defining the bounds and current value for the progress bar. + * @see #setModel(BoundedRangeModel) + */ protected BoundedRangeModel model; - /** The string that is displayed by the ProgressBar. */ + /** + * A custom string for display in the progress bar. If this is + * <code>null</code>, a default string will be generated. + * @see #setString(String) + */ protected String progressString; - /** Whether the string should be painted. */ + /** + * A flag that controls whether a string is displayed within the progress + * bar. + * @see #setStringPainted(boolean) + */ protected boolean paintString = false; - /** The static changeEvent passed to all ChangeListeners. */ + /** + * A single change event reused for all events. + * @see #fireStateChanged() + */ protected transient ChangeEvent changeEvent; - /** The ChangeListener that listens to the model. */ + /** + * The listener that is registered with the model. */ protected ChangeListener changeListener; /** - * Creates a new horizontally oriented JProgressBar object - * with a minimum of 0 and a maximum of 100. + * Creates a new <code>JProgressBar</code> with default attributes. The + * following defaults are used: + * <p> + * <ul> + * <li><code>value</code>: 0;</li> + * <li><code>minimum</code>: 0;</li> + * <li><code>maximum</code>: 100;</li> + * <li><code>orientation</code>: {@link SwingConstants#HORIZONTAL}.</li> + * </ul> */ public JProgressBar() { @@ -227,13 +260,20 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * Creates a new JProgressBar object with a minimum of 0, - * a maximum of 100, and the given orientation. - * - * @param orientation The orientation of the JProgressBar. + * Creates a new <code>JProgressBar</code> with the specified + * <code>orientation</code>. The following defaults are used: + * <p> + * <ul> + * <li><code>value</code>: 0;</li> + * <li><code>minimum</code>: 0;</li> + * <li><code>maximum</code>: 100;</li> + * </ul> * - * @throws IllegalArgumentException if <code>orientation</code> is not either - * {@link #HORIZONTAL} or {@link #VERTICAL}. + * @param orientation the orientation ({@link #HORIZONTAL} or + * {@link #VERTICAL}). + * + * @throws IllegalArgumentException if <code>orientation</code> is not one of + * the specified values. */ public JProgressBar(int orientation) { @@ -241,11 +281,16 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * Creates a new horizontally oriented JProgressBar object - * with the given minimum and maximum. - * - * @param minimum The minimum of the JProgressBar. - * @param maximum The maximum of the JProgressBar. + * Creates a new <code>JProgressBar</code> with the specified value range. + * The following defaults are used: + * <p> + * <ul> + * <li><code>value</code>: <code>minimum</code>;</li> + * <li><code>orientation</code>: {@link SwingConstants#HORIZONTAL}.</li> + * </ul> + * + * @param minimum the lower bound of the value range. + * @param maximum the upper bound of the value range. */ public JProgressBar(int minimum, int maximum) { @@ -253,15 +298,20 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * Creates a new JProgressBar object with the given minimum, - * maximum, and orientation. - * - * @param minimum The minimum of the JProgressBar. - * @param maximum The maximum of the JProgressBar. - * @param orientation The orientation of the JProgressBar. + * Creates a new <code>JProgressBar</code> with the specified range and + * orientation. The following defaults are used: + * <p> + * <ul> + * <li><code>value</code>: <code>minimum</code>;</li> + * </ul> + * + * @param minimum the lower bound of the value range. + * @param maximum the upper bound of the value range. + * @param orientation the orientation ({@link #HORIZONTAL} or + * {@link #VERTICAL}). * - * @throws IllegalArgumentException if <code>orientation</code> is not either - * {@link #HORIZONTAL} or {@link #VERTICAL}. + * @throws IllegalArgumentException if <code>orientation</code> is not one of + * the specified values. */ public JProgressBar(int orientation, int minimum, int maximum) { @@ -276,10 +326,14 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * Creates a new horizontally oriented JProgressBar object - * with the given model. - * - * @param model The model to be used with the JProgressBar. + * Creates a new <code>JProgressBar</code> with the specified model. The + * following defaults are used: + * <p> + * <ul> + * <li><code>orientation</code>: {@link SwingConstants#HORIZONTAL}.</li> + * </ul> + * + * @param model the model (<code>null</code> not permitted). */ public JProgressBar(BoundedRangeModel model) { @@ -291,9 +345,12 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method returns the current value of the JProgressBar. + * Returns the current value for the <code>JProgressBar</code>. This value + * is fetched from the model. * - * @return The current value of the JProgressBar. + * @return The current value. + * + * @see #setValue(int) */ public int getValue() { @@ -301,9 +358,20 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method sets the value of the JProgressBar. + * Sets the current value for the <code>JProgressBar</code>. The value is + * stored in the component's <code>model</code> (see {@link #getModel()}). + * If the new value is different to the old value, a {@link ChangeEvent} is + * sent to the model's registered listeners. In turn, this triggers a call + * to {@link #fireStateChanged()} which will send a <code>ChangeEvent</code> + * to this component's registered listeners. + * <p> + * If <code>value</code> is outside the range <code>minimum</code> to + * <code>maximum</code>, it will be set to the nearest of those boundary + * values. * - * @param value The value of the JProgressBar. + * @param value the new value. + * + * @see #getValue() */ public void setValue(int value) { @@ -311,23 +379,29 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method paints the border of the JProgressBar + * Paints the component's border, but only if {@link #isBorderPainted()} + * returns <code>true</code>. * - * @param graphics The graphics object to paint with. + * @param graphics the graphics object to paint with. + * + * @see #setBorderPainted(boolean) */ protected void paintBorder(Graphics graphics) { Border border = getBorder(); if (paintBorder && border != null) - border.paintBorder(this, graphics, 0, 0, - getWidth(), - getHeight()); + border.paintBorder(this, graphics, 0, 0, getWidth(), getHeight()); } /** - * This method returns the orientation of the JProgressBar. + * Returns the orientation of the <code>JProgressBar</code> component, which + * is either {@link SwingConstants#HORIZONTAL} or + * {@link SwingConstants#VERTICAL}. The default orientation is + * <code>HORIZONTAL</code>. * - * @return The orientation of the JProgressBar. + * @return The orientation. + * + * @see #setOrientation(int) */ public int getOrientation() { @@ -335,12 +409,17 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the orientation property. The orientation of the - * JProgressBar can be either horizontal or vertical. + * Sets the orientation for this <code>JProgressBar</code> component and, + * if the value changes, sends a {@link PropertyChangeEvent} (with the + * property name <code>"orientation"</code>) to all registered listeners. * - * @param orientation The orientation of the JProgressBar. + * @param orientation the orientation ({@link #HORIZONTAL} or + * {@link #VERTICAL}). + * * @throws IllegalArgumentException if <code>orientation</code> is not - * either {@link #HORIZONTAL} or {@link #VERTICAL}. + * one of the listed values. + * + * @see #getOrientation() */ public void setOrientation(int orientation) { @@ -349,17 +428,21 @@ public class JProgressBar extends JComponent implements SwingConstants, + " is not a legal orientation"); if (this.orientation != orientation) { - int oldOrientation = this.orientation; - this.orientation = orientation; - firePropertyChange("orientation", oldOrientation, - this.orientation); + int oldOrientation = this.orientation; + this.orientation = orientation; + firePropertyChange("orientation", oldOrientation, this.orientation); } } /** - * This method returns whether the progressString will be painted. + * Returns the flag that controls whether or not the string returned by + * {@link #getString()} is displayed by the <code>JProgressBar</code> + * component. * - * @return Whether the string is painted. + * @return <code>true</code> if the string should be displayed, and + * <code>false</code> otherwise. + * + * @see #setStringPainted(boolean) */ public boolean isStringPainted() { @@ -367,28 +450,37 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the stringPainted property. + * Sets the flag that controls whether or not the string returned by + * {@link #getString()} is displayed by the <code>JProgressBar</code> + * component. If the flag value changes, a {@link PropertyChangeEvent} (with + * the property name <code>"stringPainted"</code>) is sent to all registered + * listeners. * - * @param painted Whether the string is painted. + * @param painted the new flag value. + * + * @see #isStringPainted() + * @see #setString(String) */ public void setStringPainted(boolean painted) { if (paintString != painted) { - boolean oldPainted = paintString; - paintString = painted; - firePropertyChange("stringPainted", oldPainted, - paintString); + boolean oldPainted = paintString; + paintString = painted; + firePropertyChange("stringPainted", oldPainted, paintString); } } /** - * This method returns the string that is painted if the - * stringPainted property is set to true. If there is no - * string set, it will return a string containing the - * JProgressBar's value as a percent. + * Returns the string that is painted on the <code>JProgressBar</code> if + * {@link #isStringPainted()} returns <code>true</code>. If no string has + * been explicitly set, this method will return a string displaying the + * value of {@link #getPercentComplete()}. * - * @return The string that is painted. + * @return The string. + * + * @see #setString(String) + * @see #setStringPainted(boolean) */ public String getString() { @@ -399,12 +491,16 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the string property. The string - * given will be the one painted. If you want to - * revert to the default string given, set the - * string to null. + * Sets the string to display within the progress bar and, if the new value + * is different to the old value, sends a {@link PropertyChangeEvent} (with + * the property name <code>"string"</code>) to all registered listeners. If + * the string is set to <code>null</code>, {@link #getString()} will return + * a default string. * - * @param string The string to be painted. + * @param string the string (<code>null</code> permitted). + * + * @see #getString() + * @see #setStringPainted(boolean) */ public void setString(String string) { @@ -412,32 +508,35 @@ public class JProgressBar extends JComponent implements SwingConstants, string != progressString) || (string != null && ! string.equals(progressString))) { - String oldString = progressString; - progressString = string; - firePropertyChange("string", oldString, progressString); + String oldString = progressString; + progressString = string; + firePropertyChange("string", oldString, progressString); } } /** - * This method returns the percent of the bar - * that is "complete". (This is the amount value / (max - min)). + * Returns the current value expressed as a percentage. This is calculated + * as <code>(value - min) / (max - min)</code>. * - * @return DOCUMENT ME! + * @return The percentage (a value in the range 0.0 to 1.0). */ public double getPercentComplete() { if (getMaximum() == getMinimum()) return 1.0; else - return (double) (model.getValue() - model.getMinimum()) / (model - .getMaximum() - - model.getMinimum()); + return (double) (model.getValue() - model.getMinimum()) + / (model.getMaximum() - model.getMinimum()); } /** - * This method returns whether the border is painted. + * Returns a flag that controls whether or not the component's border is + * painted. The default value is <code>true</code>. * - * @return Whether the border is painted. + * @return <code>true</code> if the component's border should be painted, + * and <code>false</code> otherwise. + * + * @see #setBorderPainted(boolean) */ public boolean isBorderPainted() { @@ -445,25 +544,30 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the borderPainted property. + * Sets the flag that controls whether or not the component's border is + * painted. If the flag value is changed, this method sends a + * {@link PropertyChangeEvent} (with the property name "borderPainted") to + * all registered listeners. * - * @param painted Whether the border is painted. + * @param painted the new flag value. + * + * @see #isBorderPainted() + * @see #paintBorder */ public void setBorderPainted(boolean painted) { if (painted != paintBorder) { - boolean oldPainted = paintBorder; - paintBorder = painted; - firePropertyChange("borderPainted", oldPainted, - paintBorder); + boolean oldPainted = paintBorder; + paintBorder = painted; + firePropertyChange("borderPainted", oldPainted, paintBorder); } } /** - * This method returns the JProgressBar's UI delegate. + * Returns the UI delegate for this <code>JProgressBar</code>. * - * @return This JProgressBar's UI delegate. + * @return The UI delegate. */ public ProgressBarUI getUI() { @@ -471,9 +575,9 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the UI property for this JProgressBar. + * Sets the UI delegate for this component. * - * @param ui The new UI delegate. + * @param ui the new UI delegate. */ public void setUI(ProgressBarUI ui) { @@ -481,8 +585,8 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method reverts the UI delegate for this JProgressBar - * to the default for this Look and Feel. + * Sets this <code>JProgressBar</code>'s UI delegate to the default + * (obtained from the {@link UIManager}) for the current look and feel. */ public void updateUI() { @@ -490,11 +594,11 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method returns the identifier to allow the UIManager - * to pick the correct class to act as the UI for - * this JProgressBar. + * Returns the suffix (<code>"ProgressBarUI"</code> in this case) used to + * determine the class name for a UI delegate that can provide the look and + * feel for a <code>JProgressBar</code>. * - * @return The UIClassID: "ProgressBarUI". + * @return <code>"ProgressBarUI"</code>. */ public String getUIClassID() { @@ -502,27 +606,33 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method returns a ChangeListener that gets registered - * model. By default, the ChangeListener, propagates the - * ChangeEvents to the ChangeListeners of the JProgressBar. + * Creates a new {@link ChangeListener} that calls + * {@link #fireStateChanged()} whenever it receives a {@link ChangeEvent} + * (typically from the component's <code>model</code>). This listener is + * registered with the progress bar's model, so that changes made to the + * model directly will automatically result in the progress bar's listeners + * being notified also. * - * @return A new ChangeListener. + * @return A new listener. */ protected ChangeListener createChangeListener() { return new ChangeListener() { - public void stateChanged(ChangeEvent ce) - { - fireStateChanged(); - } + public void stateChanged(ChangeEvent ce) + { + fireStateChanged(); + } }; } /** - * This method adds a ChangeListener to this JProgressBar. + * Registers a listener with this component so that it will receive + * notification of component state changes. * - * @param listener The ChangeListener to add to this JProgressBar. + * @param listener the listener. + * + * @see #removeChangeListener(ChangeListener) */ public void addChangeListener(ChangeListener listener) { @@ -530,9 +640,12 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method removes a ChangeListener from this JProgressBar. + * Deregisters a listener so that it no longer receives notification of + * component state changes. * - * @param listener The ChangeListener to remove from this JProgressBar. + * @param listener the listener. + * + * @see #addChangeListener(ChangeListener) */ public void removeChangeListener(ChangeListener listener) { @@ -540,10 +653,12 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method returns an array of all ChangeListeners listening to this - * progress bar. + * Returns an array of the listeners that are registered with this component. + * The array may be empty, but is never <code>null</code>. * - * @return An array of ChangeListeners listening to this progress bar. + * @return An array of listeners. + * + * @since 1.4 */ public ChangeListener[] getChangeListeners() { @@ -551,9 +666,10 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method is called when the JProgressBar receives a ChangeEvent - * from its model. This simply propagates the event (changing the source - * to the JProgressBar) to the JProgressBar's listeners. + * Sends a {@link ChangeEvent} to all registered listeners to indicate that + * the state of the <code>JProgressBar</code> has changed. + * + * @see #createChangeListener() */ protected void fireStateChanged() { @@ -562,15 +678,17 @@ public class JProgressBar extends JComponent implements SwingConstants, changeEvent = new ChangeEvent(this); for (int i = changeListeners.length - 2; i >= 0; i -= 2) { - if (changeListeners[i] == ChangeListener.class) - ((ChangeListener) changeListeners[i + 1]).stateChanged(changeEvent); + if (changeListeners[i] == ChangeListener.class) + ((ChangeListener) changeListeners[i + 1]).stateChanged(changeEvent); } } /** - * This method returns the model used with this JProgressBar. + * Returns the model for the <code>JProgressBar</code>. * - * @return The model used with this JProgressBar. + * @return The model (never <code>null</code>). + * + * @see #setModel(BoundedRangeModel) */ public BoundedRangeModel getModel() { @@ -578,25 +696,32 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the model property for this JProgressBar. + * Sets the model for the <code>JProgressBar</code> and sends a + * {@link ChangeEvent} to all registered listeners. * - * @param model The model to use with this JProgressBar. + * @param model the model (<code>null</code> not permitted). + * + * @see #getModel() */ public void setModel(BoundedRangeModel model) { if (model != this.model) { this.model.removeChangeListener(changeListener); - this.model = model; - this.model.addChangeListener(changeListener); - fireStateChanged(); + this.model = model; + this.model.addChangeListener(changeListener); + fireStateChanged(); } } /** - * This method returns the minimum value of this JProgressBar. + * Returns the minimum value for the <code>JProgressBar</code>. This defines + * the lower bound for the current value, and is stored in the component's + * <code>model</code>. * - * @return The minimum value of this JProgressBar. + * @return The minimum value. + * + * @see #setMinimum(int) */ public int getMinimum() { @@ -604,9 +729,16 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method sets the minimum value of this JProgressBar. - * - * @param minimum The minimum value of this JProgressBar. + * Sets the minimum value for the <code>JProgressBar</code>. The value is + * stored in the component's <code>model</code> (see {@link #getModel()}). + * If the new value is different to the old value, a {@link ChangeEvent} is + * sent to the model's registered listeners. In turn, this triggers a call + * to {@link #fireStateChanged()} which will send a <code>ChangeEvent</code> + * to this component's registered listeners. + * + * @param minimum the minimum value. + * + * @see #getMinimum() */ public void setMinimum(int minimum) { @@ -614,9 +746,13 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method returns the maximum value of this JProgressBar. + * Returns the maximum value for the <code>JProgressBar</code>. This defines + * the upper bound for the current value, and is stored in the component's + * <code>model</code>. * - * @return The maximum value of this JProgressBar. + * @return The maximum value. + * + * @see #setMaximum(int) */ public int getMaximum() { @@ -624,9 +760,16 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method sets the maximum value of this JProgressBar. + * Sets the maximum value for the <code>JProgressBar</code>. The value is + * stored in the component's <code>model</code> (see {@link #getModel()}). + * If the new value is different to the old value, a {@link ChangeEvent} is + * sent to the model's registered listeners. In turn, this triggers a call + * to {@link #fireStateChanged()} which will send a <code>ChangeEvent</code> + * to this component's registered listeners. * - * @param maximum The maximum value of this JProgressBar. + * @param maximum the maximum value. + * + * @see #getMaximum() */ public void setMaximum(int maximum) { @@ -659,29 +802,40 @@ public class JProgressBar extends JComponent implements SwingConstants, } /** - * This method changes the indeterminate property. If the - * JProgressBar is determinate, it paints a percentage - * of the bar described by its value. If it is indeterminate, - * it simply bounces a box between the ends of the bar; the - * value of the JProgressBar is ignored. + * Sets the flag that controls the mode for this <code>JProgressBar</code> + * (<code>true</code> for indeterminate mode, and <code>false</code> for + * determinate mode). If the flag value changes, this method sends a + * {@link PropertyChangeEvent} (with the property name + * <code>"indeterminate"</code>) to all registered listeners. + * <p> + * If the <code>JProgressBar</code> is determinate, it paints a percentage + * of the bar described by its value. If it is indeterminate, it simply + * bounces a box between the ends of the bar; the value of the + * <code>JProgressBar</code> is ignored. * - * @param newValue Whether the JProgressBar is indeterminate. + * @param flag the new flag value. + * + * @see #isIndeterminate() + * @since 1.4 */ - public void setIndeterminate(boolean newValue) + public void setIndeterminate(boolean flag) { - if (indeterminate != newValue) + if (indeterminate != flag) { - boolean olddeter = indeterminate; - indeterminate = newValue; - firePropertyChange("indeterminate", olddeter, - indeterminate); + indeterminate = flag; + firePropertyChange("indeterminate", !flag, indeterminate); } } /** - * This method returns whether the JProgressBar is indeterminate. + * Returns a flag that indicates the mode for this <code>JProgressBar</code> + * (<code>true</code> for indeterminate mode, and <code>false</code> for + * determinate mode). * - * @return Whether this JProgressBar is indeterminate. + * @return A flag indicating the mode for the <code>JProgressBar</code>. + * + * @see #setIndeterminate(boolean) + * @since 1.4 */ public boolean isIndeterminate() { |