form.html

J2ME MIDP2.0 final specification

 that is used is the preferred height, unless the <code>Item</code> has the
 <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> = <code>'&#92;u000a'</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>

 <p>
 </p>
<P>
<DL>
<DT><B>Since: </B><DD>MIDP 1.0</DD>
<DT><B>See Also: </B><DD><A HREF="../../../javax/microedition/lcdui/Item.html"><CODE>Item</CODE></A></DL>
<HR>

<P>
<!-- ======== INNER CLASS SUMMARY ======== -->


<!-- =========== FIELD SUMMARY =========== -->


<!-- ======== CONSTRUCTOR SUMMARY ======== -->

<A NAME="constructor_summary"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Constructor Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#Form(java.lang.String)">Form</A></B>(String&nbsp;title)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates a new, empty <code>Form</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#Form(java.lang.String, javax.microedition.lcdui.Item[])">Form</A></B>(String&nbsp;title,
     <A HREF="../../../javax/microedition/lcdui/Item.html">Item</A>[]&nbsp;items)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates a new <code>Form</code> with the specified
 contents.</TD>
</TR>
</TABLE>
&nbsp;
<!-- ========== METHOD SUMMARY =========== -->

<A NAME="method_summary"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Method Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#append(javax.microedition.lcdui.Image)">append</A></B>(<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A>&nbsp;img)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Adds an item consisting of one <code>Image</code> to the
 <code>Form</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#append(javax.microedition.lcdui.Item)">append</A></B>(<A HREF="../../../javax/microedition/lcdui/Item.html">Item</A>&nbsp;item)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Adds an <code>Item</code> into the <code>Form</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#append(java.lang.String)">append</A></B>(String&nbsp;str)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Adds an item consisting of one <code>String</code> to the
 <code>Form</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#delete(int)">delete</A></B>(int&nbsp;itemNum)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Deletes the <code>Item</code> referenced by
 <code>itemNum</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#deleteAll()">deleteAll</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Deletes all the items from this <code>Form</code>, leaving
 it with zero items.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;<A HREF="../../../javax/microedition/lcdui/Item.html">Item</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#get(int)">get</A></B>(int&nbsp;itemNum)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gets the item at given position.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#getHeight()">getHeight</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns the height in pixels of the displayable area available
 for items.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#getWidth()">getWidth</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns the width in pixels of the displayable area available for items.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#insert(int, javax.microedition.lcdui.Item)">insert</A></B>(int&nbsp;itemNum,
       <A HREF="../../../javax/microedition/lcdui/Item.html">Item</A>&nbsp;item)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Inserts an item into the <code>Form</code> just prior to
 the item specified.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#set(int, javax.microedition.lcdui.Item)">set</A></B>(int&nbsp;itemNum,
    <A HREF="../../../javax/microedition/lcdui/Item.html">Item</A>&nbsp;item)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Sets the item referenced by <code>itemNum</code> to the
 specified item,
 replacing the previous item.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#setItemStateListener(javax.microedition.lcdui.ItemStateListener)">setItemStateListener</A></B>(<A HREF="../../../javax/microedition/lcdui/ItemStateListener.html">ItemStateListener</A>&nbsp;iListener)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Sets the <code>ItemStateListener</code> for the
 <code>Form</code>, replacing any previous
 <code>ItemStateListener</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Form.html#size()">size</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gets the number of items in the <code>Form</code>.</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_javax.microedition.lcdui.Displayable"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class javax.microedition.lcdui.<A HREF="../../../javax/microedition/lcdui/Displayable.html">Displayable</A></B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE><A HREF="../../../javax/microedition/lcdui/Displayable.html#addCommand(javax.microedition.lcdui.Command)">addCommand</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#getTicker()">getTicker</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#getTitle()">getTitle</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#isShown()">isShown</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#removeCommand(javax.microedition.lcdui.Command)">removeCommand</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#setCommandListener(javax.microedition.lcdui.CommandListener)">setCommandListener</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#setTicker(javax.microedition.lcdui.Ticker)">setTicker</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#setTitle(java.lang.String)">setTitle</A>, <A HREF="../../../javax/microedition/lcdui/Displayable.html#sizeChanged(int, int)">sizeChanged</A></CODE></TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class java.lang.Object</B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE>equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>

<!-- ============ FIELD DETAIL =========== -->