form.html

是MIDP 的API 查詢文件, 大家可以看一下裡面的index.html, 再用Package 或 Class 名字來查.

 break occurs.  For example, an implementation's layout policy may lay out
 labels specially, implicitly causing a break before every
 <code>Item</code> that has a
 label.  Or, as another example, a particular implementation's user
 interface style may dictate that a DateField item always appears on a row
 by itself.  In this case, this implementation may cause row breaks to occur
 both before and after every <code>DateField</code> item.</p>

 <p>Given two items with adjacent <code>Form</code> indexes, if
 none of the specified
 or implementation-specific conditions for a row break between them
 occurs, and if space permits, these items should be placed on the same
 row.</p>

 <p>When packing <code>Items</code> onto a row, the width of the
 item is compared with
 the remaining space on the row. For this purpose, the width used is the
 <code>Item's</code> preferred width, unless the
 <code>Item</code> has the <code>LAYOUT_SHRINK</code>
 directive,
 in which case the <code>Item's</code> minimum width is used. If
 the <code>Item</code> is too wide
 to fit in the space remaining on the row, the row is considered to be
 full, a new row is added beneath this one, and the
 <code>Item</code> is laid out on
 this new row.</p>

 <p>Once the contents of a row have been determined, the space available on
 the row is distributed by expanding items and by adding space between
 items. If any items on this row have the
 <code>LAYOUT_SHRINK</code> directive (that is,
 they are shrinkable), space is first distributed to these items. Space is
 distributed to each of these items proportionally to the difference between
 the each <code>Item's</code> preferred size and its minimum
 size.  At this stage, no
 shrinkable item is expanded beyond its preferred width.</p>

 <p>For example, consider a row that has <code>30</code> pixels
 of space available and
 that has two shrinkable items <code>A</code> and
 <code>B</code>. Item <code>A's</code> preferred size is
 <code>15</code> and
 its minimum size is <code>10</code>. Item <code>B's</code>
 preferred size is <code>30</code> and its minimum
 size is <code>20</code>. The difference between
 <code>A's</code> preferred and minimum size is
 <code>5</code>,
 and <code>B's</code> difference is <code>10</code>. The
 <code>30</code> pixels are distributed to these items
 proportionally to these differences. Therefore, <code>10</code>
 pixels are
 distributed to item <code>A</code> and <code>20</code>
 pixels to item <code>B</code>.</p>

 <p>If after expanding all the shrinkable items to their preferred widths,
 there is still space left on the row, this remaining space is distributed
 equally among the Items that have the
 <code>LAYOUT_EXPAND</code> directive (the
 stretchable <code>Items</code>).  The presence of any
 stretchable items on a row will
 cause the <code>Items</code> on this row to occupy the full
 width of the row.</p>

 <p>If there are no stretchable items on this row, and there is still space
 available on this row, the <code>Items</code> are packed as tightly as
 possible and are placed on the row according to the alignment value shared
 by the <code>Items</code> on this row.  (Since changing the current
 alignment causes a row break, all <code>Items</code> on the same row must
 share the same alignment value.)  If the alignment value is
 <code>LAYOUT_LEFT</code>, the <code>Items</code> are positioned at the left
 end of the row and the remaining space is placed at the right end of the
 row.  If the alignment value is <code>LAYOUT_RIGHT</code>, the
 <code>Items</code> are positioned at the right end of the row and the
 remaining space is placed at the left end of the row.  If the alignment
 value is <code>LAYOUT_CENTER</code>, the <code>Items</code> are positioned
 in the middle of the row such that the remaining space on the row is
 divided evenly between the left and right ends of the row.</p>

 <p>Given the set of items on a particular row, the heights of these
 <code>Items</code> are inspected.  For each <code>Item</code>, the height
 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> = 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>

 <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 ======== -->