customitem.java

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

 * event.  This location is expressed in the coordinate system of the
 * <code>CustomItem</code>, where <code>(0,0)</code> is the upper-left
 * corner of the <code>CustomItem</code>.  Under
 * certain circumstances, pointer events may occur outside the bounds of the
 * item. </p>
 * 
 * <h2>Traversal</h2>
 * 
 * <p>An implementation may support traversal <em>internal</em> to a
 * <code>CustomItem</code>, that is, the implementation
 * may temporarily delegate the
 * responsibility for traversal to the item itself.  Even if there is only one
 * traversal location inside the <code>CustomItem</code>,
 * the item may want support the
 * internal traversal protocol so that it can perform specialized
 * highlighting, animation, etc. when the user has traversed into it.</p>
 * 
 * <p>The implementation indicates its support for traversal internal to a
 * <code>CustomItem</code> by setting one or both of the
 * <code>TRAVERSE_HORIZONTAL</code> or
 * <code>TRAVERSE_VERTICAL</code> bits in the value returned by
 * <code>getInteractionModes()</code>. If
 * neither of these bits is set, the implementation is unwilling to let
 * <code>CustomItems</code> traverse internally, or the
 * implementation does not support
 * traversal at all.  If the implementation does support traversal but has
 * declined to permit traversal internal to <code>CustomItems</code>,
 * the implementation
 * will supply its own highlighting outside the
 * <code>CustomItem's</code> content area.</p>
 * 
 * <p>The <code>CustomItem</code> need not support internal
 * traversal at all.  It can do
 * this by returning <code>false</code> to the initial call to the
 * <code>traverse</code> method.  (This is the default behavior if this method
 * hasn't been overridden by the <code>CustomItem</code>.)
 * If this occurs, the system must
 * arrange for the user to be able to traverse onto and past this item.  The
 * system must also arrange for proper scrolling to take place, particularly
 * if the item exceeds the height of the screen, regardless of whether
 * internal traversal is occurring.</p>
 * 
 * <p>An implementation may provide support for delivering keypad or pointer
 * events to <code>CustomItems</code> even if it has declined
 * to support delivering traverse events to <code>CustomItems</code>.
 * If an implementation provides support for
 * delivering keypad or pointer events to <code>CustomItems</code>,
 * it must provide a means
 * to do so for every <code>CustomItem</code>, even for those
 * that have refused internal
 * traversal by returning <code>false</code> to the initial
 * <code>traverse()</code> call.
 * This implies that such implementations must still support some notion
 * of focus for an item, even if that item is not supporting internal
 * traversal.</p>
 * 
 * <p>See the documentation for the
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#traverse(int, int, int, int[])"><CODE>traverse</CODE></A> method for a full
 * specification of the behavior and responsibilities required for the item to
 * perform internal traversal.</p>
 * 
 * <h2>Item Appearance</h2>
 * 
 * <p>The visual appearance of each item consists of a
 * label (handled by the implementation)
 * and its contents (handled by the subclass).</p>
 * 
 * <p>Labels are the responsibility of the implementation, not the item.  The
 * screen area that is allocated to the <code>CustomItem</code>
 * for its contents is
 * separate from the area that the implementation uses to display the
 * <code>CustomItem's</code> label.
 * The implementation controls the rendering of the label
 * and its layout with respect to the content area.</p>
 * 
 * <p>The <code>CustomItem</code> is responsible for
 * painting its contents whenever
 * the <code>paint</code> method is called.</p>
 * 
 * <p>The colors for foreground, background, highlighted foreground,
 * highlighted background, border, and highlighted border should be
 * retrieved from <A HREF="../../../javax/microedition/lcdui/Display.html#getColor(int)"><CODE>Display.getColor(int)</CODE></A>.
 * This will allow <code>CustomItems</code> to
 * match the color scheme of other items provided with the device.
 * The <code>CustomItem</code> is responsible for keeping
 * track of its own highlighted and
 * unhighlighted state.</p>
 * 
 * <p>The fonts used should be retrieved from 
 * <A HREF="../../../javax/microedition/lcdui/Font.html#getFont(int)"><CODE>Font.getFont(int)</CODE></A>.
 * This will allow them to match the fonts used by other items
 * on the device for a consistent visual appearance. </p>
 * <HR>
 * 
 * 
 * @since MIDP 2.0
 */
public abstract class CustomItem extends Item
{
	/**
	 * Interaction mode bit indicating support of horizontal traversal
	 * internal to the <code>CustomItem</code>.
	 * 
	 * <p><code>TRAVERSE_HORIZONTAL</code> has the value <code>1</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#traverse(int, int, int, int[])"><CODE>traverse(int, int, int, int[])</CODE></A>
	 */
	protected static final int TRAVERSE_HORIZONTAL = 1;

	/**
	 * Interaction mode bit indicating support for vertical traversal
	 * internal to the <code>CustomItem</code>.
	 * 
	 * <p><code>TRAVERSE_VERTICAL</code> has the value <code>2</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#traverse(int, int, int, int[])"><CODE>traverse(int, int, int, int[])</CODE></A>
	 */
	protected static final int TRAVERSE_VERTICAL = 2;

	/**
	 * Interaction mode bit indicating support for key pressed events.
	 * 
	 * <p><code>KEY_PRESS</code> has the value <code>4</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#keyPressed(int)"><CODE>keyPressed(int)</CODE></A>
	 */
	protected static final int KEY_PRESS = 4;

	/**
	 * Interaction mode bit indicating support for key released events.
	 * 
	 * <p><code>KEY_RELEASE</code> has the value <code>8</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#keyReleased(int)"><CODE>keyReleased(int)</CODE></A>
	 */
	protected static final int KEY_RELEASE = 8;

	/**
	 * Interaction mode bit indicating support for key repeated events.
	 * 
	 * <p><code>KEY_REPEAT</code> has the value <code>0x10</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#keyRepeated(int)"><CODE>keyRepeated(int)</CODE></A>
	 */
	protected static final int KEY_REPEAT = 0x10;

	/**
	 * Interaction mode bit indicating support for point pressed events.
	 * 
	 * <p><code>POINTER_PRESS</code> has the value <code>0x20</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#pointerPressed(int, int)"><CODE>pointerPressed(int, int)</CODE></A>
	 */
	protected static final int POINTER_PRESS = 0x20;

	/**
	 * Interaction mode bit indicating support for point released events.
	 * 
	 * <p><code>POINTER_RELEASE</code> has the value<code> 0x40</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#pointerReleased(int, int)"><CODE>pointerReleased(int, int)</CODE></A>
	 */
	protected static final int POINTER_RELEASE = 0x40;

	/**
	 * Interaction mode bit indicating support for point dragged events.
	 * 
	 * <p><code>POINTER_DRAG</code> has the value <code>0x80</code>.</p>
	 * <DT><B>See Also: </B>
	 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#pointerDragged(int, int)"><CODE>pointerDragged(int, int)</CODE></A>
	 */
	protected static final int POINTER_DRAG = 0x80;

	/**
	 * A value for traversal direction that indicates that traversal has
	 * entered or has changed location within this item, but that no specific
	 * direction is associated with this traversal event.
	 * 
	 * <p><code>NONE</code> has the value <code>0</code>.</p>
	 * <DT><B>See Also: </B>
	 */
	protected static final int NONE = 0;

	//#ifdef polish.hasPointerEvents
		//# private static final int INTERACTION_MODES = KEY_PRESS | KEY_RELEASE | POINTER_PRESS | TRAVERSE_HORIZONTAL | TRAVERSE_VERTICAL;
	//#else
		private static final int INTERACTION_MODES = KEY_PRESS | KEY_RELEASE | TRAVERSE_HORIZONTAL | TRAVERSE_VERTICAL;
	//#endif
	//#if polish.css.skip-set-clip
		//# protected boolean skipClipping;
	//#endif
	/** the font which is set in each paint() method */
	private static final Font DEFAULT_FONT = Font.getDefaultFont();
	private int[] visRect_inout = new int[4];
	private int clipHeight;
	private int clipWidth;


	/**
	 * Superclass constructor, provided so that the
	 * <code>CustomItem</code> subclass can specify its label.
	 * 
	 * @param label the CustomItem's label
	 */
	protected CustomItem( String label)
	{
		this( label, null );
	}

	/**
	 * Superclass constructor for J2ME Polish, provided so that the
	 * <code>CustomItem</code> subclass can specify its label.
	 * 
	 * @param label the CustomItem's label
	 * @param style the Style which is associated with this item
	 */
	protected CustomItem( String label, Style style )
	{
		super( label, PLAIN, INTERACTIVE, style );
		this.visRect_inout = new int[4];
	}

	
	/**
	 * Gets the game action associated with the given key code of the
	 * device.  Returns zero if no game action is associated with this key
	 * code.  See the
	 * <a href="Canvas.html#gameactions">Game Actions</a>
	 * section of class <code>Canvas</code> for further discussion
	 * of game actions.
	 * 
	 * <p>The mapping of key codes to game actions may differ between
	 * <code>CustomItem</code> and <code>Canvas</code>.</p>
	 * 
	 * @param keyCode the key code
	 * @return the game action corresponding to this key, or 0 if none
	 * @throws IllegalArgumentException if keyCode is not a valid key code
	 */
	public int getGameAction(int keyCode)
	{
		if (this.screen == null) {
			this.screen = getScreen();
			if (this.screen == null) {
				return 0;
			}
		}
		return this.screen.getGameAction(keyCode);
	}

	/**
	 * Gets the available interaction modes.
	 * <p>For J2ME Polish components following modes can be supported supported:
	 * <pre>
	 *   KEY_PRESS | KEY_RELEASE | KEY_REPEAT | POINTER_PRESS | TRAVERSE_HORIZONTAL | TRAVERSE_VERTICAL
	 *  </pre></p>
	 *  <ul>
	 *    <li><code>POINTER_PRESS</code> is only supported on devices that support pointers.</li>
	 *    <li><code>KEY_REPEAT</code> events are supported where the native Canvas implementation supports these events.</li>
	 *    <li><code></code> .</li>
	 *    <li><code></code> .</li>
	 *  </ul>
	 * This method is intended to be
	 * called by <code>CustomItem</code> subclass code in order
	 * for it to determine what
	 * kinds of input are available from this device.  The modes available may
	 * be dependent upon several factors: the hardware keys on the actual
	 * device, which of these keys are needed for the system to do proper
	 * navigation, the presence of a pointing device, etc.  See <a
	 * href="#interaction">Interaction Modes</a> for further discussion.  If
	 * this method returns <code>0</code>, the only interaction available
	 * is through item commands.
	 * 
	 * @return a bitmask of the available interaction modes
	 */
	protected final int getInteractionModes()
	{