form.java

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

 * <code>LAYOUT_VSHRINK</code> directive, in which case the
 * <code>Item's</code> minimum height is used.
 * The height of the tallest
 * <code>Item</code> determines the
 * height of the row.  <code>Items</code> that have the
 * <code>LAYOUT_VSHRINK</code> directive are expanded to their preferred
 * height or to the height of the row, whichever is smaller.
 * <code>Items</code> that are still shorter than the
 * row height and that
 * have the <code>LAYOUT_VEXPAND</code> directive will expand to
 * the height of the row.
 * The <code>LAYOUT_VEXPAND</code> directive on an item will never
 * increase the height
 * of a row.</p>
 * 
 * <p>Remaining <code>Items</code> shorter than the row height
 * will be positioned
 * vertically within the row using the <code>LAYOUT_TOP</code>,
 * <code>LAYOUT_BOTTOM</code>, and
 * <code>LAYOUT_VCENTER</code> directives.  If no vertical layout directive is
 * specified, the item must be aligned along the bottom of the row.</p>
 * 
 * <p><code>StringItems</code> are treated specially in the above
 * algorithm.  If the
 * contents of a <code>StringItem</code> (its string value,
 * exclusive of its label) contain
 * a newline character (&quot;\n&quot;), the string should be split at
 * that point and
 * the remainder laid out starting on the next row.</p>
 * 
 * <p>If one or both dimensions of the preferred size of
 * a <code>StringItem</code> have been locked, the <code>StringItem</code>
 * is wrapped to fit that width and height and is treated as a
 * rectangle whose minimum and preferred width and height are the width and
 * height of this rectangle. In this case, the
 * <code>LAYOUT_SHRINK</code>, <code>LAYOUT_EXPAND</code>,
 * and <code>LAYOUT_VEXPAND</code> directives are ignored.</p>
 * 
 * <p>If both dimensions of the preferred size of a <code>StringItem</code>
 * are unlocked, the text from the <code>StringItem</code> may be wrapped
 * across multiple rows.  At the point in the layout algorithm where the width
 * of the <code>Item</code> is compared to the remaining space on the row, as
 * much text is taken from the beginning of the <code>StringItem</code> as
 * will fit onto the current row.  The contents of this row are then
 * positioned according to the current alignment value.  The remainder of the
 * text in the <code>StringItem</code> is line-wrapped to the full width of as
 * many new rows as are necessary to accommodate the text.  Each full row is
 * positioned according to the current alignment value.  The last line of the
 * text might leave space available on its row.  If there is no row break
 * following this <code>StringItem</code>, subsequent <code>Items</code> are
 * packed into the remaining space and the contents of the row are positioned
 * according to the current alignment value.  This rule has the effect of
 * displaying the contents of a <code>StringItem</code> as a paragraph of text
 * set flush-left, flush-right, or centered, depending upon whether the
 * current alignment value is <code>LAYOUT_LEFT</code>,
 * <code>LAYOUT_RIGHT</code>, or <code>LAYOUT_CENTER</code>, respectively.
 * The preferred width and height of a <code>StringItem</code> wrapped across
 * multiple rows, as reported by the
 * <A HREF="../../../javax/microedition/lcdui/Item.html#getPreferredWidth()"><CODE>Item.getPreferredWidth</CODE></A> and
 * <A HREF="../../../javax/microedition/lcdui/Item.html#getPreferredHeight()"><CODE>Item.getPreferredHeight</CODE></A>
 * methods, describe the width and height of the bounding rectangle of the
 * wrapped text.</p>
 * 
 * <p><code>ImageItems</code> are also treated specially by the above
 * algorithm.  The foregoing rules concerning the horizontal alignment value
 * and the <code>LAYOUT_LEFT</code>, <code>LAYOUT_RIGHT</code>, and
 * <code>LAYOUT_CENTER</code> directives, apply to <code>ImageItems</code>
 * only when the <code>LAYOUT_2</code> directive is also present on that item.
 * If the <code>LAYOUT_2</code> directive is not present on an
 * <code>ImageItem</code>, the behavior of the <code>LAYOUT_LEFT</code>,
 * <code>LAYOUT_RIGHT</code>, and <code>LAYOUT_CENTER</code> directives is
 * implementation-specific.</p>
 * 
 * <p>A <code>Form's</code> layout is recomputed automatically as
 * necessary.  This may
 * occur because of a change in an <code>Item's</code> size caused
 * by a change in its
 * contents or because of a request by the application to change the Item's
 * preferred size.  It may also occur if an <code>Item's</code>
 * layout directives are
 * changed by the application.  The application does not need to perform
 * any specific action to cause the <code>Form's</code> layout to
 * be updated.</p>
 * 
 * <h2><a NAME="linebreak">Line Breaks and Wrapping</a></h2>
 * 
 * <p>For all cases where text is wrapped,
 * line breaks must occur at each newline character
 * (<code>'\n'</code> = Unicode <code>'U+000A'</code>).
 * If space does not permit
 * the full text to be displayed it is truncated at line breaks.
 * If there are no suitable line breaks, it is recommended that
 * implementations break text at word boundaries.
 * If there are no word boundaries, it is recommended that
 * implementations break text at character boundaries. </p>
 * 
 * <p>Labels that contain line breaks may be truncated at the line
 * break and cause the rest of the label not to be shown.</p>
 * 
 * <h2>User Interaction</h2>
 * 
 * <p> When a <code>Form</code> is present on the display the user
 * can interact
 * with it and its <code>Items</code> indefinitely (for instance,
 * traversing from <code>Item</code>
 * to <code>Item</code>
 * and possibly
 * scrolling). These traversing and scrolling operations do not cause
 * application-visible events. The system notifies
 * the application when the user modifies the state of an interactive
 * <code>Item</code>
 * contained within the <code>Form</code>.  This notification is
 * accomplished by calling the
 * <A HREF="../../../javax/microedition/lcdui/ItemStateListener.html#itemStateChanged(javax.microedition.lcdui.Item)"><CODE>itemStateChanged()</CODE></A>
 * method of the listener declared to the <code>Form</code> with the
 * <A HREF="../../../javax/microedition/lcdui/Form.html#setItemStateListener(javax.microedition.lcdui.ItemStateListener)"><CODE>setItemStateListener()</CODE></A> method. </p>
 * 
 * <p> As with other <code>Displayable</code> objects, a
 * <code>Form</code> can declare
 * <A HREF="../../../javax/microedition/lcdui/Command.html"><CODE>commands</CODE></A> and declare a command listener with the
 * <A HREF="../../../javax/microedition/lcdui/Displayable.html#setCommandListener(javax.microedition.lcdui.CommandListener)"><CODE>setCommandListener()</CODE></A> method.
 * <A HREF="../../../javax/microedition/lcdui/CommandListener.html"><CODE>CommandListener</CODE></A>
 * objects are distinct from
 * <A HREF="../../../javax/microedition/lcdui/ItemStateListener.html"><CODE>ItemStateListener</CODE></A> objects, and they are declared
 * and invoked separately. </p>
 * 
 * <h2>Notes for Application Developers</h2>
 * 
 * <UL>
 * <LI>Although this class allows creation of arbitrary combination of
 * components
 * the application developers should keep the small screen size in mind.
 * <code>Form</code> is designed to contain a <em>small number of
 * closely related</em>
 * UI elements. </LI>
 * 
 * <LI>If the number of items does not fit on the screen, the
 * implementation may choose to make it scrollable or to fold some components
 * so that a separate screen appears when the element is edited.</LI>
 * </UL>
 * 
 * @author Robert Virkus, [e-mail] 
 * @since MIDP 1.0
 */
public class Form extends Screen
{
	protected ItemStateListener itemStateListener;
	private ArrayList stateNotifyQueue;

	/**
	 * Creates a new, empty <code>Form</code>.
	 * 
	 * @param title the Form's title, or null for no title
	 */
	public Form( String title)
	{
		this( title, null, null );
	}

	/**
	 * Creates a new, empty <code>Form</code>.
	 * 
	 * @param title the Form's title, or null for no title
	 * @param style the style of this form
	 */
	public Form( String title, Style style )
	{
		this( title, null, style );
	}

	/**
	 * Creates a new <code>Form</code> with the specified
	 * contents. This is identical to
	 * creating an empty <code>Form</code> and then using a set of
	 * <code>append</code>
	 * methods.  The
	 * items array may be <code>null</code>, in which case the
	 * <code>Form</code> is created empty.  If
	 * the items array is non-null, each element must be a valid
	 * <code>Item</code> not
	 * already contained within another <code>Form</code>.
	 * 
	 * @param title - the Form's title string
	 * @param items - the array of items to be placed in the Form, or null if there are no items
	 * @throws IllegalStateException - if one of the items is already owned by another container
	 * @throws NullPointerException - if an element of the items array is null
	 */
	public Form( String title, Item[] items)
	{
		this( title, items, null );
	}

	/**
	 * Creates a new <code>Form</code> with the specified
	 * contents. This is identical to
	 * creating an empty <code>Form</code> and then using a set of
	 * <code>append</code>
	 * methods.  The
	 * items array may be <code>null</code>, in which case the
	 * <code>Form</code> is created empty.  If
	 * the items array is non-null, each element must be a valid
	 * <code>Item</code> not
	 * already contained within another <code>Form</code>.
	 * 
	 * @param title the Form's title string
	 * @param items the array of items to be placed in the Form, or null if there are no items
	 * @param style the style of this form
	 * @throws IllegalStateException if one of the items is already owned by another container
	 * @throws NullPointerException if an element of the items array is null
	 */
	public Form( String title, Item[] items, Style style )
	{
		super( title, style, true );
		if (items != null) {
			for (int i = 0; i < items.length; i++) {
				Item item = items[i];
				this.container.add( item );
			}
		}
		//TODO rob set default layout policy according to the language.
		// (western: left to right, eastern: right to left)
	}

	//#if polish.LibraryBuild
	//# /**
	 //# * Adds an <code>Item</code> into the <code>Form</code>.  
	 //# * The newly
	 //# * added <code>Item</code> becomes the last <code>Item</code> in the
	 //# * <code>Form</code>, and the size of the <code>Form</code> grows
	 //# * by one.
	 //# * This method is only provided for being able to add native items as well as custom items to a J2ME Polish form
	 //# * within an IDE.
	 //# * 
	 //# * @param item the Item to be added.
	 //# * @return the assigned index of the Item
	 //# * @throws IllegalStateException if the item is already owned by a container
	 //# * @throws NullPointerException if item is null
	 //# */
	//# public int append( javax.microedition.lcdui.Item item)
	//# {
		//# return -1;
	//# }
	//#endif

	/**
	 * Adds an <code>Item</code> into the <code>Form</code>.  The newly
	 * added <code>Item</code> becomes the last <code>Item</code> in the
	 * <code>Form</code>, and the size of the <code>Form</code> grows
	 * by one.
	 * 
	 * @param item - the Item to be added.
	 * @return the assigned index of the Item
	 * @throws IllegalStateException if the item is already owned by a container
	 * @throws NullPointerException if item is null
	 */
	public int append( Item item)
	{
		return append( item, null );
	}
	
	/**
	 * Adds an <code>Item</code> into the <code>Form</code>.  The newly
	 * added <code>Item</code> becomes the last <code>Item</code> in the
	 * <code>Form</code>, and the size of the <code>Form</code> grows
	 * by one.
	 * 
	 * @param item the Item to be added.
	 * @param itemStyle the style for that item
	 * @return the assigned index of the Item
	 * @throws IllegalStateException if the item is already owned by a container
	 * @throws NullPointerException if item is null
	 */
	public int append( Item item, Style itemStyle )
	{
		item.screen = this;
		this.container.add( item );
		if (itemStyle != null) {
			item.setStyle( itemStyle );
		}