|
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
The List class is a Screen containing list of choices.
Most of the behavior is common with class
ChoiceGroup and the common API
is defined in interface Choice.
When a List 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 when some
Command is fired.
The notification of the application is done with
commandAction .
List, like any Choice, utilizes a dedicated "select" or "go" functionality of the devices. Typically, the select functionality is distinct from the soft-buttons, but some devices may use soft-buttons for the select. In any case, the application does not have a mean to set a label for a select key.
In respect to select functionality here are three types of Lists:
CommandListener registered.
The element that has the focus will be selected before any CommandListener
for this List is called.
An implicit SELECT_COMMAND is a parameter
for the notification.IMPLICIT List can be used to construct menus by placing logical commands
to elements. In this case no application defined Commands
have to be attached. Application just has to register a CommandListener
that is called when user "selects".
Another use might be implementation of a Screen with a default operation that takes place when "select" is pressed. For example, the List may contain email headers, and three operations: read, reply, and delete. Read is consider to be the default operation.
void initialize() {
myScreen = new List("EMAIL", List.IMPLICIT);
readCommand = new Command("read", Command.SCREEN, 1);
replyCommand = new Command("reply", Command.SCREEN, 1);
deleteCommand = new Command("delete", Command.SCREEN, 1);
myScreen.addCommand(readCommand);
myScreen.addCommand(replyCommand);
myScreen.addCommand(deleteCommand);
myScreen.setCommandListener(this);
}
Because the list is of type IMPLICIT, the select operation also calls the
method commandAction
with parameter SELECT_COMMAND. The implementation of
commandAction() can now do the obvious thing and start the read operation:
public void commandAction (Command c, Displayable d) {
if (d == myScreen) {
if (c == readCommand || c == List.SELECT_COMMAND) {
// show the mail to the user
}
// ...
}
}
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 application can also set the currently selected element(s) prior to displaying the List.
Note: Many of the essential methods have been documented in
interface Choice.
| Field Summary | |
static Command |
SELECT_COMMAND
SELECT_COMMAND is a special command that commandAction
can use to recognize the user did the select operation on a IMPLICIT
List. |
| Fields inherited from interface javax.microedition.lcdui.Choice |
EXCLUSIVE,
IMPLICIT,
MULTIPLE |
| 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 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 prior to 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. |
| Methods inherited from class javax.microedition.lcdui.Screen |
getTicker,
getTitle,
setTicker,
setTitle |
| Methods inherited from class javax.microedition.lcdui.Displayable |
addCommand,
isShown,
removeCommand,
setCommandListener |
| Methods inherited from class java.lang.Object |
equals,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
| Field Detail |
public static final Command SELECT_COMMAND
commandAction
can use to recognize the user did the select operation on a IMPLICIT
List. The field values of SELECT_COMMAND are:| Constructor Detail |
public List(String title,
int listType)
Creates a new, empty List, specifying its title and the type of the list.
title - the screen's title (see Screen)listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLEChoice
public 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.
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. Any elements present in the imageElements array must refer to immutable images.
title - the screen's title (see Screen)listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLEstringElements - set of strings specifying the string parts of the
List elementsimageElements - set of images specifying the image parts of
the List elementsChoice.EXCLUSIVE,
Choice.MULTIPLE,
Choice.IMPLICIT| Method Detail |
public int size()
Gets the number of elements present.
public String getString(int elementNum)
Gets the 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 queriedgetImage(int)public Image getImage(int elementNum)
Gets the Image part of the element referenced by elementNum. The elementNum parameter must be within the range [0..size()-1], inclusive.
elementNum - the number of the element to be queriedgetString(int),
getString(int)
public int append(String stringPart,
Image imagePart)
Appends an element to the 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
public void insert(int elementNum,
String stringPart,
Image imagePart)
Inserts an element into the 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 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 partpublic void delete(int elementNum)
Deletes the element referenced by 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
public 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. The elementNum parameter must be within the range [0..size()-1], inclusive.
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 boolean isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected. The elementNum parameter must be within the range [0..size()-1], inclusive.
elementNum - index to element to be queriedpublic int getSelectedIndex()
Returns the index number of an element in the Choice that is selected. For Choice types EXCLUSIVE 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.
public int getSelectedFlags(boolean[] selectedArray_return)
Queries the state of a 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 and IMPLICIT exactly one element will be selected (unless there are zero elements in the Choice).
selectedArray_return - array to contain the results
public void setSelectedIndex(int elementNum,
boolean selected)
For MULTIPLE, this simply sets an individual element's selected state.
For EXCLUSIVE,
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 selectedpublic void setSelectedFlags(boolean[] selectedArray)
Attempts to set the selected state of every element in the 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 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
|
MID Profile | |||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||