Class JProgressBar
- All Implemented Interfaces:
ImageObserver,MenuContainer,Serializable,Accessible,SwingConstants
JProgressBar uses a BoundedRangeModel as its data model,
with the value property representing the "current" state of the task,
and the minimum and maximum properties representing the
beginning and end points, respectively.
To indicate that a task of unknown length is executing, you can put a progress bar into indeterminate mode. While the bar is in indeterminate mode, it animates constantly to show that work is occurring. As soon as you can determine the task's length and amount of progress, you should update the progress bar's value and switch it back to determinate mode.
Here is an example of creating a progress bar,
where task is an object (representing some piece of work)
which returns information about the progress of the task:
progressBar = new JProgressBar(0, task.getLengthOfTask()); progressBar.setValue(0); progressBar.setStringPainted(true);Here is an example of querying the current state of the task, and using the returned value to update the progress bar:
progressBar.setValue(task.getCurrent());Here is an example of putting a progress bar into indeterminate mode, and then switching back to determinate mode once the length of the task is known:
progressBar = new JProgressBar(); ...//when the task of (initially) unknown length begins: progressBar.setIndeterminate(true); ...//do some work; get length of task... progressBar.setMaximum(newLength); progressBar.setValue(newValue); progressBar.setIndeterminate(false);
For complete examples and further documentation see How to Monitor Progress, a section in The Java Tutorial.
Warning: Swing is not thread safe. For more information see Swing's Threading Policy.
Warning:
Serialized objects of this class will not be compatible with
future Swing releases. The current serialization support is
appropriate for short term storage or RMI between applications running
the same version of Swing. As of 1.4, support for long term storage
of all JavaBeans
has been added to the java.beans package.
Please see XMLEncoder.
- Since:
- 1.2
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected classThis class implements accessibility support for theJProgressBarclass.Nested classes/interfaces declared in class javax.swing.JComponent
JComponent.AccessibleJComponentNested classes/interfaces declared in class java.awt.Container
Container.AccessibleAWTContainerNested classes/interfaces declared in class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected ChangeEventOnly oneChangeEventis needed per instance since the event's only interesting property is the immutable source, which is the progress bar.protected ChangeListenerListens for change events sent by the progress bar's model, redispatching them to change-event listeners registered upon this progress bar.protected BoundedRangeModelThe object that holds the data for the progress bar.protected intWhether the progress bar is horizontal or vertical.protected booleanWhether to display a border around the progress bar.protected booleanWhether to display a string of text on the progress bar.protected StringAn optional string that can be displayed on the progress bar.Fields declared in class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOWFields declared in class java.awt.Component
accessibleContext, BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENTFields declared in interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTHFields declared in interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST -
Constructor Summary
ConstructorsConstructorDescriptionCreates a horizontal progress bar that displays a border but no progress string.JProgressBar(int orient) Creates a progress bar with the specified orientation, which can be eitherSwingConstants.VERTICALorSwingConstants.HORIZONTAL.JProgressBar(int min, int max) Creates a horizontal progress bar with the specified minimum and maximum.JProgressBar(int orient, int min, int max) Creates a progress bar using the specified orientation, minimum, and maximum.JProgressBar(BoundedRangeModel newModel) Creates a horizontal progress bar that uses the specified model to hold the progress bar's data. -
Method Summary
Modifier and TypeMethodDescriptionvoidAdds the specifiedChangeListenerto the progress bar.protected ChangeListenerSubclasses that want to handle change events from the model differently can override this to return an instance of a customChangeListenerimplementation.protected voidSend aChangeEvent, whose source is thisJProgressBar, to allChangeListeners that have registered interest inChangeEvents.Gets theAccessibleContextassociated with thisJProgressBar.Returns an array of all theChangeListeners added to this progress bar withaddChangeListener.intReturns the progress bar'smaximumvalue from theBoundedRangeModel.intReturns the progress bar'sminimumvalue from theBoundedRangeModel.getModel()Returns the data model used by this progress bar.intReturnsSwingConstants.VERTICALorSwingConstants.HORIZONTAL, depending on the orientation of the progress bar.doubleReturns the percent complete for the progress bar.Returns aStringrepresentation of the current progress.getUI()Returns the look-and-feel object that renders this component.Returns the name of the look-and-feel class that renders this component.intgetValue()Returns the progress bar's currentvaluefrom theBoundedRangeModel.booleanReturns theborderPaintedproperty.booleanReturns the value of theindeterminateproperty.booleanReturns the value of thestringPaintedproperty.protected voidPaints the progress bar's border if theborderPaintedproperty istrue.protected StringReturns a string representation of thisJProgressBar.voidRemoves aChangeListenerfrom the progress bar.voidsetBorderPainted(boolean b) Sets theborderPaintedproperty, which istrueif the progress bar should paint its border.voidsetIndeterminate(boolean newValue) Sets theindeterminateproperty of the progress bar, which determines whether the progress bar is in determinate or indeterminate mode.voidsetMaximum(int n) Sets the progress bar's maximum value (stored in the progress bar's data model) ton.voidsetMinimum(int n) Sets the progress bar's minimum value (stored in the progress bar's data model) ton.voidsetModel(BoundedRangeModel newModel) Sets the data model used by theJProgressBar.voidsetOrientation(int newOrientation) Sets the progress bar's orientation tonewOrientation, which must beSwingConstants.VERTICALorSwingConstants.HORIZONTAL.voidSets the value of the progress string.voidsetStringPainted(boolean b) Sets the value of thestringPaintedproperty, which determines whether the progress bar should render a progress string.voidsetUI(ProgressBarUI ui) Sets the look-and-feel object that renders this component.voidsetValue(int n) Sets the progress bar's current value ton.voidupdateUI()Resets the UI property to a value from the current look and feel.Methods declared in class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, updateMethods declared in class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusDownCycle, validate, validateTreeMethods declared in class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
Field Details
-
orientation
protected int orientationWhether the progress bar is horizontal or vertical. The default isHORIZONTAL.- See Also:
-
paintBorder
protected boolean paintBorderWhether to display a border around the progress bar. The default istrue.- See Also:
-
model
-
progressString
An optional string that can be displayed on the progress bar. The default isnull. Setting this to a non-nullvalue does not imply that the string will be displayed. To display the string,paintStringmust betrue.- See Also:
-
paintString
protected boolean paintStringWhether to display a string of text on the progress bar. The default isfalse. Setting this totruecauses a textual display of the progress to be rendered on the progress bar. If theprogressStringisnull, the percentage of completion is displayed on the progress bar. Otherwise, theprogressStringis rendered on the progress bar.- See Also:
-
changeEvent
Only oneChangeEventis needed per instance since the event's only interesting property is the immutable source, which is the progress bar. The event is lazily created the first time that an event notification is fired.- See Also:
-
changeListener
Listens for change events sent by the progress bar's model, redispatching them to change-event listeners registered upon this progress bar.- See Also:
-
-
Constructor Details
-
JProgressBar
public JProgressBar()Creates a horizontal progress bar that displays a border but no progress string. The initial and minimum values are 0, and the maximum is 100.- See Also:
-
JProgressBar
public JProgressBar(int orient) Creates a progress bar with the specified orientation, which can be eitherSwingConstants.VERTICALorSwingConstants.HORIZONTAL. By default, a border is painted but a progress string is not. The initial and minimum values are 0, and the maximum is 100.- Parameters:
orient- the desired orientation of the progress bar- Throws:
IllegalArgumentException- iforientis an illegal value- See Also:
-
JProgressBar
public JProgressBar(int min, int max) Creates a horizontal progress bar with the specified minimum and maximum. Sets the initial value of the progress bar to the specified minimum. By default, a border is painted but a progress string is not.The
BoundedRangeModelthat holds the progress bar's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the progress bar. See theBoundedRangeModeldocumentation for details.- Parameters:
min- the minimum value of the progress barmax- the maximum value of the progress bar- See Also:
-
JProgressBar
public JProgressBar(int orient, int min, int max) Creates a progress bar using the specified orientation, minimum, and maximum. By default, a border is painted but a progress string is not. Sets the initial value of the progress bar to the specified minimum.The
BoundedRangeModelthat holds the progress bar's data handles any issues that may arise from improperly setting the minimum, initial, and maximum values on the progress bar. See theBoundedRangeModeldocumentation for details.- Parameters:
orient- the desired orientation of the progress barmin- the minimum value of the progress barmax- the maximum value of the progress bar- Throws:
IllegalArgumentException- iforientis an illegal value- See Also:
-
JProgressBar
Creates a horizontal progress bar that uses the specified model to hold the progress bar's data. By default, a border is painted but a progress string is not.- Parameters:
newModel- the data model for the progress bar- See Also:
-
-
Method Details
-
getOrientation
public int getOrientation()ReturnsSwingConstants.VERTICALorSwingConstants.HORIZONTAL, depending on the orientation of the progress bar. The default orientation isSwingConstants.HORIZONTAL.- Returns:
HORIZONTALorVERTICAL- See Also:
-
setOrientation
@BeanProperty(preferred=true, visualUpdate=true, description="Set the progress bar's orientation.") public void setOrientation(int newOrientation) Sets the progress bar's orientation tonewOrientation, which must beSwingConstants.VERTICALorSwingConstants.HORIZONTAL. The default orientation isSwingConstants.HORIZONTAL.- Parameters:
newOrientation-HORIZONTALorVERTICAL- Throws:
IllegalArgumentException- ifnewOrientationis an illegal value- See Also:
-
isStringPainted
public boolean isStringPainted()Returns the value of thestringPaintedproperty.- Returns:
- the value of the
stringPaintedproperty - See Also:
-
setStringPainted
@BeanProperty(visualUpdate=true, description="Whether the progress bar should render a string.") public void setStringPainted(boolean b) Sets the value of thestringPaintedproperty, which determines whether the progress bar should render a progress string. The default isfalse, meaning no string is painted. Some look and feels might not support progress strings or might support them only when the progress bar is in determinate mode.- Parameters:
b-trueif the progress bar should render a string- See Also:
-
getString
Returns aStringrepresentation of the current progress. By default, this returns a simple percentageStringbased on the value returned fromgetPercentComplete. An example would be the "42%". You can change this by callingsetString.- Returns:
- the value of the progress string, or a simple percentage string
if the progress string is
null - See Also:
-
setString
@BeanProperty(visualUpdate=true, description="Specifies the progress string to paint") public void setString(String s) Sets the value of the progress string. By default, this string isnull, implying the built-in behavior of using a simple percent string. If you have provided a custom progress string and want to revert to the built-in behavior, set the string back tonull.The progress string is painted only if the
isStringPaintedmethod returnstrue.- Parameters:
s- the value of the progress string- See Also:
-
getPercentComplete
Returns the percent complete for the progress bar. Note that this number is between 0.0 and 1.0.- Returns:
- the percent complete for this progress bar
-
isBorderPainted
public boolean isBorderPainted()Returns theborderPaintedproperty.- Returns:
- the value of the
borderPaintedproperty - See Also:
-
setBorderPainted
@BeanProperty(visualUpdate=true, description="Whether the progress bar should paint its border.") public void setBorderPainted(boolean b) Sets theborderPaintedproperty, which istrueif the progress bar should paint its border. The default value for this property istrue. Some look and feels might not implement painted borders; they will ignore this property.- Parameters:
b-trueif the progress bar should paint its border; otherwise,false- See Also:
-
paintBorder
Paints the progress bar's border if theborderPaintedproperty istrue.- Overrides:
paintBorderin classJComponent- Parameters:
g- theGraphicscontext within which to paint the border- See Also:
-
getUI
Returns the look-and-feel object that renders this component.- Overrides:
getUIin classJComponent- Returns:
- the
ProgressBarUIobject that renders this component
-
setUI
@BeanProperty(hidden=true, visualUpdate=true, description="The UI object that implements the Component's LookAndFeel.") public void setUI(ProgressBarUI ui) Sets the look-and-feel object that renders this component.- Parameters:
ui- aProgressBarUIobject- See Also:
-
updateUI
public void updateUI()Resets the UI property to a value from the current look and feel.- Overrides:
updateUIin classJComponent- See Also:
-
getUIClassID
@BeanProperty(bound=false, expert=true, description="A string that specifies the name of the look-and-feel class.") public String getUIClassID()Returns the name of the look-and-feel class that renders this component.- Overrides:
getUIClassIDin classJComponent- Returns:
- the string "ProgressBarUI"
- See Also:
-
createChangeListener
Subclasses that want to handle change events from the model differently can override this to return an instance of a customChangeListenerimplementation. The defaultChangeListenersimply calls thefireStateChangedmethod to forwardChangeEvents to theChangeListeners that have been added directly to the progress bar.- Returns:
- the instance of a custom
ChangeListenerimplementation. - See Also:
-
addChangeListener
Adds the specifiedChangeListenerto the progress bar.- Parameters:
l- theChangeListenerto add
-
removeChangeListener
Removes aChangeListenerfrom the progress bar.- Parameters:
l- theChangeListenerto remove
-
getChangeListeners
Returns an array of all theChangeListeners added to this progress bar withaddChangeListener.- Returns:
- all of the
ChangeListeners added or an empty array if no listeners have been added - Since:
- 1.4
-
fireStateChanged
protected void fireStateChanged()Send aChangeEvent, whose source is thisJProgressBar, to allChangeListeners that have registered interest inChangeEvents. This method is called each time aChangeEventis received from the model.The event instance is created if necessary, and stored in
changeEvent.- See Also:
-
getModel
Returns the data model used by this progress bar.- Returns:
- the
BoundedRangeModelcurrently in use - See Also:
-
setModel
@BeanProperty(bound=false, expert=true, description="The data model used by the JProgressBar.") public void setModel(BoundedRangeModel newModel) Sets the data model used by theJProgressBar. Note that theBoundedRangeModel'sextentis not used, and is set to0.- Parameters:
newModel- theBoundedRangeModelto use
-
getValue
public int getValue()Returns the progress bar's currentvaluefrom theBoundedRangeModel. The value is always between the minimum and maximum values, inclusive.- Returns:
- the current value of the progress bar
- See Also:
-
getMinimum
public int getMinimum()Returns the progress bar'sminimumvalue from theBoundedRangeModel.- Returns:
- the progress bar's minimum value
- See Also:
-
getMaximum
public int getMaximum()Returns the progress bar'smaximumvalue from theBoundedRangeModel.- Returns:
- the progress bar's maximum value
- See Also:
-
setValue
@BeanProperty(bound=false, preferred=true, description="The progress bar's current value.") public void setValue(int n) Sets the progress bar's current value ton. This method forwards the new value to the model.The data model (an instance of
BoundedRangeModel) handles any mathematical issues arising from assigning faulty values. See theBoundedRangeModeldocumentation for details.If the new value is different from the previous value, all change listeners are notified.
- Parameters:
n- the new value- See Also:
-
setMinimum
@BeanProperty(bound=false, preferred=true, description="The progress bar's minimum value.") public void setMinimum(int n) Sets the progress bar's minimum value (stored in the progress bar's data model) ton.The data model (a
BoundedRangeModelinstance) handles any mathematical issues arising from assigning faulty values. See theBoundedRangeModeldocumentation for details.If the minimum value is different from the previous minimum, all change listeners are notified.
- Parameters:
n- the new minimum- See Also:
-
setMaximum
@BeanProperty(bound=false, preferred=true, description="The progress bar's maximum value.") public void setMaximum(int n) Sets the progress bar's maximum value (stored in the progress bar's data model) ton.The underlying
BoundedRangeModelhandles any mathematical issues arising from assigning faulty values. See theBoundedRangeModeldocumentation for details.If the maximum value is different from the previous maximum, all change listeners are notified.
- Parameters:
n- the new maximum- See Also:
-
setIndeterminate
public void setIndeterminate(boolean newValue) Sets theindeterminateproperty of the progress bar, which determines whether the progress bar is in determinate or indeterminate mode. An indeterminate progress bar continuously displays animation indicating that an operation of unknown length is occurring. By default, this property isfalse. Some look and feels might not support indeterminate progress bars; they will ignore this property.See How to Monitor Progress for examples of using indeterminate progress bars.
- Parameters:
newValue-trueif the progress bar should change to indeterminate mode;falseif it should revert to normal.- Since:
- 1.4
- See Also:
-
isIndeterminate
@BeanProperty(bound=false, description="Is the progress bar indeterminate (true) or normal (false)?") public boolean isIndeterminate()Returns the value of theindeterminateproperty.- Returns:
- the value of the
indeterminateproperty - Since:
- 1.4
- See Also:
-
paramString
Returns a string representation of thisJProgressBar. This method is intended to be used only for debugging purposes. The content and format of the returned string may vary between implementations. The returned string may be empty but may not benull.- Overrides:
paramStringin classJComponent- Returns:
- a string representation of this
JProgressBar
-
getAccessibleContext
@BeanProperty(bound=false, expert=true, description="The AccessibleContext associated with this ProgressBar.") public AccessibleContext getAccessibleContext()Gets theAccessibleContextassociated with thisJProgressBar. For progress bars, theAccessibleContexttakes the form of anAccessibleJProgressBar. A newAccessibleJProgressBarinstance is created if necessary.- Specified by:
getAccessibleContextin interfaceAccessible- Overrides:
getAccessibleContextin classComponent- Returns:
- an
AccessibleJProgressBarthat serves as theAccessibleContextof thisJProgressBar
-