|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Choice defines an API for a user interface component implementing
selection from a predefined number of choices. Such UI components are
List
and ChoiceGroup
. The contents
of Choice are represented with strings and optional images.
Each element of a Choice is composed of a text string and an
optional image. The application may provide null
for the
image if the element does not have an image part. If the application
provides an image, the implementation may choose to ignore the image
if it exceeds the capacity of the device to display it. If the
implementation displays the image, it will be displayed adjacent to
the text string and the pair will be treated as a unit.
Images
within any particular Choice object should all be of the
same size, because the implementation is allowed to allocate the same amount
of vertical space for every element
If an element is too long to be displayed, the implementation will provide the user with means to see the whole element. If this is done by wrapping an element to multiple lines, the second and subsequent lines show a clear indication to the user that they are part of the same element and are not a new element.
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 Choice object are referred to by their indexes, which are consecutive integers in the range from 0 to size()-1, with 0 referring to the first element and size()-1 to the last element.
There are three types of Choices: implicit-choice (valid only for
List
), exclusive-choice, and multiple-choice.
The exclusive-choice
presents a series of elements and
interacts with the
user in object-action mode. That is, when the user selects an element, that
element is shown to be selected using a distinct visual representation.
Exactly 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 Choice,
or when the selected element is deleted from the Choice. There is no
way for the user to unselect an element within an exclusive
Choice.
The implicit-choice
is an exclusive choice where the
focused element is implicitly selected when a Command
is
initiated.
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.
When a Choice is present on the display the user can interact with it
indefinitely (for instance, traversing from element to element and possibly
scrolling). These traversing and scrolling operations do not cause
application-visible events. The system notifies the application either when
some application-defined Command
is fired, or when selection
state of ChoiceGroup
is changed. When a command is fired a high-level
event is delivered to the listener of the Screen
. The event
delivery is done with commandAction
. In the case of ChoiceGroup
,
the ItemStateListener
is
called when the user changes the selection state of the ChoiceGroup.
At this time the application can query the Choice for information
about the currently selected element(s).
Field Summary | |
static int |
EXCLUSIVE
EXCLUSIVE is a choice having exactly one element selected at a time. |
static int |
IMPLICIT
IMPLICIT is a choice in which the currently focused item is selected when a Command is initiated. |
static int |
MULTIPLE
MULTIPLE is a choice that can have an arbitrary number of elements selected at a time. |
Method Summary | |
int |
append(String stringPart,
Image imagePart)
Appends an element to the Choice. |
void |
delete(int elementNum)
Deletes the element referenced by elementNum. |
Image |
getImage(int elementNum)
Gets the Image part of the element referenced by elementNum. |
int |
getSelectedFlags(boolean[] selectedArray_return)
Queries the state of a Choice and returns the state of all elements in the boolean array selectedArray_return. |
int |
getSelectedIndex()
Returns the index number of an element in the Choice that is selected. |
String |
getString(int elementNum)
Gets the String part of the element referenced by elementNum. |
void |
insert(int elementNum,
String stringPart,
Image imagePart)
Inserts an element into the Choice just before the element specified. |
boolean |
isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected. |
void |
set(int elementNum,
String stringPart,
Image imagePart)
Sets the element referenced by elementNum to the specified element, replacing the previous contents of the element. |
void |
setSelectedFlags(boolean[] selectedArray)
Attempts to set the selected state of every element in the Choice. |
void |
setSelectedIndex(int elementNum,
boolean selected)
For MULTIPLE , this simply sets an individual element's
selected state. |
int |
size()
Gets the number of elements present. |
Field Detail |
public static final int EXCLUSIVE
Value 1 is assigned to EXCLUSIVE.
public static final int IMPLICIT
Command
is initiated.
(Note: IMPLICIT is not accepted by
ChoiceGroup
)Value 3 is assigned to IMPLICIT.
public static final int MULTIPLE
Value 2 is assigned to MULTIPLE.
Method Detail |
public int append(String stringPart, Image imagePart)
stringPart
- the string part of the element to be addedimagePart
- the image part of the element to be added, or
null if there is no image partpublic void delete(int elementNum)
elementNum
- the index of the element to be deletedpublic Image getImage(int elementNum)
elementNum
- the number of the elementgetString(int)
public int getSelectedFlags(boolean[] selectedArray_return)
size()
. If the array is
longer, the extra elements are set to false.This call is valid for all types of Choices. For MULTIPLE, any number of elements may be selected and set to true in the result array. For EXCLUSIVE and IMPLICIT exactly one element will be selected (unless there are zero elements in the Choice).
selectedArray_return
- array to contain the resultspublic int getSelectedIndex()
For MULTIPLE, this always returns -1 because no single value can in general represent the state of such a Choice.
To get the
complete state of a MULTIPLE Choice, see getSelectedFlags
.
public String getString(int elementNum)
elementNum
- the index of the element to be queriedgetImage(int)
public void insert(int elementNum, String stringPart, Image imagePart)
elementNum
- the number of the elementstringPart
- the string part of the element to be insertedimagePart
- the image part of the element to be inserted, or
null if there is no image partpublic boolean isSelected(int elementNum)
elementNum
- the index of the element to be queriedpublic void set(int elementNum, String stringPart, Image imagePart)
elementNum
- the index of the element to be setstringPart
- the string part of the new elementimagePart
- the image part of the element, or null if there
is no image partpublic void setSelectedFlags(boolean[] selectedArray)
For Choice objects of type MULTIPLE, this sets the selected state of every element in the Choice. An arbitrary number of elements may be selected.
For Choice objects of type EXCLUSIVE and IMPLICIT, exactly one array element must have the value true. If no element is true, the first element in the Choice will be selected. If two or more elements are true, the implementation will choose the first true element and select it.
selectedArray
- an array in which the method collects the
selection statuspublic void setSelectedIndex(int elementNum, boolean selected)
MULTIPLE
, this simply sets an individual element's
selected state.
For EXCLUSIVE
, this can be used only to select an
element, that is, the selected parameter must be true.
When an element is selected, the previously selected element is
deselected. If selected is false, this call is
ignored.
For IMPLICIT
, this can be used only to select an
element, that is, the selected parameter must be true.
When an element is selected, the previously selected element is
deselected. If selected is false, this call is ignored.
The call to setSelectedIndex does not cause implicit activation of a
Command
.
elementNum
- the index of the element, starting from zero.selected
- the new state of the element, where true means
selected, false means not selected.public int size()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |