gauge.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

//#condition polish.usePolishGui
// generated by de.enough.doc2java.Doc2Java (www.enough.de) on Sat Dec 06 15:06:44 CET 2003
/*
 * Copyright (c) 2004-2005 Robert Virkus / Enough Software
 *
 * This file is part of J2ME Polish.
 *
 * J2ME Polish is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * J2ME Polish 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 for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with J2ME Polish; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Commercial licenses are also available, please
 * refer to the accompanying LICENSE.txt or visit
 * http://www.j2mepolish.org for details.
 */
package de.enough.polish.ui;

import java.io.IOException;

import javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Font;
import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;

/**
 * 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 <A HREF="../../../javax/microedition/lcdui/Command.html#STOP"><CODE>STOP</CODE></A>
 * 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>
 * <HR>
 * 
 * @author Robert Virkus, [e-mail]
 * @since MIDP 1.0
 */
public class Gauge extends Item
//#ifdef polish.images.backgroundLoad
//# implements ImageConsumer
//#endif
{
	private static int ANIMATION_MODE_BACKANDFORTH = 1;
	
	/**
	 * 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>
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	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>
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	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>
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	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>
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	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>
	 * 
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	public static final int INCREMENTAL_UPDATING = 3;
	
	private static final int MODE_CONTINUOUS = 0; 
	private static final int MODE_CHUNKED = 1;

	private int value;
	private String valueString;
	private int maxValue;
	private boolean isInteractive;
	private int color = 0x0000FF; //default color is blue
	private int mode = MODE_CHUNKED;
	private int chunkWidth = 6;
	private int gapWidth = 3;
	private int gapColor = 0xFFFFFF; // default gap color is white
	private Image image;
	//#if polish.css.gauge-button-image
		//# private boolean useImageAsButton;
		//# private int sliderWidth;
	//#endif
	//#if polish.css.gauge-slider-image
		//# private Image sliderImage;
	//#endif
	private int imageYOffset;
	private Image indicatorImage;
	private boolean isIndefinite;
	private int indefinitePos;
	private boolean showValue = true;
	private boolean isValueLeft = true;
	private int fontColor;
	private Font font;
	private int valueWidth;

	//#if polish.css.gauge-animation-speed
		//# private int animationSpeed = 1;
	//#endif
	//#if polish.css.gauge-animation-mode
		//# private int animationMode;
		//# private boolean animationDirectionDownwards;
	//#endif
	//#if polish.css.gauge-inactive-image
		//# private Image inactiveImage;
	//#endif
	private boolean isShown;

	/**
	 * Creates a new <code>Gauge</code> object with the given
	 * label, in interactive or non-interactive mode, with the given
	 * maximum and initial values.  In interactive mode (where
	 * <code>interactive</code> is <code>true</code>) the maximum
	 * value must be greater than zero, otherwise an exception is
	 * thrown.  In non-interactive mode (where
	 * <code>interactive</code> is <code>false</code>) the maximum
	 * value must be greater than zero or equal to the special value
	 * <code>INDEFINITE</code>, otherwise an exception is thrown.
	 * 
	 * <p>If the maximum value is greater than zero, the gauge has
	 * definite range.  In this case the initial value must be within
	 * the range zero to <code>maxValue</code>, inclusive.  If the
	 * initial value is less than zero, the value is set to zero.  If
	 * the initial value is greater than <code>maxValue</code>, it is
	 * set to <code>maxValue</code>.</p>
	 * 
	 * <p>If <code>interactive</code> is <code>false</code> and the
	 * maximum value is <code>INDEFINITE</code>, this creates a
	 * non-interactive gauge with indefinite range. The initial value
	 * must be one of <code>CONTINUOUS_IDLE</code>,
	 * <code>INCREMENTAL_IDLE</code>, <code>CONTINUOUS_RUNNING</code>,
	 * or <code>INCREMENTAL_UPDATING</code>.</p>
	 * 
	 * @param label the Gauge's label
	 * @param interactive tells whether the user can change the value
	 * @param maxValue the maximum value, or INDEFINITE
	 * @param initialValue the initial value in the range [0..maxValue], or one of CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, or INCREMENTAL_UPDATING if maxValue is INDEFINITE.
	 * @throws IllegalArgumentException if maxValue is not positive for interactive gauges
	 * 												  or if maxValue is neither positive nor INDEFINITE for non-interactive gauges
	 * 												  or if initialValue is not one of CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, or INCREMENTAL_UPDATING for a non-interactive gauge with indefinite range
	 * @see #INDEFINITE
	 * @see #CONTINUOUS_IDLE
	 * @see #INCREMENTAL_IDLE
	 * @see #CONTINUOUS_RUNNING
	 * @see #INCREMENTAL_UPDATING
	 */
	public Gauge( String label, boolean interactive, int maxValue, int initialValue)
	{
		this( label, interactive, maxValue, initialValue, null );
	}

	/**
	 * Creates a new <code>Gauge</code> object with the given
	 * label, in interactive or non-interactive mode, with the given
	 * maximum and initial values.  In interactive mode (where
	 * <code>interactive</code> is <code>true</code>) the maximum
	 * value must be greater than zero, otherwise an exception is
	 * thrown.  In non-interactive mode (where
	 * <code>interactive</code> is <code>false</code>) the maximum
	 * value must be greater than zero or equal to the special value
	 * <code>INDEFINITE</code>, otherwise an exception is thrown.
	 * 
	 * <p>If the maximum value is greater than zero, the gauge has
	 * definite range.  In this case the initial value must be within
	 * the range zero to <code>maxValue</code>, inclusive.  If the
	 * initial value is less than zero, the value is set to zero.  If
	 * the initial value is greater than <code>maxValue</code>, it is
	 * set to <code>maxValue</code>.</p>
	 * 
	 * <p>If <code>interactive</code> is <code>false</code> and the
	 * maximum value is <code>INDEFINITE</code>, this creates a
	 * non-interactive gauge with indefinite range. The initial value
	 * must be one of <code>CONTINUOUS_IDLE</code>,
	 * <code>INCREMENTAL_IDLE</code>, <code>CONTINUOUS_RUNNING</code>,
	 * or <code>INCREMENTAL_UPDATING</code>.</p>
	 * 
	 * @param label the Gauge's label
	 * @param interactive tells whether the user can change the value
	 * @param maxValue the maximum value, or INDEFINITE
	 * @param initialValue the initial value in the range [0..maxValue], or one of CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, or INCREMENTAL_UPDATING if maxValue is INDEFINITE.
	 * @param style the CSS style for this item
	 * @throws IllegalArgumentException if maxValue is not positive for interactive gauges
	 * 												  or if maxValue is neither positive nor INDEFINITE for non-interactive gauges
	 * 												  or if initialValue is not one of CONTINUOUS_IDLE, INCREMENTAL_IDLE, CONTINUOUS_RUNNING, or INCREMENTAL_UPDATING for a non-interactive gauge with indefinite range
	 * @see #INDEFINITE
	 * @see #CONTINUOUS_IDLE
	 * @see #INCREMENTAL_IDLE
	 * @see #CONTINUOUS_RUNNING
	 * @see #INCREMENTAL_UPDATING