devicescreen.java

关于J4ME J2ME实例

package org.j4me.ui;

import java.util.*;
import javax.microedition.lcdui.*;
import org.j4me.logging.*;

/**
 * The <code>DeviceScreen</code> class is a base class for any screen that needs complete
 * control over how it is painted.  It is based on and similar to the MIDP
 * <code>Canvas</code> class.
 * <p>
 * This class removes the following methods from the MIDP <code>Canvas</code> class:
 * <ul>
 *  <li><code>isDoubleBuffered</code> - This class is always double buffered.
 *  <li><code>hasPointerEvents</code> and <code>hasPointerMotionEvents</code> - There is
 *      no use for this method.  Implement the pointer event methods and
 *      if the device has no pointer they will be ignored.  
 *  <li> - Same reason as <code>hasPointerEvents</code>.
 *  <li><code>hasRepeatEvents</code> - This class always has key repeat events.
 *  <li><code>getKeyName</code> - The application should define the names to make them
 *      consistent across all devices.
 *  <li><code>getKeyCode</code> - The key code is passed into the key event methods.
 *  <li><code>getGameAction</code> - The game action is passed into the key event methods.
 *  <li><code>sizeChanged</code> - This method is notoriously buggy and applications
 *      should use <code>getWidth</code> and <code>getHeight</code> instead.
 *  <li><code>getTicker</code> and <code>setTicker</code> - The ticker functionality has
 *      not been implemented.
 *  <li><code>addCommand</code>, <code>removeCommand</code>, and <code>setCommandListener</code> -
 *      Menu options have been replaced with something that works across all
 *      MIDP 2.0 devices.  There are left and right menu options.  See
 *      <code>setMenuText</code> for details.
 * </ul>
 * 
 * @see javax.microedition.lcdui.Canvas
 */
public abstract class DeviceScreen
{
	/**
	 * Constant for the <code>LEFT</code> game action.
	 */
	public static final int LEFT = -1 * javax.microedition.lcdui.Canvas.LEFT;

	/**
	 * Constant for the <code>RIGHT</code> game action.
	 */
	public static final int RIGHT = -1 * javax.microedition.lcdui.Canvas.RIGHT;

	/**
	 * Constant for the <code>UP</code> game action.
	 */
	public static final int UP = -1 * javax.microedition.lcdui.Canvas.UP;

	/**
	 * Constant for the <code>DOWN</code> game action.
	 */
	public static final int DOWN = -1 * javax.microedition.lcdui.Canvas.DOWN;

	/**
	 * Constant for the <code>FIRE</code> game action.
	 */
	public static final int FIRE = -1 * javax.microedition.lcdui.Canvas.FIRE;

	/**
	 * Constant for the general purpose "A" game action.
	 */
	public static final int GAME_A = -1 * javax.microedition.lcdui.Canvas.GAME_A;

	/**
	 * Constant for the general purpose "B" game action.
	 */
	public static final int GAME_B = -1 * javax.microedition.lcdui.Canvas.GAME_B;

	/**
	 * Constant for the general purpose "C" game action.
	 */
	public static final int GAME_C = -1 * javax.microedition.lcdui.Canvas.GAME_C;

	/**
	 * Constant for the general purpose "D" game action.
	 */
	public static final int GAME_D = -1 * javax.microedition.lcdui.Canvas.GAME_D;

	/**
	 * <code>keyCode</code> for ITU-T key 0.
	 * <p>
	 * Constant value 48 is set to <code>KEY_NUM0</code>.
	 */
	public static final int KEY_NUM0 = javax.microedition.lcdui.Canvas.KEY_NUM0;

	/**
	 * <code>keyCode</code> for ITU-T key 1.
	 * <p>
	 * Constant value 49 is set to <code>KEY_NUM1</code>.
	 */
	public static final int KEY_NUM1 = javax.microedition.lcdui.Canvas.KEY_NUM1;

	/**
	 * <code>keyCode</code> for ITU-T key 2.
	 * <p>
	 * Constant value 50 is set to <code>KEY_NUM2</code>.
	 */
	public static final int KEY_NUM2 = javax.microedition.lcdui.Canvas.KEY_NUM2;

	/**
	 * <code>keyCode</code> for ITU-T key 3.
	 * <p>
	 * Constant value 51 is set to <code>KEY_NUM3</code>.
	 */
	public static final int KEY_NUM3 = javax.microedition.lcdui.Canvas.KEY_NUM3;

	/**
	 * <code>keyCode</code> for ITU-T key 4.
	 * <p>
	 * Constant value 52 is set to <code>KEY_NUM4</code>.
	 */
	public static final int KEY_NUM4 = javax.microedition.lcdui.Canvas.KEY_NUM4;

	/**
	 * <code>keyCode</code> for ITU-T key 5.
	 * <p>
	 * Constant value 53 is set to <code>KEY_NUM5</code>.
	 */
	public static final int KEY_NUM5 = javax.microedition.lcdui.Canvas.KEY_NUM5;

	/**
	 * <code>keyCode</code> for ITU-T key 6.
	 * <p>
	 * Constant value 54 is set to <code>KEY_NUM6</code>.
	 */
	public static final int KEY_NUM6 = javax.microedition.lcdui.Canvas.KEY_NUM6;

	/**
	 * <code>keyCode</code> for ITU-T key 7.
	 * <p>
	 * Constant value 55 is set to <code>KEY_NUM7</code>.
	 */
	public static final int KEY_NUM7 = javax.microedition.lcdui.Canvas.KEY_NUM7;

	/**
	 * <code>keyCode</code> for ITU-T key 8.
	 * <p>
	 * Constant value 56 is set to <code>KEY_NUM8</code>.
	 */
	public static final int KEY_NUM8 = javax.microedition.lcdui.Canvas.KEY_NUM8;

	/**
	 * <code>keyCode</code> for ITU-T key 9.
	 * <p>
	 * Constant value 57 is set to <code>KEY_NUM9</code>.
	 */
	public static final int KEY_NUM9 = javax.microedition.lcdui.Canvas.KEY_NUM9;

	/**
	 * <code>keyCode</code> for ITU-T key "pound" (#).
	 * <p>
	 * Constant value 35 is set to <code>KEY_POUND</code>.
	 */
	public static final int KEY_POUND = javax.microedition.lcdui.Canvas.KEY_POUND;

	/**
	 * <code>keyCode</code> for ITU-T key "star" (*).
	 * <p>
	 * Constant value 42 is set to <code>KEY_STAR</code>.
	 */
	public static final int KEY_STAR = javax.microedition.lcdui.Canvas.KEY_STAR;
	
	/**
	 * Constant for the left soft menu key found on MIDP 2.0 devices.
	 */
	public static final int MENU_LEFT = -21;
	
	/**
	 * Constant for the right soft menu key found on MIDP 2.0 devices.
	 */
	public static final int MENU_RIGHT = -22;
	
	/**
	 * The actual <code>Canvas</code> object that controls the device's screen.
	 * This object wraps it.
	 */
	private CanvasWrapper slave;

	/**
	 * When <code>false</code> this class will paint the menu bar at the bottom
	 * of the screen.  When <code>true</code> it will not. 
	 */
	private boolean fullScreenMode = false;
	
	/**
	 * What is written as a title bar for this canvas.  When this is <code>null</code>
	 * no title bar will be written.  To show the header without any text
	 * set this to the empty string "".
	 */
	private String title;
	
	/**
	 * The text for the left menu button.  This is the negative side used
	 * for canceling and going back to previous screens.
	 */
	private String leftMenu;
	
	/**
	 * The text for the right menu button.  This is the positive side used
	 * for accepting input, invoking menus, and moving forward in the
	 * application's state.
	 */
	private String rightMenu;
	
	/**
	 * Implicitly called by derived classes to setup a new J4ME canvas.
	 */
	public DeviceScreen ()
	{
		// Create a wrapper around the canvas.
		slave = new CanvasWrapper( this );
	}
	
	/**
	 * Makes this object take over the device's screen.
	 * <p>
	 * The previous screen will have its <code>hideNotify</code> method called.
	 * Then this screen's <code>showNotify</code> method will be invoked followed
	 * by the <code>paint</code> method.
	 */
	public void show ()
	{
		// Set the wrapped canvas as the current screen.
		UIManager.setScreen( this, slave );
	}
	
	/**
	 * Checks if this screen is actually visible on the display.  In
	 * order for a screen to be visible, all of the following must be true:
	 * the MIDlet must be running in the foreground, the screen must be the
	 * current one, and the screen must not be obscured by a system screen.
	 * 
	 * @return <code>true</code> if this screen is currently visible; <code>false</code>
	 *  otherwise.
	 */
	public boolean isShown ()
	{
		if ( UIManager.getScreen() == this )
		{
			return true;
		}
		else
		{
			return false;
		}
	}
	
	/**
	 * The implementation calls <code>showNotify()</code> immediately prior to
	 * this <code>Canvas</code> being made visible on the display.  <code>Canvas</code>
	 * subclasses may override this method to perform tasks before being
	 * shown, such as setting up animations, starting timers, etc.  The
	 * default implementation of this method in class <code>Canvas</code> is empty.
	 */
	public void showNotify ()
	{
	}
	
	/**
	 * The implementation calls <code>hideNotify()</code> shortly after the
	 * <code>Canvas</code> has been removed from the display.  <code>Canvas</code>
	 * subclasses may override this method in order to pause animations,
	 * revoke timers, etc.  The default implementation of this method in
	 * class <code>Canvas</code> is empty.
	 */
	public void hideNotify ()
	{
	}

	/**
	 * Shows or hides the menu bar at the bottom of the screen.
	 * 
	 * @param mode is <code>true</code> if the <code>DeviceScreen</code> is to be in full
	 *  screen mode, <code>false</code> otherwise.
	 */
	public void setFullScreenMode (boolean mode)
	{
		this.fullScreenMode = mode;
	}
	
	/**
	 * Returns if the title bar and menu bar are hidden or not.
	 *  
	 * @return <code>true</code> if in full screen mode (title bar and menu
	 *  bar are hidden); <code>false</code> otherwise.
	 */
	public boolean isFullScreenMode ()
	{
		return fullScreenMode;
	}
	
	/**
	 * Gets the title of this screen.  If this returns <code>null</code> the
	 * screen has no title.
	 * 
	 * @return The title of this screen.
	 */
	public String getTitle ()
	{
		return title;
	}

	/**
	 * Sets the title of this screen.  The default is <code>null</code> meaning no
	 * title.
	 * <p>
	 * For the title to be visible full screen mode must be off.
	 * This can be done with the <code>setFullScreenMode</code> method.
	 * 
	 * @param title is the new title for the screen.
	 */
	public void setTitle (String title)
	{
		this.title = title;
		
		// Notify the slave screen.
		slave.setTitle( title );
		slave.repaint();
	}
	
	/**
	 * Returns if this screen displays a title bar at the top.  Title
	 * bars require both setting a title (through <code>setTitle</code>) and
	 * that full screen mode is off (<code>setFullScreenMode(false)</code>).
	 * 
	 * @return <code>true</code> if the screen has a title bar; <code>false</code>
	 *  if it does not.
	 */
	public boolean hasTitleBar ()
	{
		// Full screen mode off?
		if ( fullScreenMode == false )
		{
			// There is some title?
			if ( title != null )
			{
				// Device supports title bars?
				if ( slave.supportsTitleBar() )
				{
					return true;
				}
			}
		}
		
		// If we made it here no title bar should be displayed.
		return false;
	}
	
	/**
	 * Returns the title of this screen.
	 * 
	 * @return The title of this screen.  If no title is set this returns
	 *  the empty string "".
	 */
	public String toString ()
	{
		if ( title == null )
		{
			return "";
		}
		else
		{
			return title;
		}
	}

	/**
	 * Sets the menu bar text.
	 * <p>
	 * For the menu to be visible full screen mode must be off.
	 * This can be done with the <code>setFullScreenMode</code> method.
	 * 
	 * @param left is the text for the negative menu option or <code>null</code>
	 *  to remove the button.  Negative menu options are things like canceling
	 *  a form and moving back to a previous screen.
	 * @param right is the text for the positive menu option or <code>null</code>
	 *  to remove the button.  Positive menu options are things like accepting
	 *  a form, advancing to the next screen, or displaying a menu.
	 * @see #declineNotify()
	 * @see #acceptNotify()
	 */
	public void setMenuText (String left, String right)
	{
		this.leftMenu = left;
		this.rightMenu = right;
		
		// Notify the slave screen.
		slave.setMenuText( left, right );
		slave.repaint();
	}
	
	/**
	 * Returns the text for the left menu button.  The left menu button is
	 * for negative operations such as canceling a form and going back to
	 * a previous screen.
	 * 
	 * @return The text for the left menu button.  If there is no button
	 *  this returns <code>null</code>.
	 */
	public String getLeftMenuText ()
	{
		return leftMenu;
	}
	
	/**
	 * Returns the text for the right menu button.  The right menu button is
	 * for positive operations such as accepting a form and opening a menu.
	 * 
	 * @return The text for the right menu button.  If there is no button
	 *  this returns <code>null</code>.
	 */
	public String getRightMenuText ()
	{
		return rightMenu;
	}
	
	/**
	 * Returns if this screen displays a menu bar at the bottom.  Menu bars
	 * require both setting at least one menu option (through
	 * <code>setMenuText</code>) and that full screen mode is off
	 * (<code>setFullScreenMode(false)</code>).
	 * 
	 * @return <code>true</code> if the screen has a menu bar; <code>false</code>
	 *  if it does not.
	 */
	public boolean hasMenuBar ()