11
JCProgressMeter

Introduction · Sample Program Code · Label and Range

Label Display · Bar Display · Property Listing

Example Program

Introduction

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:

Behavior

JCProgressMeter behaves in the following manner:

• when an action is initiated by the user which activates a JCProgressMeter, the JCProgressMeter displays the continual progress of an ongoing operation as the application changes its value.

Keyboard Traversal

There are no keyboard traversal routines that apply to JCProgressMeter.

Sample Program Code

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 the end-user presses the Restart button, the value of the JCProgressMeter program Value method 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.

Label and Range

The value displayed by a JCProgressMeter component is controlled by three properties:

• The value itself is stored in the Value property.
• The maximum value allowed is specified by the Maximum property.
• The minimum value allowed is specified by the Minimum 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 Progress Percentage

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)

Label Display

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:

• whether the label is to be displayed
• whether the label is displayed as a percentage, time elapsed, or time left until the operation is completed
• the width and positioning of the label
• the color of the label.

Suppressing Label Display

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 .

Type of Label Display

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 a percentage. If true (default), the label is displayed.

The TimeElapsed method calculates the elapsed time in milliseconds since the minimum value was last set. The obverse 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% which returns a time value in the format " HH:MM:SS ", or " ? " if the value is equal to the minimum.

Label Width and Positioning

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.

Label Font

To specify the font for the label text, set the Font property. For a listing of common fontnames and values, see Appendix A: Colors and Fonts.

Label Color

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)

Bar Display

JCProgressMeter enables you to control the following aspects of bar display:

• the type of bar displayed
• the number of bars to be displayed and the space between bars
• the bar color.

Bar Type and Spacing

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 BarSpacing 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 :

Bar Color

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);

Property Listing

The following summarizes the properties of JCProgressMeter. Complete reference documentation is available online in standard javadoc format in jclass.bwt.JCProgressMeter.html.

Example Program

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