MID Profile

javax.microedition.lcdui
Interface Choice

All Known Implementing Classes:
List, ChoiceGroup

public interface Choice

Choice defines an API for a user interface components implementing selection from predefined number of choices. Such UI components are List and ChoiceGroup. The contents of the Choice are represented with strings and optional images.

Each element of a Choice is composed of a static text string and an optional image. The application may provide null for the image if the element does not have an image part. If the application provides an image, the implementation may choose to ignore the image if it exceeds the capacity of the device to display it. If the implementation displays the image, it will be displayed adjacent to the text string and the pair will be treated as a unit.

If an element is too long to be displayed on one line it wraps onto multiple lines to fit the width of the display. When an element wraps to multiple lines, the second and subsequent lines show a clear indication to the user that they are part of the same element and are not a new element. For example, the second and subsequent lines may be shown indented.

There are three types of Choices: implicit-choice (valid only for List), exclusive-choice, and multiple-choice.

The exclusive-choice presents a series of elements and interacts with the user in object-action mode. That is, when the user selects an element, that element is shown to be selected using a distinct visual representation. Exactly one element must be selected at any given time. If at any time a situation would result where there are elements in the exclusive-choice but none is selected, the implementation will choose an element and select it. This situation can arise when an element is added to an empty Choice, or when the selected element is deleted from the Choice. There is no way for the user to unselect an element within an Exclusive Choice.

The implicit choice is an exclusive choice where the focused element is implicitly selected when a command is initiated.

A multiple-choice presents a series of elements and allows the user to select any number of elements in any combination. As with exclusive-choice, the multiple-choice interacts with the user in object-operation mode. The visual appearance of a multiple-choice will likely have a visual representation distinct from the exclusive-choice that shows the selected state of each element as well as indicating to the user that multiple elements may be selected.

When a Choice 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 either when some application-defined Command is fired, or when selection state of ChoiceGroup is changed. When command is fired a high-level event is delivered to the listener of the Screen. The event delivery is done with commandAction . In the case of ChoiceGroup the ItemStateListener is called when the user changes the selection state of the ChoiceGroup. At this time the application can query the Choice for information about the currently selected element(s).

The implementation may have keyboard shortcuts for focusing and selecting the choice elements, but the use of these shortcuts is not visible to the application program.


Field Summary
static int EXCLUSIVE
          EXCLUSIVE is a choice having exactly one element selected at time.
static int IMPLICIT
          IMLICIT is a choice in which the currently focused item is selected when a Command is initiated.
static int MULTIPLE
          MULTIPLE is a choice that can have arbitrary number of elements selected at a time.
 
Method Summary
 int appendElement(String stringPart, Image imagePart)
          Appends an element to the Choice.
 void deleteElement(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.
 int getSize()
          Gets the number of elements present in the Choice.
 String getString(int elementNum)
          Gets the String part of the element referenced by elementNum.
 void insertElement(int elementNum, String stringPart, Image imagePart)
          Inserts an element into the Choice just before to the element specified.
 boolean isSelected(int elementNum)
          Gets a boolean value indicating whether this element is selected.
 void setElement(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.
 

Field Detail

EXCLUSIVE

public static final int EXCLUSIVE
EXCLUSIVE is a choice having exactly one element selected at time.

Value 1 is assigned to EXCLUSIVE.


MULTIPLE

public static final int MULTIPLE
MULTIPLE is a choice that can have arbitrary number of elements selected at a time.

Value 2 is assigned to MULTIPLE.


IMPLICIT

public static final int IMPLICIT
IMLICIT is a choice in which the currently focused item is selected when a Command is initiated. (Note: IMPLICIT is not accepted by ChoiceGroup)

Value 3 is assigned to IMPLICIT.

Method Detail

getSize

public int getSize()
Gets the number of elements present in the Choice.
Returns:
number of elements in the Choice.

getString

public String getString(int elementNum)
Gets the String part of the element referenced by elementNum. Elements are numbered starting at zero.
Parameters:
elementNum - the number of the element
Returns:
the string part of the element
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
See Also:
getImage(int)

getImage

public Image getImage(int elementNum)
Gets the Image part of the element referenced by elementNum. Elements are numbered starting at zero.
Parameters:
elementNum - the number of the element
Returns:
the image part of the element, or null if there is no image
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
See Also:
getString(int)

appendElement

public int appendElement(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.

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 number of the element
Throws:
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

insertElement

public void insertElement(int elementNum,
                          String stringPart,
                          Image imagePart)
Inserts an element into the Choice just before to the element specified. Elements are numbered starting at zero. The size of the Choice grows by one.

Parameters:
elementNum - the number of the element
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:
ArrayIndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

deleteElement

public void deleteElement(int elementNum)
Deletes the element referenced by elementNum. Elements are numbered starting at zero. The size of the Choice shrinks by one. It is legal to delete all elements from a Choice.
Parameters:
elementNum - the number of the element to be deleted
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid

setElement

public void setElement(int elementNum,
                       String stringPart,
                       Image imagePart)
Sets the element referenced by elementNum to the specified element, replacing the previous contents of the element. Elements are numbered starting at zero.
Parameters:
elementNum - the number of the element
stringPart - the string part of the new element
imagePart - the image part of the element, or null if there is no image part
Throws:
ArrayIndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

isSelected

public boolean isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected.
Parameters:
elementNum - index to element of interest
Returns:
selection status of an element
Throws:
ArrayIndexOutOfBoundsException - if elementNum specifies an invalid element.

getSelectedIndex

public 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 there are no elements in the Choice or no element has been selected.

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.

Returns:
index of selected element

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

Parameters:
selectedArray_return - array to contain the results. It must be at least as long as the size of the Choice as returned by getSize(). If the array is longer, the extra elements are set to false.
Returns:
the number of selected elements in the Choice
Throws:
IllegalArgumentException - if selectedArray_return is shorter than the size of the Choice.

setSelectedIndex

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.

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. The call to setSelectedIndex does not cause implicit activation of any Command.

Parameters:
elementNum - the number of the element. Indexing of the elements is zero-based.
selected - the new state of the element true=selected, false=not selected.
Throws:
ArrayIndexOutOfBoundsException - if elementNum specifies an invalid element.

setSelectedFlags

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

Parameters:
selectedArray - an array in which the method collect the selection status
Throws:
IllegalArgumentException - if selectedArray is shorter than the size of the Choice.

MID Profile

Submit a comment or suggestion Version 0.9 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.