Programming Wireless Devices with the Java2 Platform
| [ directory ] |
|
9.1 ListThe List class is a Screen that displays a list of choice items. The choice items are called elements. Each element has an associated string and may have an icon (an Image). There are three types of Lists: implicit, exclusive, and multiple choice. The type of the List is selected when the List is constructed and cannot be changed during the lifetime of the List object. The look and feel of Lists varies from one type of List to another, as illustrated in the examples below. Also, note that different MIDP implementations may render the Lists differently. When a List is being displayed, the user can interact with it, for instance, by traversing from element to element. The traversal may cause the List to be scrolled. These traversing and scrolling operations are handled by the system and do not generate any events that are visible to the MIDP application. The system notifies the application only when a Command is fired. The notification to the application is carried out via the CommandListener of the Screen. This means that the application operations associated with list elements are added to the List as ITEM or SCREEN type commands, depending upon whether the operation affects only the selected element or the entire list. In the List class there is also a notion of the select operation, which is central to the user's interaction with the List. The select operation is implemented differently from device to device. On devices that have a dedicated hardware key for selection operations, such as a "Select" or "Go" key, the select operation is invoked with that key. Devices that do not have a dedicated key must provide other means to perform the select operation; for example, using a labeled softkey. The behavior of the select operation within the three different types of lists is described in the following sections: Section 9.1.1, "Implicit List," Section 9.1.2, "Exclusive Choice List," and Section 9.1.3, "Multiple Choice List." Methods on List objects include insert, append and delete, and methods to get the String or the Image from any element. Elements can be added and removed from the List at any time. The selected elements in the List can be retrieved or changed. However, changing the List while the user is viewing it or trying to select an item is not recommended since it might cause confusion. The majority of the behavior for managing a List is common with class ChoiceGroup; the common API is defined in the interface class Choice. Elements in the List are manipulated with the methods append, delete, getImage, getString, insert, and set. Item selection is handled with methods getSelectedIndex, setSelectedIndex, getSelectedFlags, setSelectedFlags, and isSelected. Here is an example of List creation:
9.1.1 Implicit ListAn implicit List is used as a normal selection list. The List is presented as a menu from which the user can choose one of the elements. As with other List types, there can be one or more available operations provided as Commands. The operations that operate in the context of the selected element are provided as ITEM type Commands. In other words, List operations that affect or are related to the focused or highlighted element should have the type ITEM. The correct type allows MIDP devices to place the context-sensitive operations in the correct place in the user interface. The implicit List automatically selects the currently focused element when any Command is initiated. To be notified of the selection, the List must have a CommandListener set. The application can query the selection state of a List from CommandListener using the methods getSelectedIndex or isSelected. The select command can also be removed completely by passing null to the setSelectCommand method. There is a special usage scenario for this. There can be multiple ITEM commands on a List, but there can be only one select command. In some cases, none of the ITEM commands can be considered suitable for being a select command. If there is more than one ITEM command on a List, the select command can be considered as a default operation for the List. The following code sample illustrates how this can be accomplished. The code creates a list that presents the message headers of an e-mail messaging application. Two of the commands, openCommand and removeCommand, are related to the List elements, so they have type ITEM. The openCommand is considered to be a default operation, invoked when a select operation in the List is activated by the user. The following code initializes the List:
// Construct a list of message headers
List list = new List("Messages", Choice.IMPLICIT,
messageHeaders, messageStateIcons);
// The command handler is implemented in the same class
list.setCommandListener(this);
// Command for "opening" the selected message
Command openCommand = new Command("Open", Command.ITEM, 1);
// Command for "removing" the selected message
Command removeCommand = new Command("Remove", Command.ITEM, 2);
// Command for going "back"
Command backCommand = new Command("Back", Command.BACK, 3);
list.addCommand(openCommand);
list.addCommand(removeCommand);
list.addCommand(backCommand);
list.setSelectCommand(openCommand); // openCommand is the default
The following code defines the command handler of the List:
public void commandAction(Command cmd, Displayable d) {
int selectedIndex = ((List) d).getSelectedIndex();
if (cmd == openCommand) {
// Handle "open" command based on selectedIndex
} else if (cmd == removeCommand) {
// Handle "remove" command based on selectedIndex
} else if (cmd == backCommand) {
// Handle backward navigation
}
}
9.1.2 Exclusive Choice ListAn Exclusive List allows the user to select only a single element. This type of a List is commonly rendered to the screen as a group of radio buttons. When the user selects an element, any previously selected element is automatically deselected. Selecting an element does not notify the application. Notification to the List's CommandListener occurs when a Command on the List is chosen. When the listener is invoked, it can determine which element is selected with the List.getSelected method. An exclusive List must have Commands added to it, or the user will not be able to trigger any action and will be stuck on the screen. In the example below, the user is able to pick one element and then can select either the OK or BACK command.
9.1.3 Multiple Choice ListA Multiple Choice List allows the user to select zero or more elements. Each element can be selected or deselected individually. Typically, this kind of List is presented on the screen as a set of check boxes. Each element has an indicator displaying whether or not the element it is currently selected, and the user can toggle individual elements on or off. Toggling the selection of an element does not notify the application. Notification to the List's CommandListener occurs when a Command on the List is chosen. When the listener is invoked, it can determine which element(s) are selected with the List.getSelectedFlags or List.isSelected method. A multiple choice List must have Commands added to it, or the user will not be able to trigger any action and will be stuck on the screen. In this example, the user can individually select and deselect the choices "Red", "Green", and "Blue." When satisfied with the choices, the user can select either the OK or BACK command to exit the screen.
9.1.4 Long List Elements
If the TEXT_WRAP_ON request is honored, the text element contents are wrapped to multiple lines, if necessary, up to the available content space. Conversely, TEXT_WRAP_OFF causes the text element contents to be limited to a single line. Line ending is forced, usually by cropping, if there is too much text to fit in the line. 9.1.5 List Element FontsThere are two general usage scenarios for setting a font for a List that differs from the default. First, the element fonts with differing styles (such as plain, bold, or italic) might be used to highlight some implicit difference in elements. For example, in an e-mail client application, "unread" items might be presented using a bold font, and "read" items with plain font. Because the default font can itself be bold or plain, the application should, as a general rule, set all the element fonts, or else it should query the default font and create a variant font based on the properties of the default font. This also helps ensure that the font sizes of different elements remain consistent:
// Get the default font
Font defaultFont = list.getFont(0);
int defaultFontFace = defaultFont.getFace();
int defaultFontSize = defaultFont.getSize();
// Define a style that differs from the default font
int readFontStyle;
if (defaultFont.isBold()) {
// If default is itself bold, use bold and italic
readFontStyle = Font.STYLE_BOLD | Font.STYLE_ITALIC;
} else {
// Otherwise use simply bold
readFontStyle = Font.STYLE_BOLD;
}
// Get a new font with only the style differing from default font
Font readElementFont = Font.getFont(defaultFontFace, readFontStyle,
defaultFontSize);
// Set the readElementFont for "unread" elements
for (int i = 0 ; i < list.size() ; i++) {
// readState array contains boolean true if item is read
if (!readState[i]) {
list.setFont(i, readElementFont);
}
}
The second general use case is that the setFont method can be passed a font that differs in size from the default font. If this is done, the application should change the font of all elements to have the same size. If the List element font sizes differ from element to element, this could result in awkward-looking user interfaces. Some devices might limit the element sizes of Lists, so it might not be possible for the application to completely control the font sizes. For more a detailed description about Font properties and their proper values refer to Section 11.3.6, "Fonts."  |
List list = new List("Fruits",
Choice.IMPLICIT);
list.append("Apple", null);
list.append("Pear", null);
list.append("Orange", null);
list.append("Banana", null);
list.append("Pineapple", null);
list.append("Mandarin", null);
list.setCommandListener(this);
list.addCommand(backCommand);
List list =
new List("Border Style", Choice.EXCLUSIVE);
list.append("None", null);
list.append("Plain", null);
list.append("Fancy", null);
list.addCommand(backCommand);
list.addCommand(okCommand);
...
public void commandAction(Command cmd, Displayable d) {
List list = (List) d;
if (cmd == okCommand) {
int i = list.getSelectedIndex();
// Use the index of the selected list element...
} else if (cmd == backCommand) {
// Handle the back command
}
}
List list = new List("Colors to mix",
Choice.MULTIPLE);
list.append("Red", null);
list.append("Green", null);
list.append("Blue", null);
list.addCommand(backCommand);
list.addCommand(okCommand);
...
public void commandAction(Command cmd,
Displayable d) {
if (cmd == okCommand) {
List list = (List) d;
for (int i = 0; i < list.size(); i++) {
boolean selected = list.isSelected(i);
// If selected, take action...
}
}
}
| [ directory ] |
|