alert.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 Sun Feb 29 19:10:57 CET 2004
package de.enough.polish.ui;

import javax.microedition.lcdui.AlertType;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Image;

import de.enough.polish.util.Locale;


/**
 * An alert is a screen that shows data to the user and waits for a certain
 * period of time before proceeding to the next
 * <code>Displayable</code>. An alert can
 * contain a text string and an image.
 * The intended use of <code>Alert</code> is to inform the user about
 * errors and other
 * exceptional conditions.
 * 
 * <P>The application can set the alert time to be infinity with
 * <code> setTimeout(Alert.FOREVER)</code>
 * in which case the <code>Alert</code> is considered to be <em>modal</em> and
 * the implementation provide a feature that allows the
 * user to &quot;dismiss&quot; the alert, whereupon the next
 * <code>Displayable</code>
 * is displayed as if the timeout had expired immediately.</P>
 * 
 * <P>If an application specifies an alert to be of a
 * timed variety <em>and</em> gives it too much content such that it must
 * scroll,
 * then it automatically becomes a modal alert.</P>
 * 
 * <P> An alert may have an <code>AlertType</code> associated with it
 * to provide an indication of the nature of the alert.
 * The implementation may use this type to play an
 * appropriate sound when the <code>Alert</code> is presented to the user.
 * See <A HREF="../../../javax/microedition/lcdui/AlertType.html#playSound(javax.microedition.lcdui.Display)"><CODE>AlertType.playSound()</CODE></A>.</P>
 * 
 * <P>An alert may contain an optional <code>Image</code>.  The
 * <code>Image</code> may be mutable or
 * immutable.  If the <code>Image</code> is mutable, the effect is as
 * if a snapshot of its
 * contents is taken at the time the <code>Alert</code> is constructed
 * with this <code>Image</code> and
 * when <code>setImage</code> is called with an <code>Image</code>.
 * This snapshot is used whenever the contents of the
 * <code>Alert</code> are to be
 * displayed.  Even if the application subsequently draws into the
 * <code>Image</code>, the
 * snapshot is not modified until the next call to <code>setImage</code>.  The
 * snapshot is <em>not</em> updated when the <code>Alert</code>
 * becomes current or becomes
 * visible on the display.  (This is because the application does not have
 * control over exactly when <code>Displayables</code> appear and
 * disappear from the
 * display.)</P>
 * 
 * <a name="indicator"></a>
 * <h3>Activity Indicators</h3>
 * 
 * <P>An alert may contain an optional <A HREF="../../../javax/microedition/lcdui/Gauge.html"><CODE>Gauge</CODE></A> object that is used as an
 * activity or progress indicator.  By default, an <code>Alert</code>
 * has no activity
 * indicator; one may be set with the <A HREF="../../../javax/microedition/lcdui/Alert.html#setIndicator(javax.microedition.lcdui.Gauge)"><CODE>setIndicator(javax.microedition.lcdui.Gauge)</CODE></A> method.
 * The <code>Gauge</code>
 * object used for the activity indicator must conform to all of the following
 * restrictions:</P>
 * 
 * <ul>
 * <li>it must be non-interactive;</li>
 * <li>it must not be owned by another container (<code>Alert</code>
 * or <code>Form</code>);</li>
 * <li>it must not have any <code>Commands</code>;</li>
 * <li>it must not have an <code>ItemCommandListener</code>;</li>
 * <li>it must not have a label (that is, its label must be
 * <code>null</code>;</li>
 * <li>its preferred width and height must both be unlocked; and</li>
 * <li>its layout value must be <code>LAYOUT_DEFAULT</code>.</li>
 * </ul>
 * 
 * <P>It is an error for the application to attempt to use a
 * <code>Gauge</code> object that
 * violates any of these restrictions.  In addition, when the
 * <code>Gauge</code> object is
 * being used as the indicator within an <code>Alert</code>, the
 * application is prevented
 * from modifying any of these pieces of the <code>Gauge's</code> state.</P>
 * 
 * <a name="commands"></a>
 * <h3>Commands and Listeners</h3>
 * 
 * <P>Like the other <code>Displayable</code> classes, an
 * <code>Alert</code> can accept <code>Commands</code>, which
 * can be delivered to a <code>CommandListener</code> set by the
 * application.  The <code>Alert</code>
 * class adds some special behavior for <code>Commands</code> and listeners.</P>
 * 
 * <P>When it is created, an <code>Alert</code> implicitly has the
 * special <code>Command</code>
 * <A HREF="../../../javax/microedition/lcdui/Alert.html#DISMISS_COMMAND"><CODE>DISMISS_COMMAND</CODE></A> present on it.  If the application adds any
 * other <code>Commands</code> to the <code>Alert</code>,
 * <code>DISMISS_COMMAND</code> is implicitly removed.  If the
 * application removes all other <code>Commands</code>,
 * <code>DISMISS_COMMAND</code> is implicitly
 * restored.  Attempts to add or remove <code>DISMISS_COMMAND</code>
 * explicitly are
 * ignored.  Thus, there is always at least one <code>Command</code>
 * present on an <code>Alert</code>.
 * </P>
 * 
 * <P>If there are two or more <code>Commands</code> present on the
 * <code>Alert</code>, it is
 * automatically turned into a modal <code>Alert</code>, and the
 * timeout value is always
 * <A HREF="../../../javax/microedition/lcdui/Alert.html#FOREVER"><CODE>FOREVER</CODE></A>.  The <code>Alert</code> remains on the display
 * until a <code>Command</code> is
 * invoked.  If the Alert has one Command (whether it is DISMISS_COMMAND or it
 * is one provided by the application), the <code>Alert</code> may have
 * the timed behavior
 * as described above.  When a timeout occurs, the effect is the same as if
 * the user had invoked the <code>Command</code> explicitly.</P>
 * 
 * <P>When it is created, an <code>Alert</code> implicitly has a
 * <code>CommandListener</code> called the
 * <em>default listener</em> associated with it.  This listener may be
 * replaced by an application-provided listener through use of the <A HREF="../../../javax/microedition/lcdui/Alert.html#setCommandListener(javax.microedition.lcdui.CommandListener)"><CODE>setCommandListener(javax.microedition.lcdui.CommandListener)</CODE></A> method.  If the application removes its listener by
 * passing <code>null</code> to the <code>setCommandListener</code> method,
 * the default listener is implicitly restored.</P>
 * 
 * <P>The <A HREF="../../../javax/microedition/lcdui/Display.html#setCurrent(javax.microedition.lcdui.Alert, javax.microedition.lcdui.Displayable)"><CODE>Display.setCurrent(Alert, Displayable)</CODE></A> method and the <A HREF="../../../javax/microedition/lcdui/Display.html#setCurrent(javax.microedition.lcdui.Displayable)"><CODE>Display.setCurrent(Displayable)</CODE></A> method (when called with an
 * <code>Alert</code>) define
 * special behavior for automatically advancing to another
 * <code>Displayable</code> after
 * the <code>Alert</code> is dismissed.  This special behavior occurs
 * only when the default
 * listener is present on the <code>Alert</code> at the time it is
 * dismissed or when a
 * command is invoked.  If the user invokes a <code>Command</code> and
 * the default listener
 * is present, the default listener ignores the <code>Command</code>
 * and implements the
 * automatic-advance behavior.</P>
 * 
 * <P>If the application has set its own <code>CommandListener</code>, the
 * automatic-advance behavior is disabled.  The listener code is responsible
 * for advancing to another <code>Displayable</code>.  When the
 * application has provided a
 * listener, <code>Commands</code> are invoked normally by passing
 * them to the listener's
 * <code>commandAction</code> method.  The <code>Command</code> passed
 * will be one of the
 * <code>Commands</code> present on the <code>Alert</code>: either
 * <code>DISMISS_COMMAND</code> or one of the
 * application-provided <code>Commands</code>.</P>
 * 
 * <P>The application can restore the default listener by passing
 * <code>null</code> to the <code>setCommandListener</code> method.</P>
 * 
 * <strong>Note:</strong> An application may set a <A HREF="../../../javax/microedition/lcdui/Ticker.html"><CODE>Ticker</CODE></A>
 * with <A HREF="../../../javax/microedition/lcdui/Displayable.html#setTicker(javax.microedition.lcdui.Ticker)"><CODE>Displayable.setTicker</CODE></A> on an
 * <code>Alert</code>, however it may not be displayed due to
 * implementation restrictions.
 * 
 * @since MIDP 1.0
 */
public class Alert 
extends Screen
implements CommandListener
{
	/**
	 * <code>FOREVER</code> indicates that an <code>Alert</code> is
	 * kept visible until the user
	 * dismisses it.  It is used as a value for the parameter to
	 * <A HREF="../../../javax/microedition/lcdui/Alert.html#setTimeout(int)"><CODE>setTimeout()</CODE></A>
	 * to indicate that the alert is modal.  Instead of waiting for a
	 * specified period of time, a modal <code>Alert</code> will wait
	 * for the user to take
	 * some explicit action, such as pressing a button, before proceeding to
	 * the next <code>Displayable</code>.
	 * 
	 * <P>Value <code>-2</code> is assigned to <code>FOREVER</code>.</P>
	 */
	public static final int FOREVER = -2;

	/**
	 * A <code>Command</code> delivered to a listener to indicate that
	 * the <code>Alert</code> has been
	 * dismissed.  This Command is implicitly present an on
	 * <code>Alert</code> whenever
	 * there are no other Commands present.  The field values of
	 * <code>DISMISS_COMMAND</code> are as follows:
	 * 
	 * <ul>
	 * <li>label = &quot;&quot; (an empty string)</li>
	 * <li>type = Command.OK</li>
	 * <li>priority = 0</li>
	 * </ul>
	 * 
	 * <p>The label value visible to the application must be as specified
	 * above.  However, the implementation may display
	 * <code>DISMISS_COMMAND</code> to the
	 * user using an implementation-specific label.</p>
	 * 
	 * <p>Attempting to add or remove <code>DISMISS_COMMAND</code>
	 * from an <code>Alert</code> has no
	 * effect.  However, <code>DISMISS_COMMAND</code> is treated as an
	 * ordinary <code>Command</code> if
	 * it is used with other <code>Displayable</code> types.</p>
	 * 
	 * 
	 * 
	 * @since MIDP 2.0
	 */
	//#ifdef polish.i18n.useDynamicTranslations
		//# public static Command DISMISS_COMMAND = StyleSheet.OK_CMD;
	//#else
		public static final Command DISMISS_COMMAND = StyleSheet.OK_CMD;
	//#endif

	private int timeout = FOREVER;
	private long showTime;
	private AlertType type;
	private IconItem iconItem;
	private Gauge indicator;

	//private AlertType alertType;
	protected Displayable nextDisplayable;
	
	//#if polish.css.show-dismiss-command
		private boolean showDismissCommand = true;
	//#endif

	private int numberOfCommands;

	/**
	 * Constructs a new, empty <code>Alert</code> object with the given title. 
	 * If <code>null</code> is
	 * passed, the <code>Alert</code> will have no title.  Calling
	 * this constructor is
	 * equivalent to calling
	 * 
	 * <pre>
	 * <code>Alert(title, null, null, null)</code>
	 * </pre>
	 * 
	 * @param title the title string, or null
	 * @see #Alert(String, String, Image, AlertType)
	 */
	public Alert( String title)
	{
		//#style alert, default
		this( title, null, null, null , de.enough.polish.ui.StyleSheet.alertStyle );
	}

	/**
	 * Constructs a new, empty <code>Alert</code> object with the given title. 
	 * If <code>null</code> is
	 * passed, the <code>Alert</code> will have no title.  Calling
	 * this constructor is
	 * equivalent to calling
	 * 
	 * <pre>
	 * <code>Alert(title, null, null, null)</code>
	 * </pre>
	 * 
	 * @param title the title string, or null
	 * @param style the style of this Alert
	 * @see #Alert(String, String, Image, AlertType)
	 */
	public Alert( String title, Style style )
	{
		this( title, null, null, null, style );
	}

	/**
	 * Constructs a new <code>Alert</code> object with the given title, content string and image, and alert type.
	 * 
	 * The layout of the contents is implementation dependent.
	 * The timeout value of this new alert is the same value that is
	 * returned by <code>getDefaultTimeout()</code>.
	 * The <code>Image</code> provided may either be mutable or immutable.
	 * The handling and behavior of specific <code>AlertTypes</code>
	 * is described in
	 * <A HREF="../../../javax/microedition/lcdui/AlertType.html"><CODE>AlertType</CODE></A>.  <code>null</code> is allowed as the value