Introduction · Sample Program Code · Label and Range
Label Display · Bar Display · Property Listing
A progress indicator (sometimes known as a "progress bar") is a standard Windows component that is used to show the percentage of completion of a lengthy operation. It is comprised of a rectangular bar that is "filled in" from left to right as the operation is loaded. It provides the user with feedback as to the progress of a particular operation.
Progress indicators are typically non-interactive, though other actions by the user may influence the status of the progress bar display (such as a CANCEL
button). An optional label or an application-defined string can be used to display the meter's current value.
There is no equivalent to JCProgressMeter
in the Java Development Kit (JDK). The basic JCProgressMeter
conforms to standard Windows 95 "look and feel" and behavior.
JCProgressMeter
is capable of displaying several distinct types of progress meters. The following illustration depicts a typical Windows 95 style progress meter:
A sample JCProgressMeter in action
JCProgressMeter
behaves in the following manner:
There are no keyboard traversal routines that apply to JCProgressMeter
.
The following code fragment shows how a simple program that incorporates three different progress meter displays that can be created using JCProgressMeter
:
package jclass.bwt.examples; import jclass.bwt.BWTEnum; import jclass.bwt.JCActionEvent; import jclass.bwt.JCActionListener; import jclass.bwt.JCButton; import jclass.bwt.JCGridLayout; import jclass.bwt.JCProgressMeter; import jclass.contrib.ContribFrame; import jclass.util.JCUtilConverter; import jclass.util.JCVector; import java.awt.*; /** * This example demonstrates the use of a JCProgressMeter. */ public class progressMeter extends java.applet.Applet implements Runnable, JCActionListener { JCProgressMeter meter1, meter2, meter3; Thread thread; // JCActionListener method public void actionPerformed(JCActionEvent ev) { start(); } public void init() { setBackground(Color.lightGray); setLayout(new JCGridLayout(JCGridLayout.VARIABLE, 1)); add(meter1 = new JCProgressMeter(0, 0, 100)); add(meter2 = new JCProgressMeter(0, 0, 5000)); meter2.setAutoLabel(false); meter2.setBarColor(Color.blue); meter2.setBarCount(0); meter2.setLabelPosition(BWTEnum.STRING_TOP); add(meter3 = new JCProgressMeter(0, 0, 100)); meter3.setBarCount(0); meter3.setLabelPosition(BWTEnum.STRING_CENTER); JCButton btn = new JCButton("Restart"); btn.addActionListener(this); add(btn); } public void start() { stop(); if (thread == null) { thread = new Thread(this); thread.start(); } } public void stop() { if (thread != null) { thread.yield(); thread.stop(); } thread = null; } /** Updates the meter randomly. */ public void run() { int count = 0, sleep = 50; meter1.setValue(0); meter2.setValue(0); meter3.setValue(0); while (true) { try { Thread.sleep(sleep); } catch (Exception e) {} if (meter1.getValue() == meter1.getMaximum() && meter2.getValue() == meter2.getMaximum() && meter3.getValue() == meter2.getMaximum()) stop(); if (!Thread.currentThread().isAlive() || thread == null) return; if ((count % (1000/sleep)) == 0) { meter1.setValue(meter1.getValue() + (int)(Math.random()*20.)); meter2.setValue(meter2.getValue() + 250); meter2.setLabel("Time Left: "+meter2.getTimeToCompletionString()); } meter3.setValue(meter3.getValue() + 1); count++; } } public static void main(String args[]) { ContribFrame frame = new ContribFrame("ProgressMeter"); progressMeter s = new progressMeter(); s.init(); frame.add(s); frame.pack(); frame.show(); s.start(); } }
When this program is run, the following appears:
A sample program incorporating three JCProgressMeters
When the end-user presses the Restart
button, the value of the JCProgressMeter
program Value
property is updated, and each progress bar is redisplayed, every tenth of a second. The Value
property contains the current value of the JCProgressMeter
, which is a number between 0
and 100
representing a percentage. This current percentage is displayed in three ways: the amount of time to completion of the task, as a horizontal bar and as a numeric value.
In more complicated real-world applications, a pointer to a JCProgressMeter
can be passed to another application window, which changes the value of Value
when appropriate. This enables the application to use a JCProgressMeter
to monitor the completion of a task.
This sample code is incorporated into the example file progressMeter .class provided with JClass BWT. For information on how to run this program, see the " Example Program " section at the end of this chapter.
The value displayed by a JCProgressMeter
component is controlled by three properties:
The Value
property stores a JCProgressMeter
's current value, and is of type int
. This value is formatted by the component before being displayed: for instance, in the previous example the value 70
is formatted to become the string 70%
. The resulting formatted string, called the label, is stored in the Label
property.
The Minimum
property specifies the smallest integer that can be stored in Value
. By default, this value is 0
. When JCProgressMeter
is realized, the value of Minimum
becomes the initial value of Value
. If Value
is set to a value smaller than Minimum
, the value of Minimum
is used.
The Maximum
property specifies the largest integer that can be stored in Value
. By default, this value is 100
. When an application sets Value
to the value of Maximum
, the task whose progress is measured by JCProgressMeter
is assumed to be complete. If Value
is set to a value greater than Maximum
, the value of Maximum
is used.
Typically, the application slowly increases the value of Value
from the minimum value to the maximum value.
The default minimum and maximum of 0
and 100
make it easy to use JCProgressMeter
to indicate what percentage of a task has been performed, since the value of Value
is equivalent to the percentage. However, if Minimum
or Maximum
is changed to something other than the default value, the value of Value
may not be the same as the task percentage.
To make it easy to use JCProgressMeter
to chart task percentage when the minimum and maximum are not 0 and 100, the task percentage is stored as a double-precision floating-point number in the ValuePercent
property. ValuePercent
calculates the percentage using the following formula:
percentage =Value
/ (Maximum
-Minimum
)
The value of ValuePercent
is recalculated whenever Value
, Maximum
or Minimum
is changed.
JCProgressMeter
provides several properties that control how JCProgressMeter
's label (the current value formatted as a string) is displayed. Changing these properties enables you to specify:
By default, the label is displayed whenever JCProgressMeter
is realized or updated. To turn off label display, set ShowLabel
to false
. This tells JCProgressMeter
to display only the bar.
Setting ShowLabel
to false
is useful if you want to display the label in some place other than JCProgressMeter
.
There are three ways the value of a JCProgressMeter
can be displayed: a percentage, time elapsed, or time left until the operation is completed.
The AutoLabel
property is used to display the meter's value as a percentage. If true
(default), the label is displayed.
The TimeElapsed
property calculates the elapsed time in milliseconds since the minimum value was last set. The converse of this is TimeToCompletion
which calculates the time in milliseconds before which the value becomes 100%. It returns MAXINT
if the value is equal to the minimum. The display of this value can be manipulated by TimeToCompletionString
, which also calculates the time in milliseconds before which the value becomes 100%
. This returns a time value in the format "HH:MM:SS
", or "?
" if the value is equal to the minimum.
The width of the label is controlled by LabelWidth
, which sets the maximum number of characters to be displayed, assuming ShowLabel
is true
. If AutoLabel
is true
, a default value of 4 characters is used, 10 characters if otherwise.
The positioning of a label is governed by LabelPosition
, which sets the label's position relative to the progress bar display. Valid values are STRING_TOP
, STRING_LEFT
, STRING_RIGHT
(default), STRING_BOTTOM
or STRING_CENTER
.
The five possible label orientations for JCProgressMeter
To specify the font for the label text, set the Font
property. For a listing of common fontnames and values, see
.
The color of the label text depends on whether the text is contained in a bar. Any portion of the text that is contained in the bar is drawn in the component background color (specified by Background
). All other label text is drawn in the component's foreground color (specified by Foreground
).
JCProgressMeter
enables you to control the following aspects of bar display:
By default, the bar displayed by JCProgressMeter
is a horizontal bar comprised of discrete rectangles. To change the bar type to a continuous horizontal bar, change the BarCount
value to 0
. BarCount
is used to set the number of discrete bars that are displayed. By default, BarCount
is 10
. This means that a maximum of 10 bars will be displayed. (The number of bars actually displayed is proportional to the percentage of the task that has been completed).
The following illustration displays the effects of five different values of BarCount
applied to JCProgressMeter
:
The effects of five different BarCount values applied to JCProgressMeter
The setBarSpacing
() method sets the space in pixels between each bar. By default, BarCount
is set to 2
pixels.
The following illustration displays the effects of five different values of BarSpacing
applied to JCProgressMeter
:
The effects of five different BarSpacing values applied to JCProgressMeter
To specify the color in which the bar is drawn, set the BarColor
property. By default, the default value of BarColor
is red. The following code fragment shows how to change the color of a JCProprogessMeter
to blue:
meter1.setBarColor(Color.blue);
For a listing of common color names, see .
The following summarizes the properties of JCProgressMeter
. Complete reference documentation is available online in standard
javadoc format in
jclass.bwt.JCProgressMeter.html.
Demonstration programs and example code containing JCProgressMeter
come with JClass BWT. The examples can be viewed in applet form by launching index.html within the /jclass/bwt/examples directory. progressMeter.class can also be run as a stand-alone Java application from the command prompt by typing:
java jclass.bwt.examples.progressMeter