customitem.java

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

//#condition polish.usePolishGui
/*
 * 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 javax.microedition.lcdui.Canvas;
import javax.microedition.lcdui.Font;
import javax.microedition.lcdui.Graphics;

/**
 * A CustomItem is customizable by subclassing to introduce new visual and interactive elements into <code>Forms</code>.
 * 
 * <p><b>J2ME Polish Implementation</b><br/>
 * <br/>
 * <b>Initialisation</b><br/>
 * J2ME Polish calls the getPrefContentWidth()-method first with an open height (-1).
 * Then the getPrefContentHeight()-method is called with the actual granted width.
 * When the width had to be adjusted, the custom item will be notified again with
 * the setSize(width. height)-method.
 * 
 * <br/><br/><b>Traversal</b><br/>
 * When the custom item gains the focus for the first time, the traverse-method
 * will be called with the appropriate direction(either Canvas.UP, DOWN, LEFT, RIGHT 
 * or CustomItem.NONE, when the direction is not known).
 * 
 * <br/><br/><b>Interaction Modes</b><br/>
 * The J2ME燩olish implementation supports the interaction modes KEY_PRESS,  
 * TRAVERSE_HORIZONTAL and TRAVERSE_VERTICAL.
 * </p>
 * 
 * <p>Subclasses are responsible for their visual
 * appearance including sizing and rendering and choice of colors, fonts and
 * graphics.  Subclasses are responsible for the user interaction mode by
 * responding to events generated by keys, pointer actions, and traversal
 * actions.  Finally, subclasses are responsible for calling 
 * <A HREF="../../../de/enough/polish/ui/Item.html#notifyStateChanged()"><CODE>Item.notifyStateChanged()</CODE></A> to trigger notification of listeners that the
 * <code>CustomItem's</code> value has changed.
 * </p>
 * 
 * <p>Like other <code>Items</code>, <code>CustomItems</code>
 * have the concept of <em>minimum</em> and
 * <em>preferred</em> sizes.  These pertain to the total area
 * of the <code>Item</code>,
 * which includes space for the content, label, borders, etc.  See <a
 * href="Item.html#sizes">Item Sizes</a> for a full discussion of the
 * areas and sizes of <code>Items</code>.</p>
 * 
 * <p><code>CustomItem</code> subclasses also have the concept
 * of the <em>content</em> size, which is the size of only the
 * content area of the <code>CustomItem</code>.  The
 * content area is a rectangular area inside the total area occupied by the
 * <code>CustomItem</code>.
 * The content area is the area within which the <code>CustomItem</code>
 * subclass paints and receives input events.  It does not include space
 * consumed by labels and borders.  The implementation is responsible for
 * laying out, painting, and handling input events within the area
 * of the <code>Item</code> that is outside the content area.</p>
 * 
 * <p>All coordinates passed between the implementation and
 * the <code>CustomItem</code>
 * subclass are relative to the item's content area, with the upper-left
 * corner of this area being located at <code>(0,0)</code>.
 * Size information passed
 * between the implementation and the <code>CustomItem</code> subclass with the
 * 
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentHeight()"><CODE>getMinContentHeight</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentWidth()"><CODE>getMinContentWidth</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentHeight(int)"><CODE>getPrefContentHeight</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentWidth(int)"><CODE>getPrefContentWidth</CODE></A>, and
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A>
 * 
 * methods all refer to the size of the content area.  The implementation is
 * responsible for computing and maintaining the difference between the size
 * of the content area and the size of the total area of the
 * <code>Item</code> as reported by the Item size methods
 * 
 * <A HREF="../../../de/enough/polish/ui/Item.html#getMinimumHeight()"><CODE>Item.getMinimumHeight</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/Item.html#getMinimumWidth()"><CODE>Item.getMinimumWidth</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/Item.html#getPreferredHeight()"><CODE>Item.getPreferredHeight</CODE></A>, and
 * <A HREF="../../../de/enough/polish/ui/Item.html#getPreferredWidth()"><CODE>Item.getPreferredWidth</CODE></A>.</p>
 * 
 * <p>The implementation may disregard sizing information returned from a
 * <code>CustomItem</code> if it exceeds limits imposed by the
 * implementation's user interface policy.  In
 * this case, the implementation must always report the actual size granted to
 * the <code>CustomItem</code> via the <A HREF="../../../de/enough/polish/ui/CustomItem.html#sizeChanged(int, int)"><CODE>sizeChanged</CODE></A>
 * and the <A HREF="../../../de/enough/polish/ui/CustomItem.html#paint(javax.microedition.lcdui.Graphics, int, int)"><CODE>paint</CODE></A> methods.
 * For example, this situation may occur if the implementation
 * prohibits an <code>Item</code> from becoming wider than the screen.  If the
 * <code>CustomItem</code> subclass code returns a value from
 * <code>getMinContentWidth</code> that would result in the
 * <code>CustomItem</code> being wider than the screen, the implementation may
 * assign a width smaller than the minimum width returned by
 * <code>getMinContentWidth</code>.</p>
 * 
 * <p>The implementation is allowed to call the <code>CustomItem's</code>
 * content size methods
 * 
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentHeight()"><CODE>getMinContentHeight</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getMinContentWidth()"><CODE>getMinContentWidth</CODE></A>,
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentHeight(int)"><CODE>getPrefContentHeight</CODE></A>, and
 * <A HREF="../../../de/enough/polish/ui/CustomItem.html#getPrefContentWidth(int)"><CODE>getPrefContentWidth</CODE></A>,
 * 
 * in any order with respect to other <code>CustomItem</code> methods.
 * For all of these methods, the <code>CustomItem</code> subclass code must
 * return values that are consistent with the current contents of the
 * <code>CustomItem</code>.  If the contents changes, it is not sufficient for
 * the <code>CustomItem</code> subclass code simply to begin returning
 * different values from the content size methods.  Instead, the subclass code
 * must call the <A HREF="../../../de/enough/polish/ui/CustomItem.html#invalidate()"><CODE>invalidate</CODE></A> method whenever its contents
 * changes.  This indicates to the implementation that it may need to perform
 * its layout computation, which will call the content size methods to get new
 * values based on the <code>CustomItem's</code> new contents.</p>
 * 
 * <a name="interaction"></a>
 * <h2>Interaction Modes</h2>
 * <p>The <code>CustomItem</code> class is intended to allow
 * edit-in-place on many items,
 * but it does not allow every conceivable interaction.  Desire for
 * flexibility has been balanced against a requirement that these APIs be
 * simple enough to master easily, along with a need to allow for
 * platform-specific variations in look-and-feel, all without sacrificing
 * interoperability.</p>
 * 
 * <p>The general idea is that there are multiple interaction
 * &quot;modes&quot; and that the <code>Form</code>
 * implementation can convey which
 * ones it supports.  The <code>CustomItem</code> can then choose to
 * support one or more interaction modes.  There is no requirement for a
 * <code>CustomItem</code> to implement all combinations of
 * all interaction modes.
 * Typically, a <code>CustomItem</code> will implement an
 * approach (such as the separate
 * editing screen technique discussed below) that works on all platforms,
 * in addition to a highly interactive approach that relies on a particular
 * interaction mode.  At run time, the <code>CustomItem</code>
 * code can query the system
 * to determine whether this interaction mode is supported.  If it is, the
 * <code>CustomItem</code> can use it; otherwise, it will fall
 * back to the approach that works on all platforms. </p>
 * 
 * <p><code>CustomItem</code> can always use item commands to invoke
 * a separate editing screen,
 * although components with a small number of discrete
 * states could simply respond by changing the state and
 * then causing an <code>notifyStateChanged</code> notification.
 * A technique for using a
 * separate editing screen would be to load the value into another
 * <code>Displayable</code> object (such as a List) and then to call
 * <A HREF="../../../javax/microedition/lcdui/Display.html#setCurrent(javax.microedition.lcdui.Displayable)"><CODE>Display.setCurrent(Displayable)</CODE></A> on it.
 * When the user
 * issues a command (such as &quot;OK&quot;) to indicate that
 * editing of this value is
 * complete, the listener can retrieve the value from that
 * <code>Displayable</code> object
 * and then call
 * <A HREF="../../../javax/microedition/lcdui/Display.html#setCurrentItem(javax.microedition.lcdui.Item)"><CODE>Display.setCurrentItem(Item)</CODE></A> to return to this item.</p>
 * 
 * <a name="keypad"></a>
 * <h2>Keypad Input</h2>
 * 
 * <p>The implementation may optionally support delivery of keypad events to
 * the <code>CustomItem</code>.  The implementation indicates
 * the level of support by
 * setting the <code>KEY_PRESS</code>, <code>KEY_RELEASE</code>, and
 * <code>KEY_REPEAT</code> bits in the value
 * returned by <code>getInteractionModes</code>.
 * Events corresponding to these bits are
 * delivered through calls to the <code>keyPressed()</code>,
 * <code>keyReleased()</code>, and
 * <code>keyRepeated()</code> methods, respectively.
 * If an implementation supports
 * <code>KEY_RELEASE</code> events, it must also support
 * <code>KEY_PRESS</code> events.  If an
 * implementation supports <code>KEY_REPEAT</code> events, it must also
 * support <code>KEY_PRESS</code>
 * and <code>KEY_RELEASE</code> events.  If supported,
 * <code>KEY_RELEASE</code> events will generally
 * occur after a corresponding <code>KEY_PRESS</code> event is
 * received, and <code>KEY_REPEAT</code>
 * events will generally occur between <code>KEY_PRESS</code> and
 * <code>KEY_RELEASE</code> events.
 * However, it is possible for the <code>CustomItem</code> to receive
 * <code>KEY_RELEASE</code> or
 * <code>KEY_REPEAT</code> events without a corresponding
 * <code>KEY_PRESS</code> if a key is down when
 * the <code>CustomItem</code> becomes visible.</p>
 * 
 * <p>Key event methods are passed the <code>keyCode</code>
 * indicating the key on which the
 * event occurred.  Implementations must provide means for the user to
 * generate events with key codes <code>Canvas.KEY_NUM0</code>
 * through <code>Canvas.KEY_NUM9</code>,
 * <code>Canvas.KEY_STAR</code>, and <code>Canvas.KEY_POUND</code>.
 * Implementations may also deliver
 * key events for other keys, include device-specific keys.
 * The set of keys
 * available to a <code>CustomItem</code> may differ depending
 * upon whether commands have been added to it.</p>
 * 
 * <p>The application may map key codes to game actions through use of the
 * <code>getGameAction</code> method.
 * If the implementation supports key events on
 * <code>CustomItems</code>, the implementation must provide a
 * sufficient set of key codes
 * and a mapping to game actions such that all game actions are available to
 * <code>CustomItems</code>.</p>
 * 
 * <p>The set of keys and the key events available to a
 * <code>CustomItem</code> may differ
 * from what is available on a <code>Canvas</code>.
 * In particular, on a system that
 * supports traversal, the system might use directional keys for traversal and
 * elect not to deliver these keys to <code>CustomItems</code>.
 * The mapping between key
 * codes and game actions in a <code>CustomItem</code> may differ
 * from the mapping in a <code>Canvas</code>.  See
 * <a href="Canvas.html#keyevents">Key Events</a>
 * and
 * <a href="Canvas.html#gameactions">Game Actions</a>
 * on class <code>Canvas</code> for further information about key codes and game
 * actions.</p>
 * 
 * <a name="pointer"></a>
 * <h2>Pointer Input</h2>
 * 
 * <p>The implementation may optionally support delivery of pointer events
 * (such as taps with a stylus) to the <code>CustomItem</code>.
 * The implementation
 * indicates the level of support by setting the <code>POINTER_PRESS</code>,
 * <code>POINTER_RELEASE</code>, and <code>POINTER_DRAG</code> bits
 * in the value returned by <code>getInteractionModes</code>.
 * Events corresponding to these bits are delivered
 * through calls to the <code>pointerPressed()</code>,
 * <code>pointerReleased()</code>, and
 * <code>pointerDragged()</code> methods, respectively.
 * If an implementation supports
 * <code>POINTER_RELEASE</code> events, it must also support
 * <code>POINTER_PRESS</code> events.  If an
 * implementation supports <code>POINTER_DRAG</code> events,
 * it must also support
 * <code>POINTER_PRESS</code> and <code>POINTER_RELEASE</code> events.
 * If supported, <code>POINTER_RELEASE</code>
 * events will generally occur after a corresponding
 * <code>POINTER_PRESS</code> event is
 * received, and <code>POINTER_DRAG</code> events will generally occur between
 * <code>POINTER_PRESS</code> and <code>POINTER_RELEASE</code> events.
 * However, it is possible for the
 * <code>CustomItem</code> to receive <code>POINTER_RELEASE</code>
 * or <code>POINTER_DRAG</code> events without a
 * corresponding <code>POINTER_PRESS</code> if the pointer is
 * down when the <code>CustomItem</code> becomes visible.</p>
 * 
 * <p>The <code>(x,y)</code> location of the pointer event is
 * reported with every pointer