Choice接口说明文档

Choice接口定义了为用户界面组件实现对预定义的选项进行选择的应用程序编程接口。这些用户界面组件包括List和ChoiceGroup。Choice中的选项是通过字符串和图像来表示的。

Choice中的每一项都是由一个段文字，一个图像和一个字体属性组成的，这三部分被认为是单元。字体属性对文字起作用并且可以由应用程序来控制。应用程序可以把图像设置为null如果一个选择项没有图像的话。系统必须在文字前显示图像。如果一个Choice还包含一个显示在文字前面的选择指示符（比如单选框或复选框），选项必须放在选择指示符和文字段的中间。

当插入或是增加一个新的选项时，系统为字体提供一个默认属性。当应用程序调用过setFont(I,null)函数时，默认字体和设置的字体相同。所有的ChoiceGroup拥有相同的默认字体，所有的List拥有相同的字体。但是，Choice对象使用的默认字体可能会和Font.getDefaultFont()函数返回的字体不同。

选项的图像可以是可修改的或是不可修改的。如果图像是可修改的，结果是好象我们使用的是图像在Choice构建时或是一个Choice选项被添加、插入或设置时的一个快照。无论何时Choice的内容被显示都使用这幅快照。即使应用程序后来重画了图像，快照也不会改变，直到上述几种方法中的一种发生。当Choice在屏幕上可见的时候快照不会被更新。（这是因为应用程序没有精确控制Displayable和Item在屏幕上显示或是消失的权限。）

下面这行代码显示如何更新一个Choice ch中k选项的图像：

ch.set(k, ch.getString(k), ch.getImage(k));

如果一个应用程序在选项中显示图片，当图片超过设备能够显示的大小，系统会将会把它截去。一个Choice对象里的图片应该保持一样的大小，因为系统为每一个选择项分配相同的空间。应用程序可以通过Display.getBestImageWidth(int)和Display.getBestImageHeight(int)来查询系统建议的图片大小。

如果一个选项很长并且包含回车符，系统可能会只显示其中的一部分。在这种情况下，系统会为用户提供浏览选项全部内容的方法。如果是通过把一个选项为成多行显示，第二行和接下来的几行应该显示的通知用户它们不是新的选项而是同一选项的一部分。

应用程序可以选择一种系统用来显示较长选项包括那些包含回车符的选项的策略。只有在系统策略允许下第一个回车符后面的字符才会可见。SetFitPolicy(int)和getFitPolicy()方法控制这种选择。有效参数是TEXT_WRAP_DEFAULT,TEXT_WRAP_ON和TEXT_WRAP_OFF。除非实现Choice接口的类有特殊的定义，选项的fit policy是TEXT_WRAP_DEFAULT。

Choice对象被创建后，选项可以插入、添加和删除，而且每个选项的文字和图片都可以获得和设置。Choice对象中的选项通过索引值来引用，索引值是从0到size()-1的连续整数，第一个选项的索引值是0,最后一个的值是size()-1。

有四种类型的Choice：implicit-choice（只在List中有效），exclusive-choice,multiple-choice和pop-up（只在ChoiceGroup中有效）。

Exclusive-choice显示一系列的选项并同用户交互。即，当用户选择一个选项后，选项用一种不同的显示方式显示代表被选中。如果Choice有一些选项，任何时候只能有一个选项被选择。如果在任何时候造成exclusive-choice中有选项代没有一个被选中，系统会选择一个选项并选中它。这种情况可能发生在当把一个选项添加到一个空的Choice里，当删除一个被选中的选项，或是当Choice通过构造器构造选项的时候。。在这些情况里，对那一项选择由系统来处理。对那些选择选项很有意义的应用程序来说应该显示的设置选择。在exclusive Choice里没有让用户取消选择的方法。

Popup choice同exclusive choice很类似。Popup choice的选择行为同exclusive choice的相同。但是，popup choice的表示以及交互方式和exclusive choice不同。在exclusive choice里，所有选项都必须按顺序排列。在popup choice里，被选中的选项总是被显示出来，而其它选项可以保持隐藏直到用户持行一个特定行为来显示它们。比如，一个exclusive choice可以通过一系列的单选按钮其中总有一个被选择的方式实现。一个popup choice可以通过一个弹出式菜单来实现，被选中的选项显示在一个菜单按钮上。

Implicit choice是一种exclusive choice，这里当一个命令被初使化给它时，获得焦点或是高亮显示的选项隐式被选中。和exclusive choice一样，如果Choice中有选项，总有一个被选中。

一个multiple-choice表示一系列选项并且允许用户选择任意组合的任意个选项。和exclusive-choice一样，multiple-choice通过object-operation 模式和用户进行交互。Multiple-choice的外观看起来和exclusive-choice有些差别，它显示选中每一个被选中的选项并且通知用户多个选项可以被选中。

Selected state是选项的一个属性。如果有其它选项被添加或是删除，造成某选项更换位置，这个属性也不会改变。举个例子，假如索引值为n的选项被选中，这时一个新的选项被添加到索引值为0的位置。这时被选中的选项的索引值为n+1。同样的规则适用于删除操作。假设n大于0，删除选项0会造成选项n-1是被选中的。设置一个选项的内容不会改变选项的selected state。当一个新的选项添加或是插入的时候，它种是不被选中的（除了向一个空的Exclusive,Popup或是Implicit Choice中添加选项）

应用程序可以通过setSelectedFlags和setSelectedIndex方法来控制一个Choice对象的selected state。应用程序可以通过getSelectedFlags和getSelectedIndex方法来获得该状态。这些函数返回的selected state通常和应用程序设置的状态相同，以下的几种情况除外。添加或是删除选项可能会改变选择。当一个Choice显示在屏幕上时，系统的用户界面规则和直接的用户交互同样会影响选择。比如，当用户移动高亮时系统可能更新选择项到现在高亮显示的选项，系统也可能只当用户触发一个comm
4000
and时才把选择项更改到当前高亮的位置。再比如，系统可能会在每次implicit list成为当前显示部件时移动高亮（就是选择）到第一个选项。当屏幕上显示一个Choice对象的时候，应用程序应该只在CommandListener或是ItemStateListener回调函数里查询选择状态。在其它时间对状态进行查询可能会造成返回值和应用程序设置的值不符（因为用户或是系统的UI规则可能会改变它）而且它也可能不会反映用户的意图（因为用户可能还没有做出选择）。

注意:2.0版在Choice接口里添加了新的方法。向接口里添加方法通常是不兼容的做法。但是，Choice不作为数据域、方法参数或是方法返回值的类型，所以一个应用程序没有必要构造一个实现Choice按口的类。将来的版本还回对Choice接口进行修改。为了保持同将来的兼容性，应用程序应该避免构造实现Choice接口的类。

javax.microedition.lcduiInterface Choice

All Known Implementing Classes: ChoiceGroup, List

public interface Choice

Choice defines an API for a user interface components implementing selection from predefined number of choices. Such UI components are 
List
 and [code]ChoiceGroup

. The contents of the

Choice

are represented with strings and images. [/code]

Each element of a 
Choice
 is composed of a text string part, an [code]Image

part, and a font attribute that are all treated as a unit. The font attribute applies to the text part and can be controlled by the application. The application may provide

null

for the image if the element is not to have an image part. The implementation must display the image at the beginning of the text string. If the

Choice

also has a selection indicator (such as a radio button or a checkbox) placed at the beginning of the text string, the element's image should be placed between the selection indicator and the beginning of the text string.[/code]

When a new element is inserted or appended, the implementation provides a default font for the font attribute. This default font is the same font that is used if the application calls 
setFont(i, null)
. All [code]ChoiceGroup

instances must have the same default font, and all

List

instances must have the same default font. However, the default font used for

Choice

objects may differ from the font returned by

Font.getDefaultFont

.[/code]

The 
Image
 part of a [code]Choice

element may be mutable or immutable. If the

Image

is mutable, the effect is as if snapshot of its contents is taken at the time the

Choice

is constructed with this

Image

or when the

Choice

element is created or modified with the

append

,

insert

, or

set

methods. The snapshot is used whenever the contents of the

Choice

element are to be displayed. Even if the application subsequently draws into the

Image

, the snapshot is not modified until the next call to one of the above methods. The snapshot is not updated when the

Choice

becomes visible on the display. (This is because the application does not have control over exactly when

Displayables

and

Items

appear and disappear from the display.)[/code]

The following code illustrates a technique to refresh the image part of element 
k
 of a [code]Choice

ch

: [/code]

ch.set(k, ch.getString(k), ch.getImage(k));    

[/code]

If the application provides an image, the implementation may choose to truncate it if it exceeds the capacity of the device to display it. 
Images
 within any particular [code]Choice

object should all be of the same size, because the implementation is allowed to allocate the same amount of space for every element. The application can query the implementation's image size recommendation by calling

Display.getBestImageWidth(int)

and

Display.getBestImageHeight(int)

.[/code]

If an element is very long or contains a line break, the implementation may display only a portion of it. If this occurs, the implementation should provide the user with a means to see as much as possible of the element. If this is done by wrapping an element to multiple lines, the second and subsequent lines should show a clear indication to the user that they are part of the same element and are not a new element.

The application can express a preference for the policy used by the implementation for display of long elements including those that contain line break characters. The characters after the first line break may only be visible if the policy permits it. The 
setFitPolicy(int)
 and [code]getFitPolicy()

methods control this preference. The valid settings are

TEXT_WRAP_DEFAULT

,

TEXT_WRAP_ON

, and

TEXT_WRAP_OFF

. Unless specified otherwise by

Choice

implementation classes, the initial value of the element fit policy is

TEXT_WRAP_DEFAULT

.[/code]

After a 
Choice
 object has been created, elements may be inserted, appended, and deleted, and each element's string part and image part may be get and set. Elements within a [code]Choice

object are referred to by their indexes, which are consecutive integers in the range from zero to

size()-1

, with zero referring to the first element and

size()-1

to the last element. [/code]

There are four types of 
Choices
: implicit-choice (valid only for [code]List

), exclusive-choice, multiple-choice, and pop-up (valid only for

ChoiceGroup

). [/code]

The exclusive-choice presents a series of elements and interacts with the user. That is, when the user selects an element, that element is shown to be selected using a distinct visual representation. If there are elements present in the 
Choice
, one element must be selected at any given time. If at any time a situation would result where there are elements in the exclusive-choice but none is selected, the implementation will choose an element and select it. This situation can arise when an element is added to an empty [code]Choice

, when the selected element is deleted from the

Choice

, or when a

Choice

is created and populated with elements by a constructor. In these cases, the choice of which element is selected is left to the implementation. Applications for which the selected element is significant should set the selection explicitly. There is no way for the user to unselect an element within an exclusive

Choice

.[/code]

The popup choice is similar to the exclusive choice. The selection behavior of a popup choice is identical to that of an exclusive choice. However, a popup choice differs from an exclusive choice in presentation and interaction. In an exclusive choice, all elements should be displayed in-line. In a popup choice, the selected element should always be displayed, and the other elements should remain hidden until the user performs a specific action to show them. For example, an exclusive choice could be implemented as a series of radio buttons with one always selected. A popup choice could be implemented as a popup menu, with the selected element being displayed in the menu button.

The implicit choice is an exclusive choice where the focused or highlighted element is implicitly selected when a command is initiated. As with the exclusive choice, if there are elements present in the 
Choice
, one element is always selected.

A multiple-choice presents a series of elements and allows the user to select any number of elements in any combination. As with exclusive-choice, the multiple-choice interacts with the user in object-operation mode. The visual appearance of a multiple-choice will likely have a visual representation distinct from the exclusive-choice that shows the selected state of each element as well as indicating to the user that multiple elements may be selected.

The selected state of an element is a property of the element. This state stays with that element if other elements are inserted or deleted, causing elements to be shifted around. For example, suppose element n is selected, and a new element is inserted at index zero. The selected element would now have index n+1. A similar rule applies to deletion. Assuming n is greater than zero, deleting element zero would leave element n-1 selected. Setting the contents of an element leaves its selected state unchanged. When a new element is inserted or appended, it is always unselected (except in the special case of adding an element to an empty Exclusive, Popup, or Implicit Choice as mentioned above).

The selected state of a 
Choice
 object can be controlled by the application with the [code]setSelectedFlags

and

setSelectedIndex

methods. This state is available to the application through the

getSelectedFlags

and

getSelectedIndex

methods. The selected state reported by these methods is generally identical to what has been set by the application, with the following exceptions. Adding or removing elements may change the selection. When the

Choice

is present on the display, the implementation's user interface policy and direct user interaction with the object may also affect the selection. For example, the implementation might update the selection to the current highlight location as the user is moving the highlight, or it might set the selection from the highlight only when the user is about to invoke a command. As another example, the implementation might move the highlight (and thus the selection) of an implicit

List

to the first element each time the

List

becomes current. When a

Choice

object is present on the display, applications should query its selected state only within a

CommandListener

or a

ItemStateListener

callback. Querying the state at other times might result in a value different from what has been set by the application (because the user or the implementation's UI policy might have changed it) and it might not reflect the user's intent (because the user might still in the process of making a selection).[/code]

Note: Methods have been added to the 
Choice
 interface in version 2.0. Adding methods to interfaces is normally an incompatible change. However, [code]Choice

does not appear as a type in any field, method parameter, or method return value, and so it is not useful for an application to create a class that implements the

Choice

interface. Future versions of this specification may make additional changes to the

Choice

interface. In order to remain compatible with future versions of this specification, applications should avoid creating classes that implement the

Choice

interface. [/code]

Since: MIDP 1.0                                            翻译:lori.wang