/* * @(#)Gauge.java	1.73 01/08/09 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. ("Confidential Information").  You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING * THIS SOFTWARE OR ITS DERIVATIVES. */package javax.microedition.lcdui;/** * <P>The Gauge class implements a bar graph display of a value intended for * use in a form. Gauge is optionally * interactive. The values accepted by the object are small integers in the * range zero through a maximum value established by the application. The * application is expected to normalize its values into this range. The * device is expected to normalize this range into a smaller set of values for * display purposes. Doing so will not change the actual value contained * within the object. The range of values specified by the application may be * larger than the number of distinct visual states possible on the device, so * more than one value may have the same visual representation. </p> * * <P>For example, consider a Gauge object that has a range of values from zero * to 99, running on a device that displays the Gauge's approximate value * using a set of one to ten bars. The device might show one bar for values * zero through nine, two bars for values ten through 19, three bars for * values 20 through 29, and so forth. </p> * * <P>A Gauge may be interactive or non-interactive. Applications may set or * retrieve the Gauge's value at any time regardless of the interaction mode. * The implementation may change the visual appearance of the bar graph * depending on whether the object is created in interactive mode. </p> * * <P>In interactive mode, the user is allowed to modify the value. The user * will always have the means to change the value up or down by one and * may also have the means to change the value in greater increments. * The user is * prohibited from moving the value outside the established range. The * expected behavior is that the application sets the initial value and then * allows the user to modify the value thereafter. However, the application * is not prohibited from modifying the value even while the user is * interacting with it. </p> * * <p> In many cases the only means for the user to modify the value will be * to press a button to increase or decrease the value by one unit at a time. * Therefore, applications should specify a range of no more than a few dozen * values. </p> * * <P>In non-interactive mode, the user is prohibited from modifying the value. * An expected use of the non-interactive mode is as a "progress indicator" to * give the user some feedback as progress occurs during a long-running * operation. The application is expected to update the value periodically * using the setValue() method. An application using the Gauge as a progress * indicator should typically also attach a * {@link Command#STOP STOP} * command to the Form containing the Gauge to allow the user to halt the * operation in progress. * </p> */public class Gauge extends Item {    /** The current value of this gauge */    private int value;    /** The maximum possible value of this gauge */    private int maxValue;    /** Wether this gauge is interactive or not */    private boolean interactive;    /** The number of blocks making up this gauge */    private int blockCount;    /**     * The buffer of horizontal space to split on     * either side of this gauge (creating left/right margins)     */    private static final int BLOCK_SPACE    = 8;    /**     * Greatest height, in pixels, this gauge will     * occupy on screen     */    private static final int GAUGE_HEIGHT   = 25;    /**     * The numerical value assigned to each block.     * The number of blocks (blockCount) times the     * value of each block (valueOfEachBlock) shall     * equal the maximum value of this gauge (maxValue)     */    private int valueOfEachBlock;    /** Gauge overall height */    private int height;    /**     * <p>Creates a new Gauge object with the given label, in interactive or     * non-interactive mode, with the given maximum and initial values. The     * maximum value must be greater than zero, otherwise an exception is     * thrown.  The initial value must be within the range zero to maxValue,     * inclusive.  If the initial value is less than zero, the value is set to     * zero.  If the initial value is greater than maxValue, it is set to     * maxValue.</p>     *     * @param label the Gauge's label     * @param interactive tells whether the user can change the value     * @param maxValue the maximum value     * @param initialValue the initial value in the range [0..maxValue]     * @throws IllegalArgumentException if maxValue is invalid     */    public Gauge(String label, boolean interactive, int maxValue,                 int initialValue)    {        // This super.constructor call guarantees that our layouts[] is        // non-null and that index 0 contains a StringLayout        super(label, 1);        synchronized (Display.LCDUILock) {            this.interactive = interactive;            this.value = initialValue;            setMaxValueImpl(maxValue);        }    }    // public implementation    /**     * <p>Sets the current value of this Gauge object. If the value is less     * than zero, zero is used. If the current value is greater than the     * maximum value, the current value is set to be equal to the maximum     * value. </p>     *     * @param value the new value     *     * @see #getValue     */    public void setValue(int value) {        synchronized (Display.LCDUILock) {            this.value = value;            checkValue();            contentChanged(0, height - (GAUGE_HEIGHT + 5), 0);        }    }    /**     * <p>Gets the current value of this Gauge object.</p>     *     * @return current value of the Gauge     *     * @see #setValue     */    public int getValue() {        // SYNC NOTE: return of atomic value, no locking necessary        return value;    }    /**     * <p>Sets the maximum value of this Gauge object.  The new maximum value     * must be greater than zero, otherwise an exception is thrown.  If the     * current value is greater than new maximum value, the current value is     * set to be equal to the new maximum value.</p>     *     * @param maxValue the new maximum value     *     * @throws IllegalArgumentException if maxValue is invalid     *      * @see #getMaxValue     */    public void setMaxValue(int maxValue) {        synchronized (Display.LCDUILock) {            setMaxValueImpl(maxValue);        }    }    /**     * <p>Gets the maximum value of this Gauge object.</p>     *     * @return the maximum value of the Gauge     *     * @see #setMaxValue     */    public int getMaxValue() {        // SYNC NOTE: return of atomic value, no locking necessary        return maxValue;    }    /**     * <p>Tells whether the user is allowed to change the value of the Gauge.     * </p>     *     * @return a boolean indicating whether the Gauge is interactive     */    public boolean isInteractive() {        // SYNC NOTE: return of atomic value, no locking necessary        return interactive;    }    /**     * Sets the label of the Item. If label is null, specifies that this     * item has no label.     * @param label the label string     */    public void setLabel(String label) {        synchronized (Display.LCDUILock) {            super.setLabel(label);            int deltaHeight = ((StringLayout)layouts[0]).setString(label);            height += deltaHeight;            contentChanged(0, 0, deltaHeight);        }    }    // package private implementation    /**     * Paint this Gauge     *     * @param g The Graphics to paint to     */    void paint(Graphics g) {        g.setColor(Display.ERASE_COLOR);        g.fillRect(g.getClipX(), 0, g.getClipWidth(), height);        // We need to check the clip to determine if        // the label needs painting        int layoutHeight = layouts[0].getHeight();        if (g.getClipY() < layoutHeight) {            layouts[0].paint(g, false, false);        }        g.translate(0, layoutHeight);        // Depending on the clip, we may need to repaint        // only some or all of the blocks.        int startBlock = 0;        int stopBlock = blockCount;        if (g.getClipX() > 0) {            startBlock = (g.getClipX() - 6) / BLOCK_SPACE;        }        if (g.getClipWidth() == BLOCK_SPACE - 3) {            // We just need to paint 1 bar            stopBlock = startBlock + 1;            // NOTE: We're a little careless here. It could            // be possible that the clip contains several            // bars rather than one. If this is the case,            // we paint from the start bar to the end of            // the gauge, rather than figure the more precise            // end bar. Its not possible with the current            // emulator but it may be on some platforms.        }        if (hasFocus()) {            g.setColor(Display.FG_COLOR);        } else {            g.setColor(0x00606060); // dark gray            // Keep in mind that on a 1-bit display, dark gray will            // round to black        }        //        // these values are used in calculating the blockHeight        // they only need to be calculated once every paint        //        int bc  = blockCount - 1;        int bc2 = bc * bc;