|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.lcdui.Displayable | +--javax.microedition.lcdui.Screen | +--javax.microedition.lcdui.List
A Screen
containing list of choices. Most of its
behavior is common with
class ChoiceGroup
, and their common API. The
different List
types in particular, are defined in
interface Choice
. When a List
is present on the display, the
user can interact with
it by selecting elements and possibly by traversing and scrolling among
them. Traversing and scrolling operations do not cause application-visible
events. The system notifies the application only when a Command
is invoked by notifying its CommandListener
. The
List
class also supports a select command that may be invoked specially
depending upon the capabilities of the device.
The notion of a select operation on a List
element is central
to the user's interaction with the List
. On devices
that have a dedicated
hardware "select" or "go" key, the select
operation is implemented with
that key. Devices that do not have a dedicated key must provide another
means to do the select operation, for example, using a soft key. The
behavior of the select operation within the different types of lists is
described in the following sections.
List
objects may be created with Choice
types of
Choice.EXCLUSIVE
, Choice.MULTIPLE
, and
Choice.IMPLICIT
. The Choice
type Choice.POPUP
is not allowed on List
objects.
EXCLUSIVE
and MULTIPLE
ListsThe select operation is not associated with a
Command
object, so the
application has no means of setting a label for it or being notified when
the operation is performed. In Lists
of type
EXCLUSIVE
, the select
operation selects the target element and deselects the previously selected
element. In Lists
of type MULTIPLE
, the
select operation toggles the
selected state of the target element, leaving the selected state of other
elements unchanged. Devices that implement the select operation using a
soft key will need to provide a label for it. The label should be something
similar to "Select" for Lists
of type
EXCLUSIVE
, and it should be something
similar to "Mark" or "Unmark" for
Lists
of type MULTIPLE
.
IMPLICIT
ListsThe select operation is associated with a Command
object referred to as
the select command. When the user performs the select operation,
the system will invoke the select command by notifying the
List's
CommandListener
. The default select command is the
system-provided command SELECT_COMMAND
. The select
command may be modified
by the application through use of the setSelectCommand
method. Devices that implement the select
operation using a soft key will use the label from the select command. If
the select command is SELECT_COMMAND
, the device may
choose to provide its
own label instead of using the label attribute of
SELECT_COMMAND
.
Applications should generally provide their own select command to replace
SELECT_COMMAND
. This allows applications to provide a
meaningful label,
instead of relying on the one provided by the system for
SELECT_COMMAND
.
The implementation must not invoke the select command if there are
no elements in the List
, because if the
List
is empty the selection does
not exist. In this case the implementation should remove or disable the
select command if it would appear explicitly on a soft button or in a menu.
Other commands can be invoked normally when the List
is empty.
IMPLICIT
Lists IMPLICIT
Lists
can be used to
construct menus by providing operations
as List
elements. The application provides a
Command
that is used to
select a List
element and then defines this
Command
to be used as the
select command. The application must also register a
CommandListener
that
is called when the user selects or activates the Command
:
|
The listener can query the List
to determine which
element is selected
and then perform the corresponding action. Note that setting a command as
the select command adds it to the List
as a side effect.
The select command should be considered as a default operation
that takes place when a select key is pressed. For example, a
List
displaying email headers might have three operations: read, reply, and
delete. Read is considered to be the default operation.
|
On a device with a dedicated select key, pressing this key will invoke
readCommand
. On a device without a select key, the user is
still able to invoke the read command, since it is also provided as an
ordinary Command
.
It should be noted that this kind of default operation must be used carefully, and the usability of the resulting user interface must always kept in mind. The default operation should always be the most intuitive operation on a particular List.
Field Summary | |
static Command |
SELECT_COMMAND
The default select command for IMPLICIT Lists . |
Fields inherited from interface javax.microedition.lcdui.Choice |
EXCLUSIVE, IMPLICIT, MULTIPLE, POPUP, TEXT_WRAP_DEFAULT, TEXT_WRAP_OFF, TEXT_WRAP_ON |
Constructor Summary | |
List(String title,
int listType)
Creates a new, empty List , specifying its title
and the type of the
list. |
|
List(String title,
int listType,
String[] stringElements,
Image[] imageElements)
Creates a new List , specifying its title, the type
of the List , and
an array of Strings and Images to be
used as its initial contents. |
Method Summary | |
int |
append(String stringPart,
Image imagePart)
Appends an element to the List . |
void |
delete(int elementNum)
Deletes the element referenced by elementNum . |
void |
deleteAll()
Deletes all elements from this List. |
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 List and returns the
state of all elements
in the
boolean array
selectedArray_return . |
int |
getSelectedIndex()
Returns the index number of an element in the List
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 List just prior to
the element specified. |
boolean |
isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected. |
void |
removeCommand(Command cmd)
The same as Displayable.removeCommand
but with the following additional semantics. |
void |
set(int elementNum,
String stringPart,
Image imagePart)
Sets the String and Image parts of the
element referenced by elementNum ,
replacing the previous contents of the element. |
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 |
setSelectCommand(Command command)
Sets the Command to be used for an
IMPLICIT List selection
action. |
void |
setSelectedFlags(boolean[] selectedArray)
Sets the selected state of all elements of the List . |
void |
setSelectedIndex(int elementNum,
boolean selected)
Sets the selected state of an element. |
void |
setTicker(Ticker ticker)
Sets a ticker for use with this Displayable ,
replacing any
previous ticker. |
void |
setTitle(String s)
Sets the title of the Displayable . |
int |
size()
Gets the number of elements in the List . |
Methods inherited from class javax.microedition.lcdui.Displayable |
addCommand, getHeight, getTicker, getTitle, getWidth, isShown, setCommandListener, sizeChanged |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final Command SELECT_COMMAND
IMPLICIT
Lists
.
Applications using an IMPLICIT
List
should set their own select command
using
setSelectCommand
.
The field values of SELECT_COMMAND
are:
- label = ""
(an empty string)
- type = SCREEN
- priority = 0
(It would be more appropriate if the type were
ITEM
, but the type of
SCREEN
is retained for historical purposes.)
The application should not use these values for recognizing
the SELECT_COMMAND
. Instead, object identities of
the Command
and
Displayable
(List
) should be used.
SELECT_COMMAND
is treated as an ordinary
Command
if it is used with other Displayable
types.
Constructor Detail |
public List(String title, int listType)
List
, specifying its title
and the type of the
list.title
- the screen's title (see Displayable
)listType
- one of IMPLICIT
, EXCLUSIVE
,
or MULTIPLE
IllegalArgumentException
- if listType
is not
one of
IMPLICIT
,
EXCLUSIVE
, or MULTIPLE
Choice
public List(String title, int listType, String[] stringElements, Image[] imageElements)
List
, specifying its title, the type
of the List
, and
an array of Strings
and Images
to be
used as its initial contents.
The stringElements
array must be non-null and
every array element
must also be non-null. The length of the
stringElements
array
determines the number of elements in the List
.
The imageElements
array
may be null
to indicate that the List
elements have no images. If the
imageElements
array is non-null, it must be the
same length as the
stringElements
array. Individual elements of the
imageElements
array
may be null
in order to indicate the absence of an
image for the
corresponding List
element. Non-null elements of the
imageElements
array may refer to mutable or
immutable images.
title
- the screen's title (see Displayable
)listType
- one of IMPLICIT
, EXCLUSIVE
,
or MULTIPLE
stringElements
- set of strings specifying the string parts of the
List
elementsimageElements
- set of images specifying the image parts of
the List
elementsNullPointerException
- if stringElements
is
null
NullPointerException
- if the stringElements
array contains any null elementsIllegalArgumentException
- if the imageElements
array is non-null
and has a different length from the stringElements
arrayIllegalArgumentException
- if listType
is not one
of IMPLICIT
,
EXCLUSIVE
, or MULTIPLE
Choice.EXCLUSIVE
,
Choice.MULTIPLE
,
Choice.IMPLICIT
Method Detail |
public void setTicker(Ticker ticker)
Displayable
,
replacing any
previous ticker.
If null
, removes the ticker object
from this Displayable
. The same ticker may be shared by
several Displayable
objects within an application. This is done by calling
setTicker()
with the same Ticker
object on several
different Displayable
objects.
If the Displayable
is actually visible on the display,
the implementation should update
the display as soon as it is feasible to do so.
The existence of a ticker may affect the size
of the area available for Displayable's
contents.
If the application adds, removes, or sets the ticker text at runtime,
this can dynamically change the size of the content area.
This is most important to be aware of when using the
Canvas
class.
setTicker
in class Displayable
ticker
- the ticker object used on this screenDisplayable.getTicker()
public void setTitle(String s)
Displayable
. If
null
is given,
removes the title.
If the Displayable
is actually visible on
the display,
the implementation should update
the display as soon as it is feasible to do so.
The existence of a title may affect the size
of the area available for Displayable
content.
If the application adds, removes, or sets the title text at runtime,
this can dynamically change the size of the content area.
This is most important to be aware of when using the
Canvas
class.
setTitle
in class Displayable
s
- the new title, or null
for no titleDisplayable.getTitle()
public int size()
List
.size
in interface Choice
List
public String getString(int elementNum)
String
part of the element referenced by
elementNum
.getString
in interface Choice
elementNum
- the index of the element to be queriedIndexOutOfBoundsException
- if elementNum
is invalidgetImage(int)
public Image getImage(int elementNum)
Image
part of the element referenced by
elementNum
.getImage
in interface Choice
elementNum
- the number of the element to be queriednull
if there is no imageIndexOutOfBoundsException
- if elementNum
is invalidgetString(int)
public int append(String stringPart, Image imagePart)
List
.append
in interface Choice
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 partNullPointerException
- if stringPart
is
null
public void insert(int elementNum, String stringPart, Image imagePart)
List
just prior to
the element specified.insert
in interface Choice
elementNum
- the index of the element where insertion is to occurstringPart
- 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 partIndexOutOfBoundsException
- if elementNum
is invalidNullPointerException
- if stringPart
is
null
public void delete(int elementNum)
elementNum
.delete
in interface Choice
elementNum
- the index of the element to be deletedIndexOutOfBoundsException
- if elementNum
is invalidpublic void deleteAll()
deleteAll
in interface Choice
public void set(int elementNum, String stringPart, Image imagePart)
String
and Image
parts of the
element referenced by elementNum
,
replacing the previous contents of the element.set
in interface Choice
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 partIndexOutOfBoundsException
- if elementNum
is invalidNullPointerException
- if stringPart
is
null
public boolean isSelected(int elementNum)
isSelected
in interface Choice
elementNum
- index to element to be queriedIndexOutOfBoundsException
- if elementNum
is invalidpublic int getSelectedIndex()
List
that is selected.getSelectedIndex
in interface Choice
-1
if nonesetSelectedIndex(int, boolean)
public int getSelectedFlags(boolean[] selectedArray_return)
List
and returns the
state of all elements
in the
boolean array
selectedArray_return
.getSelectedFlags
in interface Choice
selectedArray_return
- array to contain the resultsChoice
IllegalArgumentException
- if selectedArray_return
is shorter than the size of the ListNullPointerException
- if selectedArray_return
is null
setSelectedFlags(boolean[])
public void setSelectedIndex(int elementNum, boolean selected)
setSelectedIndex
in interface Choice
elementNum
- the index of the element, starting from zeroselected
- the state of the element, where true
means
selected and false
means not selectedIndexOutOfBoundsException
- if elementNum
is invalidgetSelectedIndex()
public void setSelectedFlags(boolean[] selectedArray)
List
.setSelectedFlags
in interface Choice
selectedArray
- an array in which the method collect
the selection statusIllegalArgumentException
- if selectedArray
is
shorter than the size of the List
NullPointerException
- if selectedArray
is
null
getSelectedFlags(boolean[])
public void removeCommand(Command cmd)
Displayable.removeCommand
but with the following additional semantics.
If the command to be removed happens to be the select command, the
List
is set to have no select command, and the command is
removed from the List
.
The following code:
|
is equivalent to the following code:
|
removeCommand
in class Displayable
cmd
- the command to be removedpublic void setSelectCommand(Command command)
Command
to be used for an
IMPLICIT
List
selection
action.
By default, an implicit selection of a List will result in the
predefined List.SELECT_COMMAND
being used. This
behavior may be
overridden by calling the List.setSelectCommand()
method with an
appropriate parameter value. If a null
reference
is passed, this
indicates that no "select" action is appropriate for
the contents
of this List
.
If a reference to a command object is passed, and
it is not the special command List.SELECT_COMMAND
, and
it is not currently present on this List
object,
the command object is added to this List
as if
addCommand(command)
had been called
prior to the command being made the select command. This
indicates that this command
is to be invoked when the user performs the "select"
on an element of
this List
.
The select command should have a command type of
ITEM
to indicate
that it operates on the currently selected object. It is not an error
if the command is of some other type.
(List.SELECT_COMMAND
has a type
of SCREEN
for historical purposes.) For purposes
of presentation and
placement within its user interface, the implementation is allowed to
treat the select command as if it were of type ITEM
.
If the select command is later removed from the List
with removeCommand()
, the List
is set to have
no select command as if List.setSelectCommand(null)
had
been called.
The default behavior can be reestablished explicitly by calling
setSelectCommand()
with an argument of
List.SELECT_COMMAND
.
This method has no effect if the type of the
List
is not IMPLICIT
.
command
- the command to be used for an IMPLICIT
list
selection action, or null
if there is nonepublic 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
Choice.TEXT_WRAP_DEFAULT
, Choice.TEXT_WRAP_ON
,
and Choice.TEXT_WRAP_OFF
. Fit policy is a hint, and the
implementation may disregard the application's preferred policy.setFitPolicy
in interface Choice
fitPolicy
- preferred content fit policy for choice elementsIllegalArgumentException
- if fitPolicy
is invalidgetFitPolicy()
public 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.getFitPolicy
in interface Choice
Choice.TEXT_WRAP_DEFAULT
, Choice.TEXT_WRAP_ON
, or
Choice.TEXT_WRAP_OFF
setFitPolicy(int)
public 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.
setFont
in interface Choice
elementNum
- the index of the element, starting from zerofont
- the preferred font to use to render the elementIndexOutOfBoundsException
- if elementNum
is invalidgetFont(int)
public 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.
getFont
in interface Choice
elementNum
- the index of the element, starting from zeroIndexOutOfBoundsException
- if elementNum
is invalidsetFont(int elementNum, Font font)
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |