gauge.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 747 行 · 第 1/3 页

/*
 *   
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package javax.microedition.lcdui; 

/** 
 * Implements a graphical display, such as a bar graph, of an integer
 * value.  The <code>Gauge</code> contains a <em>current value</em>
 * that lies between zero and the <em>maximum value</em>, inclusive.
 * The application can control the current value and maximum value.
 * 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>For example, consider a <code>Gauge</code> object that has a
 * range of values from zero to <code>99</code>, running on a device
 * that displays the <code>Gauge's</code> 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 <code>19</code>,
 * three bars for values <code>20</code> through <code>29</code>, and
 * so forth. </p>
 *
 * <P>A <code>Gauge</code> may be interactive or
 * non-interactive. Applications may set or retrieve the
 * <code>Gauge's</code> 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.  Non-interactive mode is used to provide feedback to the
 * user on the state of a long-running operation. One expected use of
 * the non-interactive mode is as a &quot;progress indicator&quot; or
 * &quot;activity indicator&quot; to give the user some feedback
 * during a long-running operation. The application may update the
 * value periodically using the <code>setValue()</code> method. </P>
 *
 * <P>A non-interactive <code>Gauge</code> can have a definite or
 * indefinite range.  If a <code>Gauge</code> has definite range, it
 * will have an integer value between zero and the maximum value set
 * by the application, inclusive.  The implementation will provide a
 * graphical representation of this value such as described above.</p>
 *
 * <P>A non-interactive <code>Gauge</code> that has indefinite range
 * will exist in one of four states: continuous-idle,
 * incremental-idle, continuous-running, or incremental-updating.
 * These states are intended to indicate to the user that some level
 * of activity is occurring.  With incremental-updating, progress can
 * be indicated to the user even though there is no known endpoint to
 * the activity.  With continuous-running, there is no progress that
 * gets reported to the user and there is no known endpoint;
 * continuous-running is merely a busy state indicator. The
 * implementation should use a graphical display that shows this
 * appropriately.  The implementation may use different graphics for
 * indefinite continuous gauges and indefinite incremental gauges.
 * Because of this, separate idle states exist for each mode.  For
 * example, the implementation might show an hourglass or spinning
 * watch in the continuous-running state, but show an animation with
 * different states, like a beach ball or candy-striped bar, in the
 * incremental-updating state.</p>
 *
 * <p>In the continuous-idle or incremental-idle state, the
 * <code>Gauge</code> indicates that no activity is occurring. In the
 * incremental-updating state, the <code>Gauge</code> indicates
 * activity, but its graphical representation should be updated only
 * when the application requests an update with a call to
 * <code>setValue()</code>.  In the continuous-running state, the
 * <code>Gauge</code> indicates activity by showing an animation that
 * runs continuously, without update requests from the
 * application.</p>
 *
 * <p>The values <code>CONTINUOUS_IDLE</code>,
 * <code>INCREMENTAL_IDLE</code>, <code>CONTINUOUS_RUNNING</code>, and
 * <code>INCREMENTAL_UPDATING</code> have their special meaning only
 * when the <code>Gauge</code> is non-interactive and has been set to
 * have indefinite range.  They are treated as ordinary values if the
 * <code>Gauge</code> is interactive or if it has been set to have a
 * definite range.</p>
 *
 * <P>An application using the <code>Gauge</code> as a progress
 * indicator should typically also attach a {@link Command#STOP STOP}
 * command to the container containing the <code>Gauge</code> to allow
 * the user to halt the operation in progress.</p>
 *
 * <h3>Notes for Application Developers</h3>
 * 
 * <P>As mentioned above, a non-interactive <code>Gauge</code> may be
 * used to give user feedback during a long-running operation.  If the
 * application can observe the progress of the operation as it
 * proceeds to an endpoint known in advance, then the application
 * should use a non-interactive <code>Gauge</code> with a definite
 * range.  For example, consider an application that is downloading a
 * file known to be <code>20</code> kilobytes in size.  The
 * application could set the <code>Gauge's</code> maximum value to be
 * <code>20</code> and set its value to the number of kilobytes
 * downloaded so far.  The user will be presented with a
 * <code>Gauge</code> that shows the portion of the task completed at
 * any given time.</P>
 *
 * <P>If, on the other hand, the application is downloading a file of
 * unknown size, it should use a non-interactive <code>Gauge</code>
 * with indefinite range.  Ideally, the application should call
 * <CODE>setValue(INCREMENTAL_UPDATING)</CODE> periodically, perhaps
 * each time its input buffer has filled.  This will give the user an
 * indication of the rate at which progress is occurring.</P>
 *
 * <P>Finally, if the application is performing an operation but has
 * no means of detecting progress, it should set a non-interactive
 * <code>Gauge</code> to have indefinite range and set its value to
 * <CODE>CONTINUOUS_RUNNING</CODE> or <CODE>CONTINUOUS_IDLE</CODE> as
 * appropriate.  For example, if the application has issued a request
 * to a network server and is about to block waiting for the server to
 * respond, it should set the <code>Gauge's</code> state to
 * <CODE>CONTINUOUS_RUNNING</CODE> before awaiting the response, and it
 * should set the state to <CODE>CONTINUOUS_IDLE</CODE> after it has
 * received the response.</P>
 *
 * @since MIDP 1.0 
 */

public class Gauge extends Item {

    // public implementation

    /**
     * A special value used for the maximum value in order to indicate that 
     * the <code>Gauge</code> has indefinite range.  This value may be
     * used as the <code>maxValue</code>
     * parameter to the constructor, the parameter passed to
     * <code>setMaxValue()</code>, and
     * as the return value of <code>getMaxValue()</code>.
     * <P>
     * The value of <code>INDEFINITE</code> is <code>-1</code>.</P>
     *
     */
    public static final int INDEFINITE = -1;
    
    /**    
     * The value representing the continuous-idle state of a
     * non-interactive <code>Gauge</code> with indefinite range.  In
     * the continuous-idle state, the gauge shows a graphic
     * indicating that no work is in progress.
     *
     * <p>This value has special meaning only for non-interactive
     * gauges with indefinite range.  It is treated as an ordinary
     * value for interactive gauges and for non-interactive gauges
     * with definite range.</p>
     *
     * <p>The value of <code>CONTINUOUS_IDLE</code> is
     * <code>0</code>.</p>
     * 
     */
    public static final int CONTINUOUS_IDLE = 0;

    /** 
     * The value representing the incremental-idle state of a
     * non-interactive <code>Gauge</code> with indefinite range.  In
     * the incremental-idle state, the gauge shows a graphic
     * indicating that no work is in progress.
     *
     * <p>This value has special meaning only for non-interactive
     * gauges with indefinite range.  It is treated as an ordinary
     * value for interactive gauges and for non-interactive gauges
     * with definite range.</p>
     *
     * <p>The value of <code>INCREMENTAL_IDLE</code> is
     * <code>1</code>.</p>
     * 
     */
    public static final int INCREMENTAL_IDLE = 1;
    
    /** 
     * The value representing the continuous-running state of a
     * non-interactive <code>Gauge</code> with indefinite range.  In
     * the continuous-running state, the gauge shows a
     * continually-updating animation sequence that indicates that
     * work is in progress.  Once the application sets a gauge into
     * the continuous-running state, the animation should proceed
     * without further requests from the application.
     * 
     * <p>This value has special meaning only for non-interactive
     * gauges with indefinite range.  It is treated as an ordinary
     * value for interactive gauges and for non-interactive gauges
     * with definite range.</p>
     *
     * <p>The value of <code>CONTINUOUS_RUNNING</code> is
     * <code>2</code>.</p>
     *
     */
    public static final int CONTINUOUS_RUNNING = 2;
    
    /** 
     * The value representing the incremental-updating state of a
     * non-interactive <code>Gauge</code> with indefinite range.  In
     * the incremental-updating state, the gauge shows a graphic
     * indicating that work is in progress, typically one frame of an
     * animation sequence.  The graphic should be updated to the next
     * frame in the sequence only when the application calls
     * <code>setValue(INCREMENTAL_UPDATING)</code>.
     * 
     * <p>This value has special meaning only for non-interactive
     * gauges with indefinite range.  It is treated as an ordinary
     * value for interactive gauges and for non-interactive gauges
     * with definite range.</p> 
     *
     * <p> The value of <code>INCREMENTAL_UPDATING</code> is
     * <code>3</code>.</p>
     *
     */
    public static final int INCREMENTAL_UPDATING = 3;