gauge.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)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;