de.enough.polish.ui
Class List

java.lang.Object
  javax.microedition.lcdui.Displayable
      javax.microedition.lcdui.Canvas
          de.enough.polish.ui.Screen
              de.enough.polish.ui.List

All Implemented Interfaces:

AccessibleCanvas, Choice

Direct Known Subclasses:

FilteredList

public class List
extends Screen
implements Choice

A Screen containing list of choices. The dynamic CSS selector is "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.

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 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.

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.

Since:

MIDP 1.0

Field Summary

protected ChoiceGroup	choiceGroup
protected int	listType
static javax.microedition.lcdui.Command	SELECT_COMMAND The default select command for IMPLICIT Lists.

Fields inherited from class de.enough.polish.ui.Screen

background, border, container, contentHeight, contentWidth, contentX, contentY, cssSelector, fullScreenHeight, ignoreRepaintRequests, infoHeight, isInitRequested, isRepaintRequested, isScrollBackground, isSetFullScreenCalled, itemStateListener, keyPressedProcessed, keyReleasedProcessed, lastInteractionTime, lastTriggeredCommand, menuBarHeight, originalScreenHeight, paintScrollBarOnRightSide, screenHeight, screenOrientationDegrees, screenStateListener, screenWidth, scrollBar, scrollBarVisible, style, subTitleHeight, title, titleHeight, triggerReleasedKeyCode, triggerReleasedTime

Fields inherited from class javax.microedition.lcdui.Canvas

DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP

Fields inherited from interface de.enough.polish.ui.Choice

EXCLUSIVE, IMPLICIT, MULTIPLE, POPUP, TEXT_WRAP_DEFAULT, TEXT_WRAP_OFF, TEXT_WRAP_ON

Constructor Summary

List(java.lang.String title, int listType)
Creates a new, empty List, specifying its title and the type of the list.

List(java.lang.String title, int listType, ChoiceItem[] items)
Creates a new List, specifying its title, the type the type of the List, and an array of ChoiceItems to be used as its initial contents.

List(java.lang.String title, int listType, ChoiceItem[] items, Style style)
Creates a new List, specifying its title, the type the type of the List, and an array of ChoiceItems to be used as its initial contents.

List(java.lang.String title, int listType, java.lang.String[] stringElements, javax.microedition.lcdui.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.

List(java.lang.String title, int listType, java.lang.String[] stringElements, javax.microedition.lcdui.Image[] imageElements, Style style)
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.

List(java.lang.String title, int listType, Style style)
Creates a new, empty List, specifying its title and the type of the list.

Method Summary

int	append(ChoiceItem item) Appends a ChoiceItem to the List.
int	append(java.lang.String stringPart, javax.microedition.lcdui.Image imagePart) Appends an element to the List.
int	append(java.lang.String stringPart, javax.microedition.lcdui.Image imagePart, Style elementStyle) Appends an element to the List.
protected java.lang.String	createCssSelector() Retrieves the CSS selector for this screen.
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.
javax.microedition.lcdui.Font	getFont(int elementNum) Gets the application's preferred font for rendering the specified element of this Choice.
javax.microedition.lcdui.Image	getImage(int elementNum) Gets the Image part of the element referenced by elementNum.
ChoiceItem	getItem(int elementNum) Gets the ChoiceItem 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.
java.lang.String	getString(int elementNum) Gets the String part of the element referenced by elementNum.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
void	insert(int elementNum, ChoiceItem item) Inserts an element into the List just prior to the element specified.
void	insert(int elementNum, java.lang.String stringPart, javax.microedition.lcdui.Image imagePart) Inserts an element into the List just prior to the element specified.
void	insert(int elementNum, java.lang.String stringPart, javax.microedition.lcdui.Image imagePart, Style elementStyle) 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(javax.microedition.lcdui.Command cmd) The same as Displayable.removeCommand but with the following additional semantics.
void	set(int elementNum, ChoiceItem item) Sets the ChoiceItem of the element referenced by elementNum, replacing the previous one.
void	set(int elementNum, java.lang.String stringPart, javax.microedition.lcdui.Image imagePart) Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.
void	set(int elementNum, java.lang.String stringPart, javax.microedition.lcdui.Image imagePart, Style elementStyle) 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, javax.microedition.lcdui.Font font) Sets the application's preferred font for rendering the specified element of this Choice.
void	setSelectCommand(javax.microedition.lcdui.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	setStyle(Style style) Sets the style of this screen.
int	size() Gets the number of elements in the List.

Methods inherited from class de.enough.polish.ui.Screen

addCommand, addCommand, addSubCommand, addSubCommand, animate, animate, calculateContentArea, callCommandListener, checkForRequestInit, closeMenu, commandAction, focus, focus, focus, focus, focus, getAvailableHeight, getCommandItem, getCommandListener, getCurrentIndex, getCurrentItem, getGameAction, getItemAt, getMenuBar, getPolishTicker, getRootItems, getScreenContentHeight, getScreenContentWidth, getScreenData, getScreenFullHeight, getScreenFullWidth, getScreenHeight, getScreenStyle, getScrollBarWidth, getScrollYOffset, getTitle, handleCommand, handleKeyReleased, handleKeyRepeated, handlePointerPressed, handlePointerReleased, hideNotify, isGameActionFire, isKeyboardAccessible, isMenuOpened, isShown, isSoftKey, isSoftKey, isSoftKeyLeft, isSoftKeyMiddle, isSoftKeyRight, keyPressed, keyReleased, keyRepeated, notifyScreenStateChanged, notifyStateListener, paint, paintScreen, pointerDragged, pointerPressed, pointerReleased, releaseResources, removeAllCommands, removeItemCommands, requestInit, requestRepaint, requestRepaint, scrollRelative, setCommandListener, setFullScreenMode, setInfo, setItemCommands, setItemStateListener, setItemStateListener, setMenuBarStyle, setMenuItemStyle, setPolishTicker, setPolishTicker, setScreenData, setScreenOrientation, setScreenStateListener, setScrollYOffset, setSubTitle, setTitle, setTitle, setTitle, showNotify, sizeChanged

Methods inherited from class javax.microedition.lcdui.Canvas

getKeyCode, getKeyName, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, isDoubleBuffered, repaint, repaint, serviceRepaints

Methods inherited from class javax.microedition.lcdui.Displayable

getHeight, getTicker, getWidth, setTicker

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SELECT_COMMAND

public static javax.microedition.lcdui.Command SELECT_COMMAND

The default select command for 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.

listType

protected int listType

choiceGroup

protected ChoiceGroup choiceGroup

Constructor Detail

List

public List(java.lang.String title,
            int listType)

Creates a new, empty List, specifying its title and the type of the list.

Parameters:

title - the screen's title (see Displayable)

listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLE

Throws:

java.lang.IllegalArgumentException - if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice

List

public List(java.lang.String title,
            int listType,
            Style style)

Creates a new, empty List, specifying its title and the type of the list.

Parameters:

title - the screen's title (see Displayable)

listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLE

style - the style of this list

Throws:

java.lang.IllegalArgumentException - if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice

List

public List(java.lang.String title,
            int listType,
            java.lang.String[] stringElements,
            javax.microedition.lcdui.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.

Parameters:

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 elements

imageElements - set of images specifying the image parts of the List elements

Throws:

java.lang.NullPointerException - if stringElements is null or if the stringElements array contains any null elements

java.lang.IllegalArgumentException - if the imageElements array is non-null and has a different length from the stringElements array or if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

List

public List(java.lang.String title,
            int listType,
            java.lang.String[] stringElements,
            javax.microedition.lcdui.Image[] imageElements,
            Style style)

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.

Parameters:

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 elements

imageElements - set of images specifying the image parts of the List elements

style - the style of this list

Throws:

java.lang.NullPointerException - if stringElements is null or if the stringElements array contains any null elements

java.lang.IllegalArgumentException - if the imageElements array is non-null and has a different length from the stringElements array or if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

List

public List(java.lang.String title,
            int listType,
            ChoiceItem[] items)

Creates a new List, specifying its title, the type the type of the List, and an array of ChoiceItems to be used as its initial contents.

The itemss array must be non-null and every ChoiceItem must have its text be a non-null String. The length of the items array determines the number of elements in the ChoiceGroup.

Parameters:

title - the screen's title (see Displayable)

listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLE

items - set of ChoiceItems specifying the ChoiceGroup elements

Throws:

java.lang.NullPointerException - if items is null or if getText() for one of the ChoiceItem in the array retuns a null String.

java.lang.IllegalArgumentException - if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

List

public List(java.lang.String title,
            int listType,
            ChoiceItem[] items,
            Style style)

Creates a new List, specifying its title, the type the type of the List, and an array of ChoiceItems to be used as its initial contents.

The itemss array must be non-null and every ChoiceItem must have its text be a non-null String. The length of the items array determines the number of elements in the ChoiceGroup.

Parameters:

title - the screen's title (see Displayable)

listType - one of IMPLICIT, EXCLUSIVE, or MULTIPLE

items - set of ChoiceItems specifying the ChoiceGroup elements

style - the style of this list

Throws:

java.lang.NullPointerException - if items is null or if getText() for one of the ChoiceItem in the array retuns a null String.

java.lang.IllegalArgumentException - if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

Method Detail

size

public int size()

Gets the number of elements in the List.

Specified by:

size in interface Choice

Returns:

the number of elements in the List

See Also:

in interface Choice

getString

public java.lang.String getString(int elementNum)

Gets the String part of the element referenced by elementNum.

Specified by:

getString in interface Choice

Parameters:

elementNum - - the index of the element to be queried

Returns:

the string part of the element

Throws:

java.lang.IndexOutOfBoundsException - - if elementNum is invalid

See Also:

in interface Choice, getImage(int)

getImage

public javax.microedition.lcdui.Image getImage(int elementNum)

Gets the Image part of the element referenced by elementNum.

Specified by:

getImage in interface Choice

Parameters:

elementNum - the number of the element to be queried

Returns:

the image part of the element, or null if there is no image

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

See Also:

in interface Choice, getString(int)

getItem

public ChoiceItem getItem(int elementNum)

Gets the ChoiceItem of the element referenced by elementNum.

Parameters:

elementNum - the number of the element to be queried

Returns:

the ChoiceItem of the element

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

append

public int append(java.lang.String stringPart,
                  javax.microedition.lcdui.Image imagePart)

Appends an element to the List.

Specified by:

append in interface Choice

Parameters:

stringPart - the string part of the element to be added

imagePart - the image part of the element to be added, or null if there is no image part

Returns:

the assigned index of the element

Throws:

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

append

public int append(java.lang.String stringPart,
                  javax.microedition.lcdui.Image imagePart,
                  Style elementStyle)

Appends an element to the List.

Parameters:

stringPart - the string part of the element to be added

imagePart - the image part of the element to be added, or null if there is no image part

elementStyle - the style for the new list element.

Returns:

the assigned index of the element

Throws:

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

append

public int append(ChoiceItem item)

Appends a ChoiceItem to the List.

Parameters:

item - ChoiceItem to be added

Returns:

the assigned index of the element

insert

public void insert(int elementNum,
                   java.lang.String stringPart,
                   javax.microedition.lcdui.Image imagePart)

Inserts an element into the List just prior to the element specified.

Specified by:

insert in interface Choice

Parameters:

elementNum - the index of the element where insertion is to occur

stringPart - the string part of the element to be inserted

imagePart - the image part of the element to be inserted, or null if there is no image part

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

insert

public void insert(int elementNum,
                   java.lang.String stringPart,
                   javax.microedition.lcdui.Image imagePart,
                   Style elementStyle)

Inserts an element into the List just prior to the element specified.

Parameters:

elementNum - the index of the element where insertion is to occur

stringPart - the string part of the element to be inserted

imagePart - the image part of the element to be inserted, or null if there is no image part

elementStyle - the style for the new list element.

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

insert

public void insert(int elementNum,
                   ChoiceItem item)

Inserts an element into the List just prior to the element specified.

Parameters:

elementNum - the index of the element where insertion is to occur

item - ChoiceItem of the element to be inserted

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

set

public void set(int elementNum,
                java.lang.String stringPart,
                javax.microedition.lcdui.Image imagePart)

Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.

Specified by:

set in interface Choice

Parameters:

elementNum - the index of the element to be set

stringPart - the string part of the new element

imagePart - the image part of the element, or null if there is no image part

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

set

public void set(int elementNum,
                java.lang.String stringPart,
                javax.microedition.lcdui.Image imagePart,
                Style elementStyle)

Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.

Parameters:

elementNum - the index of the element to be set

stringPart - the string part of the new element

imagePart - the image part of the element, or null if there is no image part

elementStyle - the style for the new list element.

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

java.lang.NullPointerException - if stringPart is null

See Also:

in interface Choice

set

public void set(int elementNum,
                ChoiceItem item)

Sets the ChoiceItem of the element referenced by elementNum, replacing the previous one.

Parameters:

elementNum - the index of the element to be set

item - ChoiceItem of the new element

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

delete

public void delete(int elementNum)

Deletes the element referenced by elementNum.

Specified by:

delete in interface Choice

Parameters:

elementNum - the index of the element to be deleted

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

See Also:

in interface Choice

deleteAll

public void deleteAll()

Deletes all elements from this List.

Specified by:

deleteAll in interface Choice

See Also:

in interface Choice

isSelected

public boolean isSelected(int elementNum)

Gets a boolean value indicating whether this element is selected.

Specified by:

isSelected in interface Choice

Parameters:

elementNum - index to element to be queried

Returns:

selection state of the element

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

See Also:

in interface Choice

getSelectedIndex

public int getSelectedIndex()

Returns the index number of an element in the List that is selected.

Specified by:

getSelectedIndex in interface Choice

Returns:

index of selected element, or -1 if none is selected

See Also:

in interface Choice, setSelectedIndex(int, boolean)

getSelectedFlags

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.

Specified by:

getSelectedFlags in interface Choice

Parameters:

selectedArray_return - array to contain the results

Returns:

the number of selected elements in the Choice

Throws:

java.lang.IllegalArgumentException - if selectedArray_return is shorter than the size of the List

java.lang.NullPointerException - if selectedArray_return is null

See Also:

in interface Choice, setSelectedFlags(boolean[])

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)

Sets the selected state of an element.

Specified by:

setSelectedIndex in interface Choice

Parameters:

elementNum - the index of the element, starting from zero

selected - the state of the element, where true means selected and false means not selected

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

See Also:

in interface Choice, getSelectedIndex()

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)

Sets the selected state of all elements of the List.

Specified by:

setSelectedFlags in interface Choice

Parameters:

selectedArray - an array in which the method collect the selection status

Throws:

java.lang.IllegalArgumentException - if selectedArray is shorter than the size of the List

java.lang.NullPointerException - if selectedArray is null

See Also:

in interface Choice, getSelectedFlags(boolean[])

removeCommand

public void removeCommand(javax.microedition.lcdui.Command cmd)

The same as 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);     

Overrides:

removeCommand in class Screen

Parameters:

cmd - - the command to be removed

Since:

MIDP 2.0

See Also:

Displayable.removeCommand(javax.microedition.lcdui.Command)

setSelectCommand

public void setSelectCommand(javax.microedition.lcdui.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.

Parameters:

command - the command to be used for an IMPLICIT list selection action, or null if there is none

Since:

MIDP 2.0

setFitPolicy

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 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.

Specified by:

setFitPolicy in interface Choice

Parameters:

fitPolicy - preferred content fit policy for choice elements

Throws:

java.lang.IllegalArgumentException - if fitPolicy is invalid

Since:

MIDP 2.0

See Also:

in interface Choice, getFitPolicy()

getFitPolicy

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.

Specified by:

getFitPolicy in interface Choice

Returns:

one of Choice.TEXT_WRAP_DEFAULT, Choice.TEXT_WRAP_ON, or Choice.TEXT_WRAP_OFF

Since:

MIDP 2.0

See Also:

in interface Choice, setFitPolicy(int)

setFont

public void setFont(int elementNum,
                    javax.microedition.lcdui.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.

Specified by:

setFont in interface Choice

Parameters:

elementNum - the index of the element, starting from zero

font - the preferred font to use to render the element

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

Since:

MIDP 2.0

See Also:

in interface Choice, getFont(int)

getFont

public javax.microedition.lcdui.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.

Specified by:

getFont in interface Choice

Parameters:

elementNum - the index of the element, starting from zero

Returns:

the preferred font to use to render the element

Throws:

java.lang.IndexOutOfBoundsException - if elementNum is invalid

Since:

MIDP 2.0

See Also:

in interface Choice, setFont(int elementNum, Font font)

createCssSelector

protected java.lang.String createCssSelector()

Description copied from class: Screen

Retrieves the CSS selector for this screen. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the screen and not by a predefined style-name. With the #style preprocessing command styles are set in a static way, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "form>p", than the selector of the screen is needed. This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles

Specified by:

createCssSelector in class Screen

Returns:

the name of the appropriate CSS Selector for this screen.

setStyle

public void setStyle(Style style)

Description copied from class: Screen

Sets the style of this screen.

Overrides:

setStyle in class Screen

Parameters:

style - the style

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: Screen

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed.

Overrides:

handleKeyPressed in class Screen

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key-event was processed