Listpublic class List extends Screen implements ChoiceA Screen containing list of choices. Most of its
behavior is common with
class {@link ChoiceGroup ChoiceGroup}, and their common API. The
different List types in particular, are defined in
interface {@link Choice
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 {@link Command
Command} is invoked by notifying its {@link 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
{@link Choice#EXCLUSIVE}, {@link Choice#MULTIPLE}, and
{@link Choice#IMPLICIT}. The Choice type {@link Choice#POPUP}
is not allowed on List objects.
Selection in EXCLUSIVE and MULTIPLE Lists
The 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.
Selection in IMPLICIT Lists
The 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 {@link
CommandListener 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 {@link #setSelectCommand(Command
command) 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.
Use of 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:
String[] elements = { ... }; //Menu items as List elements
List menuList = new List("Menu", List.IMPLICIT, elements, null);
Command selectCommand = new Command("Open", Command.ITEM, 1);
menuList.setSelectCommand(selectCommand);
menuList.setCommandListener(...);
|
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.
List list = new List("Email", List.IMPLICIT, headers);
readCommand = new Command("Read", Command.ITEM, 1);
replyCommand = new Command("Reply", Command.ITEM, 2);
deleteCommand = new Command("Delete", Command.ITEM, 3);
list.setSelectCommand(readCommand);
list.addCommand(replyCommand);
list.addCommand(deleteCommand);
list.setCommandListener(...);
|
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. |
| Fields Summary |
|---|
| public static final Command | SELECT_COMMANDThe default select command for IMPLICIT Lists.
Applications using an IMPLICIT List
should set their own select command
using
{@link #setSelectCommand(Command command) 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.
| | private Form | formAn internal Form to render this List (basically, a List is
just a Form with a choiceGroup in it | | private ChoiceGroup | cgAn internal choicegroup to handle the selections | | private Command | selectCommandThis is an internal Command which represents the callback
to a selection event of an IMPLICIT list. By default, this
command is the predefined List.SELECT_COMMAND. This can be
overridden however using the setSelectCommand(). |
| Constructors Summary |
|---|
public List(String title, int listType)Creates a new, empty List, specifying its title
and the type of the
list.
// constructors //
this(title, listType, new String[] {}, new Image[] {});
| 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. Non-null elements of the
imageElements array may refer to mutable or
immutable images.
super(title);
if (!(listType == IMPLICIT ||
listType == EXCLUSIVE ||
listType == MULTIPLE)) {
throw new IllegalArgumentException();
}
synchronized (Display.LCDUILock) {
cg = new ChoiceGroup(null, listType,
stringElements, imageElements, true);
cg.isList = true;
form = new Form(title);
form.paintDelegate = this;
form.append(cg);
}
|
| Methods Summary |
|---|
| public int | append(java.lang.String stringPart, Image imagePart)Appends an element to the List.
return cg.append(stringPart, imagePart);
| | void | callHideNotify(Display d)Notify this Displayable it is being hidden on the given Display
super.callHideNotify(d);
form.callHideNotify(d);
| | void | callInvalidate(Item src)Called by the event thread to invalidate the contents
of this List
form.callInvalidate(src);
| | void | callItemStateChanged(Item src)Called by the event thread to notify an ItemStateChangeListener
that an item has changed
form.callItemStateChanged(src);
| | void | callKeyPressed(int keyCode)Handle a key pressed event
form.callKeyPressed(keyCode);
if (keyCode == Display.KEYCODE_SELECT) {
// don't invoke the select command if there are
// no elements in the List
if (cg.size() == 0) {
return;
}
CommandListener cl = null;
synchronized (Display.LCDUILock) {
cl = listener;
}
if (cl != null) {
try {
// SYNC NOTE: We lock on calloutLock around any calls
// into application code
synchronized (Display.calloutLock) {
cl.commandAction(selectCommand, this);
}
} catch (Throwable thr) {
Display.handleThrowable(thr);
}
}
}
| | void | callPaint(Graphics g, java.lang.Object target)Display calls this method on it's current Displayable.
SYNC NOTE: The caller of this method handles synchronization.
form.callPaint(g, target);
| | void | callShowNotify(Display d)Notify this Displayable it is being shown on the given Display
super.callShowNotify(d);
form.callShowNotify(d);
| | public void | delete(int elementNum)Deletes the element referenced by elementNum.
cg.delete(elementNum);
| | public void | deleteAll()Deletes all elements from this List.
cg.deleteAll();
| | public int | getFitPolicy()Gets the application's preferred policy for fitting
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.
return cg.getFitPolicy();
| | public Font | getFont(int elementNum)Gets the application's preferred font for
rendering the specified element of this 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.
return cg.getFont(elementNum);
| | public Image | getImage(int elementNum)Gets the Image part of the element referenced by
elementNum.
return cg.getImage(elementNum);
| | public int | getSelectedFlags(boolean[] selectedArray_return)Queries the state of a List and returns the
state of all elements
in the
boolean array
selectedArray_return.
return cg.getSelectedFlags(selectedArray_return);
| | public int | getSelectedIndex()Returns the index number of an element in the List
that is selected.
return cg.getSelectedIndex();
| | public java.lang.String | getString(int elementNum)Gets the String part of the element referenced by
elementNum.
return cg.getString(elementNum);
| | public void | insert(int elementNum, java.lang.String stringPart, Image imagePart)Inserts an element into the List just prior to
the element specified.
cg.insert(elementNum, stringPart, imagePart);
| | public boolean | isSelected(int elementNum)Gets a boolean value indicating whether this element is selected.
return cg.isSelected(elementNum);
| | public void | removeCommand(Command cmd)The same as {@link Displayable#removeCommand 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:
// Command c is the select command on List list
list.removeCommand(c);
|
is equivalent to the following code:
// Command c is the select command on List list
list.setSelectCommand(null);
list.removeCommand(c);
|
synchronized (Display.LCDUILock) {
super.removeCommandImpl(cmd);
if (cmd == selectCommand) {
selectCommand = null;
}
} // synchronized
| | public 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.
cg.set(elementNum, stringPart, imagePart);
| | public void | setFitPolicy(int fitPolicy)Sets the application's preferred policy for fitting
Choice element
contents to the available screen space. The set policy applies for all
elements of the Choice object. Valid values are
{@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON},
and {@link #TEXT_WRAP_OFF}. Fit policy is a hint, and the
implementation may disregard the application's preferred policy.
cg.setFitPolicy(fitPolicy);
| | public void | setFont(int elementNum, Font font)Sets the application's preferred font for
rendering the specified element of this 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.
cg.setFont(elementNum, font);
| | public void | setSelectCommand(Command command)Sets the 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.
// If we're not an IMPLICIT List, ignore this method
// call entirely
if (cg.getType() != Choice.IMPLICIT) {
return;
}
// Here we're just resetting the default behavior
// of this implicit List
if (command == List.SELECT_COMMAND) {
selectCommand = command;
return;
}
// Here we're deciding there is no appropriate default
// command for a selection
if (command == null) {
selectCommand = null;
return;
}
// SYNC NOTE: We grab the lock here because we need to determine
// if the command is in the Displayables command set AND we need
// to protect ourselves from the Command being removed from the
// set just after we've done the check. #See how we override the
// removeCommand() method in this class
synchronized (Display.LCDUILock) {
// We ensure that the provided Command has been added
// to this List.
addCommandImpl(command);
selectCommand = command;
}
| | public void | setSelectedFlags(boolean[] selectedArray)Sets the selected state of all elements of the List.
cg.setSelectedFlags(selectedArray);
| | public void | setSelectedIndex(int elementNum, boolean selected)Sets the selected state of an element.
cg.setSelectedIndex(elementNum, selected);
| | public void | setTicker(Ticker ticker)Sets a ticker for use with this 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.
super.setTicker(ticker);
// We override this method from Displayable to set the ticker
// on our internal Form which is doing all our rendering
form.setTicker(ticker);
| | public void | setTitle(java.lang.String s)Sets the title of the 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.
super.setTitle(s);
// We override this method from Displayable to set the title
// on our internal Form which is doing all our rendering
form.setTitle(s);
| | public int | size()Gets the number of elements in the List.
return cg.size();
|
|
