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

#####

##### A sample JCProgressMeter in action

#### 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 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` 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 `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 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)

The value of `ValuePercent` is recalculated whenever `Value`, `Maximum` or `Minimum` is changed.

### 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`.

##### The five possible label orientations for JCProgressMeter

##### 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 effects of five different BarCount values 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` :

#####

##### The effects of five different BarSpacing values 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);

For a listing of common color names, see Appendix A: Colors and Fonts.

### Property Listing

The following is a listing of available properties for `JCProgressMeter.`

#### jclass.bwt.JCProgressMeter

#####

Name | Method | Inherited from
--- | --- | ---
`Background` | `setBackground` | `jclass.bwt.JCComponent`
`Font` | `setFont` | `jclass.bwt.JCComponent`
`Foreground` | `setForeground` | `jclass.bwt.JCComponent`
`PreferredSize` | `setPreferredSize` | `jclass.bwt.JCComponent`
`Values` | `setValues` | `jclass.bwt.JCProgressMeter`
`UserData` | `setUserData` | `jclass.bwt.JCComponent`

### 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