item.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) 2003, 2004 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.Command;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Graphics;
import javax.microedition.lcdui.Image;
//#if polish.blackberry
	//# import net.rim.device.api.ui.Field;
//#endif

import de.enough.polish.util.ArrayList;
import de.enough.polish.util.HashMap;


/**
 * A superclass for components that can be added to a Form.
 * 
 * <p>Items support following CSS attributes:
 * </p>
 * <ul>
 * 		<li><b>margin, margin-left, margin-right, margin-top, margin-bottom, margin-vertical, margin-horizontal</b>: margins between border and next item.</li>
 * 		<li><b>padding, padding-left, padding-right, padding-top, padding-bottom, padding-vertical, padding-horizontal</b>: paddings between border and content.</li>
 * 		<li><b>background</b>: The background of this item.</li>
 * 		<li><b>border</b>: The border of this item.</li>
 * 		<li><b>min-width</b>: The minimum width of this item.</li>
 * 		<li><b>max-width</b>: The maximum width of this item.</li>
 * 		<li><b>min-height</b>: The minimum height of this item.</li>
 * 		<li><b>max-height</b>: The maximum height of this item.</li>
 * 		<li><b>before</b>: URL of image that should be placed before this item.</li>
 * 		<li><b>after</b>: URL of image that should be placed after this item.</li>
 * 		<li><b>include-label</b>: set to true when the background and border should include the label of this item as well.</li>
 * 		<li><b>colspan</b>: when this item is embedded in a table, you can span it over several cells, e.g. colspan: 2;.</li>
 * 		<li><b>label-style</b>: The name of the specialized label style for this item, e.g. "label-style: funnyLabel;"</li>
 * 		<li><b>focused-style</b>: The name of the specialized focused style for this item, e.g. "focused-style: funnyFocused;"</li>
 * 		<li><b>view-type</b>: The view of this item.</li>
 * </ul>
 * 
 * A superclass for components that can be added to a <A HREF="../../../javax/microedition/lcdui/Form.html"><CODE>Form</CODE></A>. All <code>Item</code> objects have a label field,
 * which is a string that is
 * attached to the item. The label is typically displayed near the component
 * when it is displayed within a screen.  The label should be positioned on
 * the same horizontal row as the item or
 * directly above the item.  The implementation should attempt to distinguish
 * label strings from other textual content, possibly by displaying the label
 * in a different font, aligning it to a different margin, or appending a
 * colon to it if it is placed on the same line as other string content.
 * If the screen is scrolling, the implementation should try
 * to keep the label visible at the same time as the <code>Item</code>.
 * 
 * <p>In some cases,
 * when the user attempts to interact with an <code>Item</code>,
 * the system will switch to
 * a system-generated screen where the actual interaction takes place. If
 * this occurs, the label will generally be carried along and displayed within
 * this new screen in order to provide the user with some context for the
 * operation. For this reason it is recommended that applications supply a
 * label to all interactive Item objects. However, this is not required, and
 * a <code>null</code> value for a label is legal and specifies
 * the absence of a label.
 * </p>
 * 
 * <h3>Item Layout</h3>
 * 
 * <p>An <code>Item's</code> layout within its container is
 * influenced through layout directives:</p>
 * 
 * <ul>
 * <li> <code>LAYOUT_DEFAULT</code> </li>
 * <li> <code>LAYOUT_LEFT</code> </li>
 * <li> <code>LAYOUT_RIGHT</code> </li>
 * <li> <code>LAYOUT_CENTER</code> </li>
 * <li> <code>LAYOUT_TOP</code> </li>
 * <li> <code>LAYOUT_BOTTOM</code> </li>
 * <li> <code>LAYOUT_VCENTER</code> </li>
 * <li> <code>LAYOUT_NEWLINE_BEFORE</code> </li>
 * <li> <code>LAYOUT_NEWLINE_AFTER</code> </li>
 * <li> <code>LAYOUT_SHRINK</code> </li>
 * <li> <code>LAYOUT_VSHRINK</code> </li>
 * <li> <code>LAYOUT_EXPAND</code> </li>
 * <li> <code>LAYOUT_VEXPAND</code> </li>
 * <li> <code>LAYOUT_2</code> </li>
 * </ul>
 * 
 * <p>The <code>LAYOUT_DEFAULT</code> directive indicates
 * that the container's default
 * layout policy is to be used for this item.
 * <code>LAYOUT_DEFAULT</code> has the value
 * zero and has no effect when combined with other layout directives.  It is
 * useful within programs in order to document the programmer's intent.</p>
 * 
 * <p>The <code>LAYOUT_LEFT</code>, <code>LAYOUT_RIGHT</code>, and
 * <code>LAYOUT_CENTER</code> directives indicate
 * horizontal alignment and are mutually exclusive.  Similarly, the
 * <code>LAYOUT_TOP</code>, <code>LAYOUT_BOTTOM</code>, and
 * <code>LAYOUT_VCENTER</code> directives indicate vertical
 * alignment and are mutually exclusive.</p>
 * 
 * <p>A horizontal alignment directive, a vertical alignment directive, and
 * any combination of other layout directives may be combined using the
 * bit-wise <code>OR</code> operator (<code>|</code>) to compose a
 * layout directive value.  Such a value
 * is used as the parameter to the <A HREF="../../../javax/microedition/lcdui/Item.html#setLayout(int)"><CODE>setLayout(int)</CODE></A> method and is the return
 * value from the <A HREF="../../../javax/microedition/lcdui/Item.html#getLayout()"><CODE>getLayout()</CODE></A> method.</p>
 * 
 * <p>Some directives have no defined behavior in some contexts.  A layout
 * directive is ignored if its behavior is not defined for the particular
 * context within which the <code>Item</code> resides.</p>
 * 
 * <p>A complete specification of the layout of <code>Items</code>
 * within a <code>Form</code> is given
 * <a href="Form.html#layout">here</a>.</p>
 * 
 * <a name="sizes"></a>
 * <h3>Item Sizes</h3>
 * 
 * <p><code>Items</code> have two explicit size concepts: the <em>minimum</em>
 * size and the
 * <em>preferred</em> size.  Both the minimum and the preferred sizes refer to
 * the total area of the <code>Item</code>, which includes space for the
 * <code>Item's</code> contents,
 * the <code>Item's</code> label, as well as other space that is
 * significant to the layout
 * policy.  These sizes do not include space that is not significant for
 * layout purposes.  For example, if the addition of a label to an
 * <code>Item</code> would
 * cause other <code>Items</code> to move in order to make room,
 * then the space occupied by
 * this label is significant to layout and is counted as part of
 * the <code>Item's</code>
 * minimum and preferred sizes.  However, if an implementation were to place
 * the label in a margin area reserved exclusively for labels, this would not
 * affect the layout of neighboring <code>Items</code>.
 * In this case, the space occupied
 * by the label would not be considered part of the minimum and preferred
 * sizes.</p>
 * 
 * <p>The minimum size is the smallest size at which the
 * <code>Item</code> can function and
 * display its contents, though perhaps not optimally.  The minimum size
 * may be recomputed whenever the <code>Item's</code> contents changes.</p>
 * 
 * <p>The preferred size is generally a size based on the
 * <code>Item's</code> contents and
 * is the smallest size at which no information is clipped and text wrapping
 * (if any) is kept to a tolerable minimum.  The preferred size may be
 * recomputed whenever the <code>Item's</code> contents changes.
 * The application can
 * <em>lock</em> the preferred width or preferred height (or both) by
 * supplying specific values for parameters to the <A HREF="../../../javax/microedition/lcdui/Item.html#setPreferredSize(int, int)"><CODE>setPreferredSize</CODE></A> method.  The manner in which an
 * <code>Item</code> fits its contents
 * within an application-specified preferred size is implementation-specific.
 * However, it is recommended that textual content be word-wrapped to fit the
 * preferred size set by the application.  The application can <em>unlock</em>
 * either or both dimensions by supplying the value <code>-1</code>
 * for parameters to the <code>setPreferredSize</code> method.</p>
 * 
 * <p>When an <code>Item</code> is created, both the preferred width
 * and height are
 * unlocked.  In this state, the implementation computes the preferred width
 * and height based on the <code>Item's</code> contents, possibly
 * including other relevant
 * factors such as the <code>Item's</code> graphic design and the
 * screen dimensions.
 * After having locked either the preferred width or height, the application
 * can restore the initial, unlocked state by calling
 * <code>setPreferredSize(-1,&nbsp;-1)</code>.</p>
 * 
 * <p>The application can lock one dimension of the preferred size and leave
 * the other unlocked.  This causes the system to compute an appropriate value
 * for the unlocked dimension based on arranging the contents to fit the
 * locked dimension.  If the contents changes, the size on the unlocked
 * dimension is recomputed to reflect the new contents, but the size on the
 * locked dimension remains unchanged.  For example, if the application called
 * <code>setPreferredSize(50,&nbsp;-1)</code>, the preferred width would be
 * locked at <code>50</code> pixels and the preferred height would
 * be computed based on the
 * <code>Item's</code> contents.  Similarly, if the application called
 * <code>setPreferredSize(-1,&nbsp;60)</code>, the preferred height would be
 * locked at <code>60</code> pixels and the preferred width would be
 * computed based on the
 * <code>Item's</code> contents.  This feature is particularly useful
 * for <code>Items</code> with
 * textual content that can be line wrapped.</p>
 * 
 * <p>The application can also lock both the preferred width and height to
 * specific values.  The <code>Item's</code> contents are truncated or padded
 * as necessary to honor this request.  For <code>Items</code> containing
 * text, the text should be wrapped to the specified width, and any truncation
 * should occur at the end of the text.</p>
 * 
 * <p><code>Items</code> also have an implicit maximum size provided by the
 * implementation.  The maximum width is typically based on the width of the
 * screen space available to a <code>Form</code>.  Since <code>Forms</code>
 * can scroll vertically, the maximum height should typically not be based on
 * the height of the available screen space.</p>
 * 
 * <p>If the application attempts to lock a preferred size dimension to a
 * value smaller than the minimum or larger than the maximum, the
 * implementation may disregard the requested value and instead use either the
 * minimum or maximum as appropriate.  If this occurs, the actual values used
 * must be visible to the application via the values returned from the
 * <A HREF="../../../javax/microedition/lcdui/Item.html#getPreferredWidth()"><CODE>getPreferredWidth</CODE></A> and
 * <A HREF="../../../javax/microedition/lcdui/Item.html#getPreferredHeight()"><CODE>getPreferredHeight</CODE></A> methods.
 * </p>
 * 
 * <h3>Commands</h3>
 * 
 * <p>A <code>Command</code> is said to be present on an <code>Item</code>
 * if the <code>Command</code> has been
 * added to this <code>Item</code> with a prior call to <A HREF="../../../javax/microedition/lcdui/Item.html#addCommand(javax.microedition.lcdui.Command)"><CODE>addCommand(javax.microedition.lcdui.Command)</CODE></A>
 * or <A HREF="../../../javax/microedition/lcdui/Item.html#setDefaultCommand(javax.microedition.lcdui.Command)"><CODE>setDefaultCommand(javax.microedition.lcdui.Command)</CODE></A> and if
 * the <code>Command</code> has not been removed with a subsequent call to
 * <A HREF="../../../javax/microedition/lcdui/Item.html#removeCommand(javax.microedition.lcdui.Command)"><CODE>removeCommand(javax.microedition.lcdui.Command)</CODE></A>.  <code>Commands</code> present on an
 * item should have a command
 * type of <code>ITEM</code>.  However, it is not an error for a
 * command whose type is
 * other than <code>ITEM</code> to be added to an item.
 * For purposes of presentation and
 * placement within its user interface, the implementation is allowed to
 * treat a command's items as if they were of type <code>ITEM</code>. </p>
 * 
 * <p><code>Items</code> may have a <em>default</em> <code>Command</code>.
 * This state is
 * controlled by the <A HREF="../../../javax/microedition/lcdui/Item.html#setDefaultCommand(javax.microedition.lcdui.Command)"><CODE>setDefaultCommand(javax.microedition.lcdui.Command)</CODE></A> method.  The default
 * <code>Command</code> is eligible to be bound to a special
 * platform-dependent user
 * gesture.  The implementation chooses which gesture is the most
 * appropriate to initiate the default command on that particular
 * <code>Item</code>.
 * For example, on a device that has a dedicated selection key, pressing
 * this key might invoke the item's default command.  Or, on a
 * stylus-based device, tapping on the <code>Item</code> might
 * invoke its default
 * command.  Even if it can be invoked through a special gesture, the
 * default command should also be invokable in the same fashion as
 * other item commands.</p>
 * 
 * <p>It is possible that on some devices there is no special gesture
 * suitable for invoking the default command on an item.  In this case
 * the default command must be accessible to the user in the same
 * fashion as other item commands.  The implementation may use the state
 * of a command being the default in deciding where to place the command
 * in its user interface.</p>
 * 
 * <p>It is possible for an <code>Item</code> not to have a default command.
 * In this
 * case, the implementation may bind its special user gesture (if any)
 * for another purpose, such as for displaying a menu of commands.  The
 * default state of an <code>Item</code> is not to have a default command.
 * An <code>Item</code>
 * may be set to have no default <code>Command</code> by removing it from
 * the <code>Item</code> or
 * by passing <code>null</code> to the <code>setDefaultCommand()</code>
 * method.</p>
 * 
 * <p>The same command may occur on more than one
 * <code>Item</code> and also on more than
 * one <code>Displayable</code>.  If this situation occurs, the user
 * must be provided with
 * distinct gestures to invoke that command on each <code>Item</code> or
 * <code>Displayable</code> on
 * which it occurs, while those <code>Items</code> or <code>Displayables</code>
 * are visible on the
 * display.  When the user invokes the command, the listener
 * (<code>CommandListener</code>
 * or <code>ItemCommandListener</code> as appropriate) of just the
 * object on which the
 * command was invoked will be called.</p>
 * 
 * <p>Adding commands to an <code>Item</code> may affect its appearance, the
 * way it is laid out, and the traversal behavior.  For example, the presence
 * of commands on an <code>Item</code> may cause row breaks to occur, or it
 * may cause additional graphical elements (such as a menu icon) to appear.
 * In particular, if a <code>StringItem</code> whose appearance mode is
 * <code>PLAIN</code> (see below) is given one or more <code>Commands</code>,
 * the implementation is allowed to treat it as if it had a different
 * appearance mode.</p>
 * 
 * <p>J2ME Polish notifies the command-listener of the current screen,
 * when an item-command has been selected and no item-command-listener
 * has been registered.
 * </p>
 * 
 * <a name="appearance"></a>
 * <h3>Appearance Modes</h3>
 * 
 * <p>The <code>StringItem</code> and <code>ImageItem</code> classes have an
 * <em>appearance mode</em> attribute that can be set in their constructors.
 * This attribute can have one of the values <A HREF="../../../javax/microedition/lcdui/Item.html#PLAIN"><CODE>PLAIN</CODE></A>,
 * <A HREF="../../../javax/microedition/lcdui/Item.html#HYPERLINK"><CODE>HYPERLINK</CODE></A>, or <A HREF="../../../javax/microedition/lcdui/Item.html#BUTTON"><CODE>BUTTON</CODE></A>.
 * An appearance mode of <code>PLAIN</code> is typically used
 * for non-interactive
 * display of textual or graphical material.  The appearance
 * mode values do not have any side effects on the interactivity of the item.
 * In order to be interactive, the item must have one or more
 * <code>Commands</code>
 * (preferably with a default command assigned), and it must have a
 * <code>CommandListener</code> that receives notification of
 * <code>Command</code> invocations.  The
 * appearance mode values also do not have any effect on the semantics of
 * <code>Command</code> invocation on the item.  For example,
 * setting the appearance mode
 * of a <code>StringItem</code> to be <code>HYPERLINK</code>
 * requests that the implementation display
 * the string contents as if they were a hyperlink in a browser.  It is the
 * application's responsibility to attach a <code>Command</code>
 * and a listener to the
 * <code>StringItem</code> that provide behaviors that the user
 * would expect from invoking
 * an operation on a hyperlink, such as loading the referent of the link or
 * adding the link to the user's set of bookmarks.</p>
 * 
 * <p>Setting the appearance mode of an <code>Item</code> to be other than
 * <code>PLAIN</code> may affect its minimum, preferred, and maximum sizes, as
 * well as the way it is laid out.  For example, a <code>StringItem</code>
 * with an appearance mode of <code>BUTTON</code> should not be wrapped across