Form类说明文档

Form是包含任意Item组合的Screen：image、只读的text field、可编辑的text field、可编辑的data field、gauge、choice group和custom item。通常来说，一个form可以包任意一个item的子类。系统负责处理布局、横向和纵向的滚动。Form的所有组件在滚动时作为一个整体。

 

Item管理

 

可以向一个Form里添加、删除和插入item。Form中的itme通过从0到size()-1的连续整数来索引，0是第一个item的索引，size()-1是最后一个。

 

任何item只能放在一个Form里。如果应用程序试图把一个已经属于另一人Form的Item放到一个新的Form里，将会抛出一个IllegalStateException的异常。应用程序必须在把item放入新的Form前把它从当前的Form里移除。

 

如果应用程序要求改变一个Form的组件时该Form是屏幕可见的，对屏幕的更新会在系统可行的时候立即执行。

 

布局

 

Form里的布局规则是按行来组织的。行同screen的宽度、相对的空白边框、滚动轴特别相关。一个特定的Form中的所有行都有相同的宽度。行宽的该行包含的item无关，虽然它们可能在某些情况下改变所有的行宽，比如添加或是删除一个滚动轴的时候。Form通过不会水平滚动。

 

Form的增长是垂直的，所以滚动也是垂直的。Form的高度取决于包含的行数和每一行的高度。每一行的高度由列于该行的item的高度来决定。行高不一定要都相同。系统可能会通过行高来对item标签提供适当的填充和垂直布局。

 

系统根据使用的语言习惯选择是从左到右还是从右到左来排列item。一个Form中的所有行的排列方向都应该相同。

 

在布局算法开始之前，Form被认为不含任何行。布局算法一个接一个的处理每一个item，从第0个item开始直到form中的最后一个item。如果排列方向为从左到右，行的开始端在Form的左边。如果排列方向为从右到左，行的开始端在Form的右边。Item从每一个的开始处排起，按选定的排列方向排列每一行，把尽可能多的item放入同一行中，除非提前换行的情况发生。新行这时候被添加，itme按上面的方法继续放入该行中。Item被放到每一行，只要有必要就添加新行直到所有item都被布局算法处理完毕。

 

布局算法里有一个current alignment的概念。它可以是LAYOUT_LEFT、LAYOUT_CENTER和LAYOUT_RIGHT三个值中的一个。布局算法开始时current alignment有值由这个Form的排列方向来决定。如果排列方向是从左到右，那么初始的alignment值必须是LAYOUT_LEFT。如果排列方向是从右到左，那么初始的alignment值必须是LAYOUT_RIGHT。Current alignment的值会在布局算法遇到一个含有LAYOUT_LEFT、LAYOUT_CENTER和LAYOUT_RIGHT中一个值的itme时改变。如果item中没有任何一个值，当前的值就不会改变。这个规则使得Form里按顺序连续的item拥有相同的alignment值。每个item的alignment值是由Form内部管理，并不会对由Item.getLayout方法返回的layout值有影响。

 

布局算法通常试图把一个item和它前一个item排列在同一行，除非遇到换行的情况。当需要换行时，当前的item会被放在下一行的开始而不是前一个item的后面，即使该行仍有空间。

 

下面情况之一发生时将在一个item前面换行：

前一个item后面一个换行符

该item拥有LAYOUT_NEWLINE_BEFORE字段

是一个以”/n”开头的字符串

是一个LAYOUT_2字段未设置的ChoiceGroup、DateField、Gauge或TextField

该item包含LAYOUT_LEFT、LAYOUT_CENTER或LAYOUT_RIGHT这些值并和Form的current alignment不同

 

下面的情况之一发生时，将在一个item之后发生换行

是一个以”/n”字符结束的字符串

它拥有一个LAYOUT_NEWLINE_AFTER字段

是一个Layout_2未设置的ChoiceGroup、DateField、Gauge或TextField

 

LAYOUT_NEWLINE_BEFORE或LAYOUT_NEWLINE_AFTER字段不会在已经有一个换行的时候产生多余的换行。比如，如果一个以”/n”开头的StringItem包含LAYOUT_NEWLINE_BEFORE字段，将只产生一个换行。一个相似的情况是，”/n”结尾并包含LAYOUT_NEWLINE_AFTER字段。同样如果前一个item包含LAYOUT_NEWLINE_AFER而接下来的item包含LAYOUT_NEWLINE_BEFORE字段。但是，无论是在单独的StringItem或是在相连的StringItem里显示连续的”/n”字符，都会根据”/n”的个数产生换行的数目。这会造成空行。空行的高度是由包含”/n”字符的StringItem中主要的字体高度在决定的。

 

系统会为换行发生提供额外的条件。比如，一个系统的布局算法会特别对待label，隐式的对每一个包含label的item产生换行。或者，再比如，一个特定的系统用户界面样式会规定DateField item总是单独显式在一行中。这种情况下，系统会在每个DateField item的前后都产生换行。

 

两个连续的item，如果没有换行或是系统定义的换行发生，并且如果有足够的空间，这两个item会被放在同一行中。

 

当把一个item放在行中是，item的宽度将和行剩余的宽度相比较。item的宽度用的是最佳宽度，除非item含有LAYOUT_SHRINK字段，这时item的最小宽度被应用。如果一个item太宽已至于不能放在一行中剩余的空间里，这时行被认为已满，一个新行将在下面被创建，并且该item将被放入新的一行里。

 

一旦一行中的内容被确定，行内剩余的空间通过扩展item和在item之间添加空格来分配。如果行中任何一个item含有LAYOUT_SHRINK字段（就是说，是可收缩的），空间会先分配给这些item。剩余空间按这些item最大宽度和最小宽度的差按比例分配给它们。在这个阶段，没有一个可收缩的item的宽度可以超过它们最佳宽度。

 

比如，考虑一个含有30个像素剩余空间的行，行中包含两个可收缩的item A和B。Item A的最佳宽度是15，最小宽度是10，B的最佳宽度是30，最小宽度是20。A的最佳宽度和最小宽度的差是5，B的最佳宽度和最小宽度的差是10。30个像素根据两个item的差值按比例分配。所以，10个像素分配给A，20个像素分配给B。

 

如果扩展所有可收缩的item之后，行中仍有剩余空间，这些剩余空间就在含有LAYOUT_EXPAND字段的item（可扩展的item）中平均分配。仍何一个可扩展的item都会使这一行的空间被占满。

 

如果行中没有可扩展的item，而且行中仍有一些剩余空间，item会按照它们的current alignment尽可紧的排列在一起。（因为改变current alignment会引起换行，所以一行中的所有item拥有相同的alignment值。）如果alignment值是LAYOUT_LEFT，item被放在一行的最左边剩余空间被放在一行的右边。如果alignment值是LAYOUT_RIGHT，item被放在一行的最右边剩余空间被放在一行的左边。如果alignment值是LAYOUT_CENTER，item会放在行的中央，剩余空间分在左右两边平分。

 

在一个特定行的item集中，这些item的高度是被子检查过的。对每一个item，高度用的是最佳高度，除非item含有LAYOUT_VSHRINK字段，这时item的最小高度被使用。行中最高的item决定该行的高度。含有LAYOUT_VSHRINK字段的item被扩展到它们的最佳高度或是行高中最小的那一个。那些仍旧小于行高的item如果含有LAYOUT_VEXPAND字段分扩展到行高。Item中的LAYOUT_VEXPAND字段不会增加行高。

 

剩余那些比行高小的item会根据LAYOUT_TOP、LAYOUT_BOTTOM和LAYOUT_VCENTER字段放在行中。如果没有指定的垂直布局字段，item必须排列在一行的底部。

 

StringItem的排列同上面的排列算法有所不同。如果一个StringItem的内容（即它的值，除了它的label）包含一个换行符（”/n”），字符串会被分开，后半部分会在下一行的开始处排列。

 

如果StringItem的一维或是两个维度的最佳大小被锁定，StringItem被包装以适合这两个大小，并且被看做是一个最佳和最小的高度和宽度都是这个高度和宽度的矩形框。这时，LAYOUT_SHRINK、LAYOUT_EXPAND和LAYOUT_VEXPAND将被忽略。

 

如果两个维度的最佳大小都没被锁定，StringItem中的文本可能会跨越多行。这时在布局算法里item的宽度和剩余的行宽比较，把尽可能多的StringItem前面的文本放入当前行。这行的内容根据current alignment的值排列。StringItem中剩余的文本被放在接下来的行中。每一个被填满的行排照current alighment排列。最后一行可能会留有剩余空间。如果StringItem后没有换行符，后面的item被放入该行中，并且该行的内容按照current alignment的值排列。这个规则对作为文本设置为flush-left、flush-right或centered段落的StringItem的显示有影响，这取决于current alignment的值是LAYOUT_LEFT、LAYOUT_RIGHTG还是LAYOUT_CENTER。方法Item.getPreferredWidth和Item.getPreferredHeight返回的StringItem的最佳高度和宽度定义了包装文本的矩形边框。

 

ImageItems同样和上面的排列方法有所不风吹草动。前面关于水平排列的值和LAYOUT_LEFT、LAYOUT_RIGHT和LAYOUT_CENTER字段，只有在ImageItem拥有LAYOUT_2字段时才有效。如果一个ImageItem没有LAYOUT_2字段，LAYOUT_LEFT、LAYOUT_RIGHT和LAYOUT_CENTER的行为由系统定义。

 

一个Form的布局如果必要会重新排列。这种情况可能会在一个item由于内容的变化而引起的大小改变或是因为由应用程序请求改变一个item的最佳大小是发生。还可能在一个item的layout字段被应用程序改变。应用程序没有必要执行任何特定的行为来引起Form的布局更新。

 

挽行和包装

 

在所有文本被包装的情况下，换行必须在每一个换行符出现的地方发生（”/n”=Unicode ‘U+000A’）。如果空间不允许完全显示文本，它将在换行符的地方被裁减。如果没有合适的换行符，建议在词间之前进行系统换行。如果没有词间，建议在字符间进行系统换行。

 

包含换行符的Label可能会在换行处被裁减，剩余的部分可能不被显示。

 

用户界面

 

当一个Form显示在屏幕上时，用户可能一确定的和它或是它的item交互（比如，traversing和可能的scrolling）。这些traversing和scrolling操作不会改变应用程序的可见事件发和。系统在用户修改一个Form中的交互组件的状态时通知应用程序。通知通过调用利用setItemStateListener()方法设置给Form的监听器的itemStateChanged()方法。

 

同其它的Displayable对象相同，Form可以声明command并通过setCommandListener()方法注册一个command listener。CommandListener对象和ItemStateListener对象不同，并且分别声明和调用。

 

给应用程序开发人员的提示

 

虽然这个类允许构建任意组件的组合，应用程序开发者应该记住最小屏幕的概念。Form应该包含最少的密切相关的UI组件

 

如果item的数量屏幕容纳不下，系统会让它可滚动或是在某些组件被编辑时转到个一单独的屏幕。

 

javax.microedition.lcdui
Class Form

java.lang.Object
javax.microedition.lcdui.Displayable
javax.microedition.lcdui.Screen
javax.microedition.lcdui.Form

---

public class Form

extends Screen

A Form is a Screen that contains an arbitrary mixture of items: images, read-only text fields, editable text fields, editable date fields, gauges, choice groups, and custom items. In general, any subclass of the ItemForm scrolls together. class may be contained within a form. The implementation handles layout, traversal, and scrolling. The entire contents of the

Item Management

The items contained within a Form may be edited using append, delete, insert, and set methods. Items within a Form are referred to by their indexes, which are consecutive integers in the range from zero to size()-1, with zero referring to the first item and size()-1 to the last item.

An item may be placed within at most one Form. If the application attempts to place an item into a Form, and the item is already owned by this or another Form, an IllegalStateException is thrown. The application must remove the item from its currently containing Form before inserting it into the new Form.

If the Form is visible on the display when changes to its contents are requested by the application, updates to the display take place as soon as it is feasible for the implementation to do so. Applications need not take any special action to refresh a Form's display after its contents have been modified.

Layout

Layout policy in Form is organized around rows. Rows are typically related to the width of the screen, respective of margins, scroll bars, and such. All rows in a particular Form will have the same width. Rows do not vary in width based on the Items contained within the Form, although they may all change width in certain circumstances, such as when a scroll bar needs to be added or removed. Forms generally do not scroll horizontally.

Forms grow vertically and scroll vertically as necessary. The height of a Form varies depending upon the number of rows and the height of each row. The height of each row is determined by the items that are positioned on that row. Rows need not all have the same height. Implementations may also vary row heights to provide proper padding or vertical alignment of Item labels.

An implementation may choose to lay out Items in a left-to-right or right-to-left direction depending upon the language conventions in use. The same choice of layout direction must apply to all rows within a particular Form.

Prior to the start of the layout algorithm, the Form is considered to have one empty row at the top. The layout algorithm considers each Item in turn, starting at Item zero and proceeding in order through each Item until the last Item in the Form has been processed. If the layout direction (as described above) is left-to-right, the beginning of the row is the left edge of the Form. If the layout direction is right-to-left, the beginning of the row is the right edge of the Form. Items are laid out at the beginning of each row, proceeding across each row in the chosen layout direction, packing as many Items onto each row as will fit, unless a condition occurs that causes the packing of a row to be terminated early. A new row is then added, and Items are packed onto it as described above. Items are packed onto rows, and new rows are added below existing rows as necessary until all Items have been processed by the layout algorithm.

The layout algorithm has a concept of a current alignment. It can have the value LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT. The value of the current alignment at the start of the layout algorithm depends upon the layout direction in effect for this Form. If the layout direction is left-to-right, the initial alignment value must be LAYOUT_LEFT. If the layout direction is right-to-left, the initial alignment value must be LAYOUT_RIGHT. The current alignment changes when the layout algorithm encounters an Item that has one of the layout directives LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT. If none of these directives is present on an Item, the current layout directive does not change. This rule has the effect of grouping the contents of the Form into sequences of consecutive Items sharing an alignment value. The alignment value of each Item is maintained internally to the Form and does not affect the Items' layout value as reported by the Item.getLayout method.

The layout algorithm generally attempts to place an item on the same row as the previous item, unless certain conditions occur that cause a "row break." When there is a row break, the current item will be placed at the beginning of a new row instead of being placed after the previous item, even if there is room.

A row break occurs before an item if any of the following conditions occurs:

• the previous item has a row break after it;
• it has the LAYOUT_NEWLINE_BEFORE directive; or
• it is a StringItem whose contents starts with "/n";
• it is a ChoiceGroup, DateField, Gauge, or a TextField, and the LAYOUT_2 directive is not set; or
• this Item has a LAYOUT_LEFT, LAYOUT_CENTER, or LAYOUT_RIGHT directive that differs from the Form's current alignment.

A row break occurs after an item if any of the following conditions occurs:

• it is a StringItem whose contents ends with "/n"; or
• it has the LAYOUT_NEWLINE_AFTER directive; or
• it is a ChoiceGroup, DateField, Gauge, or a TextField, and the LAYOUT_2 directive is not set.

The presence of the LAYOUT_NEWLINE_BEFORE or LAYOUT_NEWLINE_AFTER directive does not cause an additional row break if there is one already present. For example, if a LAYOUT_NEWLINE_BEFORE directive appears on a StringItem whose contents starts with "/n", there is only a single row break. A similar rule applies with a trailing "/n" and LAYOUT_NEWLINE_AFTER. Also, there is only a single row break if an item has the LAYOUT_NEWLINE_AFTER directive and the next item has the LAYOUT_NEWLINE_BEFORE directive. However, the presence of consecutive "/n" characters, either within a single StringItem or in adjacent StringItems, will cause as many row breaks as there are "/n" characters. This will cause empty rows to be present. The height of an empty row is determined by the prevailing font height of the StringItem within which the "/n" that ends the row occurs.

Implementations may provide additional conditions under which a row break occurs. For example, an implementation's layout policy may lay out labels specially, implicitly causing a break before every Item 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 DateField item.

Given two items with adjacent Form 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.

When packing Items 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 Item's preferred width, unless the Item has the LAYOUT_SHRINK directive, in which case the Item's minimum width is used. If the Item 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 Item is laid out on this new row.

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 LAYOUT_SHRINK 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 Item's preferred size and its minimum size. At this stage, no shrinkable item is expanded beyond its preferred width.

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

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 LAYOUT_EXPAND directive (the stretchable Items). The presence of any stretchable items on a row will cause the Items on this row to occupy the full width of the row.

If there are no stretchable items on this row, and there is still space available on this row, the Items are packed as tightly as possible and are placed on the row according to the alignment value shared by the Items on this row. (Since changing the current alignment causes a row break, all Items on the same row must share the same alignment value.) If the alignment value is LAYOUT_LEFT, the Items 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 LAYOUT_RIGHT, the Items 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 LAYOUT_CENTER, the Items 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.

Given the set of items on a particular row, the heights of these Items are inspected. For each Item, the height that is used is the preferred height, unless the Item has the LAYOUT_VSHRINK directive, in which case the Item's minimum height is used. The height of the tallest Item determines the height of the row. Items that have the LAYOUT_VSHRINK directive are expanded to their preferred height or to the height of the row, whichever is smaller. Items that are still shorter than the row height and that have the LAYOUT_VEXPAND directive will expand to the height of the row. The LAYOUT_VEXPAND directive on an item will never increase the height of a row.

Remaining Items shorter than the row height will be positioned vertically within the row using the LAYOUT_TOP, LAYOUT_BOTTOM, and LAYOUT_VCENTER directives. If no vertical layout directive is specified, the item must be aligned along the bottom of the row.

StringItems are treated specially in the above algorithm. If the contents of a StringItem (its string value, exclusive of its label) contain a newline character ("/n"), the string should be split at that point and the remainder laid out starting on the next row.

If one or both dimensions of the preferred size of a StringItem have been locked, the StringItem 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 LAYOUT_SHRINK, LAYOUT_EXPAND, and LAYOUT_VEXPAND directives are ignored.

If both dimensions of the preferred size of a StringItem are unlocked, the text from the StringItem may be wrapped across multiple rows. At the point in the layout algorithm where the width of the Item is compared to the remaining space on the row, as much text is taken from the beginning of the StringItem 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 StringItem 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 StringItem, subsequent Items 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 StringItem as a paragraph of text set flush-left, flush-right, or centered, depending upon whether the current alignment value is LAYOUT_LEFT, LAYOUT_RIGHT, or LAYOUT_CENTER, respectively. The preferred width and height of a StringItem wrapped across multiple rows, as reported by the Item.getPreferredWidth and Item.getPreferredHeight methods, describe the width and height of the bounding rectangle of the wrapped text.

ImageItems are also treated specially by the above algorithm. The foregoing rules concerning the horizontal alignment value and the LAYOUT_LEFT, LAYOUT_RIGHT, and LAYOUT_CENTER directives, apply to ImageItems only when the LAYOUT_2 directive is also present on that item. If the LAYOUT_2 directive is not present on an ImageItem, the behavior of the LAYOUT_LEFT, LAYOUT_RIGHT, and LAYOUT_CENTER directives is implementation-specific.

A Form's layout is recomputed automatically as necessary. This may occur because of a change in an Item's 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 Item's layout directives are changed by the application. The application does not need to perform any specific action to cause the Form's layout to be updated.

Line Breaks and Wrapping

For all cases where text is wrapped, line breaks must occur at each newline character ('/n' = Unicode 'U+000A'). 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.

Labels that contain line breaks may be truncated at the line break and cause the rest of the label not to be shown.

User Interaction

When a Form is present on the display the user can interact with it and its Items indefinitely (for instance, traversing from Item to Item 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 Item contained within the Form. This notification is accomplished by calling the itemStateChanged()Form with the setItemStateListener() method. method of the listener declared to the

As with other Displayable objects, a Form can declare commands and declare a command listener with the setCommandListener() method. CommandListener objects are distinct from ItemStateListener objects, and they are declared and invoked separately.

Notes for Application Developers

• Although this class allows creation of arbitrary combination of components the application developers should keep the small screen size in mind. Form is designed to contain a small number of closely related UI elements.
• 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.

Since:

MIDP 1.0

See Also:

Item                                                  翻译:lori.wang