|
MIDP3.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 ChoiceGroup
. The contents of the Choice
are represented with strings and images.
Each element of a Choice
is composed of a text string part, an
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.
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
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
.
The Image
part of a 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.)
The following code illustrates a technique to refresh the image part of
element k
of a Choice
ch
:
ch.set(k, ch.getString(k), ch.getImage(k));
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 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)
.
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
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
.
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 zero to size()-1
, with zero referring to the first
element and size()-1
to the last element.
There are four types of Choices
: implicit-choice (valid only
for List
), exclusive-choice, multiple-choice, and pop-up (valid
only for ChoiceGroup
).
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 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
.
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 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).
Disabling a Choice element automatically marks the state of the choice element
as not-selected. Hence, a disabled choice element once enabled using
setEnabled(i, true)
will be in not-selected state
(except for EXCLUSIVE/POPUP/IMPLICIT Choice, where at least one element MUST
be selected, see details in next paragraph). Attempts to set the state of a
disabled choice element using a setSelectedIndex
or
setSelectedFlags
will have no effect on the state
of the element.
In the case of EXCLUSIVE/IMPLICT/POPUP Choice elements, if there were no enabled
elements in the Choice and setEnabled(i, true)
was called to enable
element i, then this choice element at index i is marked selected automatically.
If the currently selected Choice element is disabled using
setEnabled (i, false)
, the implementation MUST look for the next
Choice
element that is enabled in this Choice to mark as selected.
If the end of the Choice
is reached and no enabled element is
found, the implementation MUST continue to look for an enabled element starting
from index 0. It is possible that no enabled Choice
elements exist
in the Choice
, and hence no element is marked selected in this
EXCLUSIVE/IMPLICIT/POPUP Choice
.
Note: Methods have been added to the Choice
interface in version 2.0. Adding methods to interfaces is normally an
incompatible change. However, 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.
Field Summary | |
---|---|
static int |
EXCLUSIVE
EXCLUSIVE is a choice having exactly one element selected
at time. |
static int |
IMPLICIT
IMPLICIT is a choice in which the currently focused
element is selected when a Command is initiated. |
static int |
MULTIPLE
MULTIPLE is a choice that can have arbitrary number of
elements selected at a time. |
static int |
POPUP
POPUP is a choice having exactly one element selected at a
time. |
static int |
TEXT_WRAP_DEFAULT
Constant for indicating that the application has no preference as to wrapping or truncation of text element contents and that the implementation should use its default behavior. |
static int |
TEXT_WRAP_OFF
Constant for hinting that text element contents should be limited to a single line. |
static int |
TEXT_WRAP_ON
Constant for hinting that text element contents should be wrapped to multiple lines if necessary to fit available content space. |
Method Summary | |
---|---|
int |
append(java.lang.String stringPart,
Image imagePart)
Appends an element to the Choice . |
void |
delete(int elementNum)
Deletes the element referenced by elementNum . |
void |
deleteAll()
Deletes all elements from this Choice , leaving it with
zero elements. |
int |
getFitPolicy()
Gets the application's preferred policy for fitting Choice
element contents to the available screen space. |
Font |
getFont(int elementNum)
Gets the application's preferred font for rendering the specified element of this Choice . |
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. |
java.lang.String |
getString(int elementNum)
Gets the String part of the element referenced by
elementNum . |
void |
insert(int elementNum,
java.lang.String stringPart,
Image imagePart)
Inserts an element into the Choice just prior to the
element specified. |
boolean |
isEnabled(int elementNum)
Gets a boolean value indicating whether the specified Choice element is enabled or disabled. |
boolean |
isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected. |
void |
set(int elementNum,
java.lang.String stringPart,
Image imagePart)
Sets the String and Image parts of the
element referenced by elementNum , replacing the previous
contents of the element. |
void |
setEnabled(int elementNum,
boolean isEnabled)
Sets the Choice element into enabled or
disabled mode. |
void |
setFitPolicy(int fitPolicy)
Sets the application's preferred policy for fitting Choice
element contents to the available screen space. |
void |
setFont(int elementNum,
Font font)
Sets the application's preferred font for rendering the specified element of this Choice . |
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 |
---|
static final int EXCLUSIVE
EXCLUSIVE
is a choice having exactly one element selected
at time. All elements of an EXCLUSIVE
type
Choice
should be displayed in-line. That is, the user
should not need to perform any extra action to traverse among and select
from the elements.
Value 1
is assigned to EXCLUSIVE
.
static final int MULTIPLE
MULTIPLE
is a choice that can have arbitrary number of
elements selected at a time.
Value 2
is assigned to MULTIPLE
.
static final int IMPLICIT
IMPLICIT
is a choice in which the currently focused
element is selected when a Command
is initiated.
The IMPLICIT
type is not valid for ChoiceGroup
objects.
Value 3
is assigned to IMPLICIT
.
static final int POPUP
POPUP
is a choice having exactly one element selected at a
time. The selected element is always shown. The other elements should be
hidden until the user performs a particular action to show them. When the
user performs this action, all elements become accessible. For example,
an implementation could use a popup menu to display the elements of a
ChoiceGroup
of type POPUP
.
The POPUP
type is not valid for List
objects.
Value 4
is assigned to POPUP
.
static final int TEXT_WRAP_DEFAULT
Field has the value 0
.
getFitPolicy()
,
setFitPolicy(int)
,
Constant Field Valuesstatic final int TEXT_WRAP_ON
Field has the value 1
.
getFitPolicy()
,
setFitPolicy(int)
,
Constant Field Valuesstatic final int TEXT_WRAP_OFF
Implementations should indicate that cropping has occurred, for example, by placing an ellipsis at the point where the text contents have been cropped.
Field has the value 2
.
getFitPolicy()
,
setFitPolicy(int)
,
Constant Field ValuesMethod Detail |
---|
int size()
Choice
java.lang.String getString(int elementNum)
String
part of the element referenced by
elementNum
.
The elementNum
parameter must
be within the range [0..size()-1]
, inclusive.
elementNum
- the index of the element to be queried, starting from zero
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidgetImage(int)
Image getImage(int elementNum)
Image
part of the element referenced by
elementNum
.
The elementNum
parameter must
be within the range [0..size()-1]
, inclusive.
elementNum
- the index of the element to be queried, starting from zero
null
if there is
no image
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidgetString(int)
int append(java.lang.String stringPart, Image imagePart)
Choice
. The added element will
be the last element of the Choice
. The size of the
Choice
grows by one.
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 part
java.lang.NullPointerException
- if stringPart
is null
void insert(int elementNum, java.lang.String stringPart, Image imagePart)
Choice
just prior to the
element specified. The size of the Choice
grows by one.
The elementNum
parameter must be within the range
[0..size()]
, inclusive. The index of the last element is
size()-1
, and so there is actually no element whose index
is size()
. If this value is used for
elementNum
, the new element is inserted immediately after
the last element. In this case, the effect is identical to
append()
.
elementNum
- the index of the element where insertion is to occur, starting from zerostringPart
- 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 part
java.lang.IndexOutOfBoundsException
- if elementNum
is invalid
java.lang.NullPointerException
- if stringPart
is null
void delete(int elementNum)
elementNum
. The size of
the Choice
shrinks by one. It is legal to delete all
elements from a Choice
. The elementNum
parameter must be within the range [0..size()-1]
,
inclusive.
elementNum
- the index of the element to be deleted, starting from zero
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidvoid deleteAll()
Choice
, leaving it with
zero elements. This method does nothing if the Choice
is
already empty.
void set(int elementNum, java.lang.String stringPart, Image imagePart)
String
and Image
parts of the
element referenced by elementNum
, replacing the previous
contents of the element. The elementNum
parameter must be
within the range [0..size()-1]
, inclusive.
The font attribute of the element is left unchanged.
elementNum
- the index of the element to be set, starting from zerostringPart
- the string part of the new elementimagePart
- the image part of the element, or null
if there
is no image part
java.lang.IndexOutOfBoundsException
- if elementNum
is invalid
java.lang.NullPointerException
- if stringPart
is null
boolean isSelected(int elementNum)
TheelementNum
parameter must be within the range
[0..size()-1]
, inclusive.
elementNum
- the index of the element to be queried, starting from zero
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidint getSelectedIndex()
Choice
that
is selected. For Choice
types EXCLUSIVE
,
POPUP
, and IMPLICIT
there is at most one
element selected, so this method is useful for determining the user's
choice. Returns -1
if the Choice
has no
elements (and therefore has no selected elements).
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
.
-1
if nonesetSelectedIndex(int, boolean)
int getSelectedFlags(boolean[] selectedArray_return)
Choice
and returns the state of all
elements in the boolean array selectedArray_return
.
Note: this is a result parameter. It must be at least
as long as the size of the Choice
as returned by
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
,
POPUP
, and IMPLICIT
exactly one element
will be selected (unless there are zero elements in the
Choice
).
selectedArray_return
- array to contain the results
Choice
java.lang.IllegalArgumentException
- if selectedArray_return
is shorter than the
size of the Choice
.
java.lang.NullPointerException
- if selectedArray_return
is null
setSelectedFlags(boolean[])
void setSelectedIndex(int elementNum, boolean selected)
MULTIPLE
, this simply sets an individual element's
selected state.
For EXCLUSIVE
and POPUP
, this can be used
only to select any 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. If element was already
selected, the call has no effect.
For IMPLICIT
, this can be used only to select any
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. If element was already selected, the call has no effect.
The call to setSelectedIndex
does not cause implicit
activation of any Command
.
For all list types, the elementNum
parameter must be
within the range [0..size()-1]
, inclusive.
elementNum
- the index of the element, starting from zeroselected
- the state of the element, where true
means
selected and false
means not selected
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidgetSelectedIndex()
void setSelectedFlags(boolean[] selectedArray)
Choice
. The array must be at least as long as the size of
the Choice
. If the array is longer, the additional values
are ignored.
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
,
POPUP
, 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 collect the selection status
java.lang.IllegalArgumentException
- if selectedArray
is shorter than the size of
the Choice
java.lang.NullPointerException
- if selectedArray
is null
getSelectedFlags(boolean[])
void setFitPolicy(int fitPolicy)
Choice
element contents to the available screen space. The set policy applies
for all elements of the Choice
object. Valid values are
TEXT_WRAP_DEFAULT
, TEXT_WRAP_ON
, and
TEXT_WRAP_OFF
. Fit policy is a hint, and the implementation may
disregard the application's preferred policy.
fitPolicy
- preferred content fit policy for choice elements
java.lang.IllegalArgumentException
- if fitPolicy
is invalidgetFitPolicy()
int getFitPolicy()
Choice
element contents to the available screen space. The value returned is the
policy that had been set by the application, even if that value had been
disregarded by the implementation.
TEXT_WRAP_DEFAULT
, TEXT_WRAP_ON
, or
TEXT_WRAP_OFF
setFitPolicy(int)
void setFont(int elementNum, Font font)
Choice
. An element's font is a hint, and the
implementation may disregard the application's preferred font.
The elementNum
parameter must be within the range
[0..size()-1]
, inclusive.
The font
parameter must be a valid Font
object or null
. If the font
parameter is
null
, the implementation must use its default font to
render the element.
elementNum
- the index of the element, starting from zerofont
- the preferred font to use to render the element
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidgetFont(int)
Font getFont(int elementNum)
Choice
. The value returned is the font that had
been set by the application, even if that value had been disregarded by
the implementation. If no font had been set by the application, or if the
application explicitly set the font to null
, the value is
the default font chosen by the implementation.
The elementNum
parameter must be within the range
[0..size()-1]
, inclusive.
elementNum
- the index of the element, starting from zero
java.lang.IndexOutOfBoundsException
- if elementNum
is invalidsetFont(int, javax.microedition.lcdui.Font)
void setEnabled(int elementNum, boolean isEnabled)
Choice
element into enabled or
disabled mode. The set mode applies for the
element of the Choice
object specified by the elementNum
parameter. A disabled Choice element
SHOULD be visually different from an enabled Choice element.
The elementNum
parameter must be within the
range [0..size()-1]
, inclusive.
elementNum
- the index of the element to which the mode change
is applied, the index starts from zeroisEnabled
- true if enabled, false if disabled
java.lang.IndexOutOfBoundsException
- if elementNum
is
invalidisEnabled(int)
boolean isEnabled(int elementNum)
The elementNum
parameter must be within the range
[0..size()-1]
, inclusive.
elementNum
- the index of the element to be queried, starting from zero
java.lang.IndexOutOfBoundsException
- if elementNum
is
invalid
|
MIDP3.0 | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |