javax.swing

Class JProgressBar

public class JProgressBar extends JComponent implements SwingConstants, Accessible

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 JProgressBar fills a percentage of its bar based on its current value. In indeterminate mode, it creates box and bounces it between its bounds.

This component has the following properties:

Property	Stored in	Bound?
borderPainted	progressBar	yes
changeListeners	progressBar	no
indeterminate	progressBar	yes
maximum	model	no
minimum	model	no
model	progressBar	no
orientation	progressBar	yes
percentComplete	progressBar	no
string	progressBar	yes
stringPainted	progressBar	yes
value	model	no

Nested Class Summary
protected class	JProgressBar.AccessibleJProgressBar Provides the accessibility features for the `JProgressBar` component.

Field Summary
protected ChangeEvent	changeEvent A single change event reused for all events.
protected ChangeListener	changeListener The listener that is registered with the model.
protected BoundedRangeModel	model The model defining the bounds and current value for the progress bar.
protected int	orientation The orientation of the `JProgressBar` ({@link SwingConstants#HORIZONTAL} or {@link SwingConstants#VERTICAL}).
protected boolean	paintBorder A flag the controls whether or not the component's border is painted.
protected boolean	paintString A flag that controls whether a string is displayed within the progress bar.
protected String	progressString A custom string for display in the progress bar.

Constructor Summary
	JProgressBar() Creates a new `JProgressBar` with default attributes.
	JProgressBar(int orientation) Creates a new `JProgressBar` with the specified `orientation`.
	JProgressBar(int minimum, int maximum) Creates a new `JProgressBar` with the specified value range.
	JProgressBar(int orientation, int minimum, int maximum) Creates a new `JProgressBar` with the specified range and orientation.
	JProgressBar(BoundedRangeModel model) Creates a new `JProgressBar` with the specified model.

Method Summary
void	addChangeListener(ChangeListener listener) Registers a listener with this component so that it will receive notification of component state changes.
protected ChangeListener	createChangeListener() Creates a new {@link ChangeListener} that calls {@link #fireStateChanged()} whenever it receives a {@link ChangeEvent} (typically from the component's `model`).
protected void	fireStateChanged() Sends a {@link ChangeEvent} to all registered listeners to indicate that the state of the `JProgressBar` has changed.
AccessibleContext	getAccessibleContext() Returns the object that provides accessibility features for this `JProgressBar` component.
ChangeListener[]	getChangeListeners() Returns an array of the listeners that are registered with this component.
int	getMaximum() Returns the maximum value for the `JProgressBar`.
int	getMinimum() Returns the minimum value for the `JProgressBar`.
BoundedRangeModel	getModel() Returns the model for the `JProgressBar`.
int	getOrientation() Returns the orientation of the `JProgressBar` component, which is either {@link SwingConstants#HORIZONTAL} or {@link SwingConstants#VERTICAL}.
double	getPercentComplete() Returns the current value expressed as a percentage.
String	getString() Returns the string that is painted on the `JProgressBar` if {@link #isStringPainted()} returns `true`.
ProgressBarUI	getUI() Returns the UI delegate for this `JProgressBar`.
String	getUIClassID() Returns the suffix (`"ProgressBarUI"` in this case) used to determine the class name for a UI delegate that can provide the look and feel for a `JProgressBar`.
int	getValue() Returns the current value for the `JProgressBar`.
boolean	isBorderPainted() Returns a flag that controls whether or not the component's border is painted.
boolean	isIndeterminate() Returns a flag that indicates the mode for this `JProgressBar` (`true` for indeterminate mode, and `false` for determinate mode).
boolean	isStringPainted() Returns the flag that controls whether or not the string returned by {@link #getString()} is displayed by the `JProgressBar` component.
protected void	paintBorder(Graphics graphics) Paints the component's border, but only if {@link #isBorderPainted()} returns `true`.
protected String	paramString() Returns an implementation-dependent string describing the attributes of this `JProgressBar`.
void	removeChangeListener(ChangeListener listener) Deregisters a listener so that it no longer receives notification of component state changes.
void	setBorderPainted(boolean painted) Sets the flag that controls whether or not the component's border is painted.
void	setIndeterminate(boolean flag) Sets the flag that controls the mode for this `JProgressBar` (`true` for indeterminate mode, and `false` for determinate mode).
void	setMaximum(int maximum) Sets the maximum value for the `JProgressBar`.
void	setMinimum(int minimum) Sets the minimum value for the `JProgressBar`.
void	setModel(BoundedRangeModel model) Sets the model for the `JProgressBar` and sends a {@link ChangeEvent} to all registered listeners.
void	setOrientation(int orientation) Sets the orientation for this `JProgressBar` component and, if the value changes, sends a {@link PropertyChangeEvent} (with the property name `"orientation"`) to all registered listeners.
void	setString(String string) 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 `"string"`) to all registered listeners.
void	setStringPainted(boolean painted) Sets the flag that controls whether or not the string returned by {@link #getString()} is displayed by the `JProgressBar` component.
void	setUI(ProgressBarUI ui) Sets the UI delegate for this component.
void	setValue(int value) Sets the current value for the `JProgressBar`.
void	updateUI() Sets this `JProgressBar`'s UI delegate to the default (obtained from the {@link UIManager}) for the current look and feel.

Field Detail

changeEvent

protected transient ChangeEvent changeEvent

A single change event reused for all events.

changeListener

protected ChangeListener changeListener

The listener that is registered with the model.

model

protected BoundedRangeModel model

The model defining the bounds and current value for the progress bar.

orientation

protected int orientation

The orientation of the JProgressBar ({@link SwingConstants#HORIZONTAL} or {@link SwingConstants#VERTICAL}). Defaults to {@link SwingConstants#HORIZONTAL}.

See Also: JProgressBar

paintBorder

protected boolean paintBorder

A flag the controls whether or not the component's border is painted. The default is true.

See Also: JProgressBar

paintString

protected boolean paintString

A flag that controls whether a string is displayed within the progress bar.

See Also: JProgressBar

progressString

protected String progressString

A custom string for display in the progress bar. If this is null, a default string will be generated.

Constructor Detail

JProgressBar

public JProgressBar()

Creates a new JProgressBar with default attributes. The following defaults are used:

value: 0;
minimum: 0;
maximum: 100;
orientation: {@link SwingConstants#HORIZONTAL}.

JProgressBar

public JProgressBar(int orientation)

Creates a new JProgressBar with the specified orientation. The following defaults are used:

value: 0;
minimum: 0;
maximum: 100;

Parameters: orientation the orientation ({@link #HORIZONTAL} or {@link #VERTICAL}).

Throws: IllegalArgumentException if orientation is not one of the specified values.

JProgressBar

public JProgressBar(int minimum, int maximum)

Creates a new JProgressBar with the specified value range. The following defaults are used:

value: minimum;
orientation: {@link SwingConstants#HORIZONTAL}.

Parameters: minimum the lower bound of the value range. maximum the upper bound of the value range.

JProgressBar

public JProgressBar(int orientation, int minimum, int maximum)

Creates a new JProgressBar with the specified range and orientation. The following defaults are used:

value: minimum;

Parameters: minimum the lower bound of the value range. maximum the upper bound of the value range. orientation the orientation ({@link #HORIZONTAL} or {@link #VERTICAL}).

Throws: IllegalArgumentException if orientation is not one of the specified values.

JProgressBar

public JProgressBar(BoundedRangeModel model)

Creates a new JProgressBar with the specified model. The following defaults are used:

orientation: {@link SwingConstants#HORIZONTAL}.

Parameters: model the model (null not permitted).

Method Detail

addChangeListener

public void addChangeListener(ChangeListener listener)

Registers a listener with this component so that it will receive notification of component state changes.

Parameters: listener the listener.

createChangeListener

protected ChangeListener createChangeListener()

Creates a new {@link ChangeListener} that calls {@link #fireStateChanged()} whenever it receives a {@link ChangeEvent} (typically from the component's model). 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.

Returns: A new listener.

fireStateChanged

protected void fireStateChanged()

Sends a {@link ChangeEvent} to all registered listeners to indicate that the state of the JProgressBar has changed.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Returns the object that provides accessibility features for this JProgressBar component.

Returns: The accessible context (an instance of {@link AccessibleJProgressBar}).

getChangeListeners

public ChangeListener[] getChangeListeners()

Returns an array of the listeners that are registered with this component. The array may be empty, but is never null.

Returns: An array of listeners.

Since: 1.4

getMaximum

public int getMaximum()

Returns the maximum value for the JProgressBar. This defines the upper bound for the current value, and is stored in the component's model.

Returns: The maximum value.

See Also: JProgressBar

getMinimum

public int getMinimum()

Returns the minimum value for the JProgressBar. This defines the lower bound for the current value, and is stored in the component's model.

Returns: The minimum value.

See Also: JProgressBar

getModel

public BoundedRangeModel getModel()

Returns the model for the JProgressBar.

Returns: The model (never null).

getOrientation

public int getOrientation()

Returns the orientation of the JProgressBar component, which is either {@link SwingConstants#HORIZONTAL} or {@link SwingConstants#VERTICAL}. The default orientation is HORIZONTAL.

Returns: The orientation.

See Also: JProgressBar

getPercentComplete

public double getPercentComplete()

Returns the current value expressed as a percentage. This is calculated as (value - min) / (max - min).

Returns: The percentage (a value in the range 0.0 to 1.0).

getString

public String getString()

Returns the string that is painted on the JProgressBar if {@link #isStringPainted()} returns true. If no string has been explicitly set, this method will return a string displaying the value of {@link #getPercentComplete()}.

Returns: The string.

getUI

public ProgressBarUI getUI()

Returns the UI delegate for this JProgressBar.

Returns: The UI delegate.

getUIClassID

public String getUIClassID()

Returns the suffix ("ProgressBarUI" in this case) used to determine the class name for a UI delegate that can provide the look and feel for a JProgressBar.

Returns: "ProgressBarUI".

getValue

public int getValue()

Returns the current value for the JProgressBar. This value is fetched from the model.

Returns: The current value.

See Also: JProgressBar

isBorderPainted

public boolean isBorderPainted()

Returns a flag that controls whether or not the component's border is painted. The default value is true.

Returns: true if the component's border should be painted, and false otherwise.

See Also: JProgressBar

isIndeterminate

public boolean isIndeterminate()

Returns a flag that indicates the mode for this JProgressBar (true for indeterminate mode, and false for determinate mode).

Returns: A flag indicating the mode for the JProgressBar.

Since: 1.4

See Also: JProgressBar

isStringPainted

public boolean isStringPainted()

Returns the flag that controls whether or not the string returned by {@link #getString()} is displayed by the JProgressBar component.

Returns: true if the string should be displayed, and false otherwise.

See Also: JProgressBar

paintBorder

protected void paintBorder(Graphics graphics)

Paints the component's border, but only if {@link #isBorderPainted()} returns true.

Parameters: graphics the graphics object to paint with.

See Also: JProgressBar

paramString

protected String paramString()

Returns an implementation-dependent string describing the attributes of this JProgressBar.

Returns: A string describing the attributes of this JProgressBar (never null).

removeChangeListener

public void removeChangeListener(ChangeListener listener)

Deregisters a listener so that it no longer receives notification of component state changes.

Parameters: listener the listener.

setBorderPainted

public void setBorderPainted(boolean painted)

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.

Parameters: painted the new flag value.

setIndeterminate

public void setIndeterminate(boolean flag)

Sets the flag that controls the mode for this JProgressBar (true for indeterminate mode, and false for determinate mode). If the flag value changes, this method sends a {@link PropertyChangeEvent} (with the property name "indeterminate") to all registered listeners.

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.

Parameters: flag the new flag value.

Since: 1.4

setMaximum

public void setMaximum(int maximum)

Sets the maximum value for the JProgressBar. The value is stored in the component's model (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 ChangeEvent to this component's registered listeners.

Parameters: maximum the maximum value.

setMinimum

public void setMinimum(int minimum)

Sets the minimum value for the JProgressBar. The value is stored in the component's model (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 ChangeEvent to this component's registered listeners.

Parameters: minimum the minimum value.

setModel

public void setModel(BoundedRangeModel model)

Sets the model for the JProgressBar and sends a {@link ChangeEvent} to all registered listeners.

Parameters: model the model (null not permitted).

setOrientation

public void setOrientation(int orientation)

Sets the orientation for this JProgressBar component and, if the value changes, sends a {@link PropertyChangeEvent} (with the property name "orientation") to all registered listeners.

Parameters: orientation the orientation ({@link #HORIZONTAL} or {@link #VERTICAL}).

Throws: IllegalArgumentException if orientation is not one of the listed values.

setString

public void setString(String string)

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 "string") to all registered listeners. If the string is set to null, {@link #getString()} will return a default string.

Parameters: string the string (null permitted).

setStringPainted

public void setStringPainted(boolean painted)

Sets the flag that controls whether or not the string returned by {@link #getString()} is displayed by the JProgressBar component. If the flag value changes, a {@link PropertyChangeEvent} (with the property name "stringPainted") is sent to all registered listeners.

Parameters: painted the new flag value.

setUI

public void setUI(ProgressBarUI ui)

Sets the UI delegate for this component.

Parameters: ui the new UI delegate.

setValue

public void setValue(int value)

Sets the current value for the JProgressBar. The value is stored in the component's model (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 ChangeEvent to this component's registered listeners.

If value is outside the range minimum to maximum, it will be set to the nearest of those boundary values.

Parameters: value the new value.

updateUI

public void updateUI()

Sets this JProgressBar's UI delegate to the default (obtained from the {@link UIManager}) for the current look and feel.