javax.microedition.lcdui
Class ChoiceGroup

java.lang.Object
  |
  +--javax.microedition.lcdui.Item
        |
        +--javax.microedition.lcdui.ChoiceGroup

public class ChoiceGroup
extends Item
implements Choice

A ChoiceGroup is a group of selectable elements intended to be placed within a Form. The group may be created with a mode that requires a single choice to be made or that allows multiple choices. The implementation is responsible for providing the graphical representation of these modes and must provide visually different graphics for different modes. For example, it might use "radio buttons" for the single choice mode and "check boxes" for the multiple choice mode.

Note: most of the essential methods have been documented in the Choice interface.

Version:
MIDP 0.95 Public Draft

Fields inherited from interface javax.microedition.lcdui.Choice
EXCLUSIVE, IMPLICIT, MULTIPLE
 
Constructor Summary
ChoiceGroup(String label, int choiceType)
          Creates a new, empty ChoiceGroup, specifying its title and its type.
ChoiceGroup(String label, int choiceType, String[] stringElements, Image[] imageElements)
          Creates a new ChoiceGroup, specifying its title, its type, 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 before 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.Item
getLabel, setLabel
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType)
Creates a new, empty ChoiceGroup, specifying its title and its type. The type must be one of EXCLUSIVE or MULTIPLE. The IMPLICIT choice type is not allowed within a ChoiceGroup.
Parameters:
label - the item's label (see Item)
choiceType - either EXCLUSIVE or MULTIPLE

Throws:
IllegalArgumentException - if choice type is neither EXCLUSIVE nor MULTIPLE

See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   String[] stringElements,
                   Image[] imageElements)
Creates a new ChoiceGroup, specifying its title, its type, and an array of Strings and Images to be used as its initial contents.

The type must be one of EXCLUSIVE or MULTIPLE. The IMPLICIT choice type is not allowed for ChoiceGroup.

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 ChoiceGroup. The imageElements array may be null to indicate that the ChoiceGroup 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 ChoiceGroup element.

Parameters:
label - the item's label (see Item)
choiceType - EXCLUSIVE or MULTIPLE
stringElements - set of strings specifying the string parts of the ChoiceGroup elements
imageElements - set of images specifying the image parts of the ChoiceGroup elements

Throws:
NullPointerException - if stringElements is null
NullPointerException - if the stringElements array contains any null elements
IllegalArgumentException - if the imageElements array is non-null and has a different length from the stringElements array.
IllegalArgumentException - if choice type is not EXCLUSIVE or MULTIPLE

See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE
Method Detail

append

public int append(String stringPart,
                  Image imagePart)
Description copied from interface: Choice
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.
Specified by:
append in interface Choice
Tags copied from 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:
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

delete

public void delete(int elementNum)
Description copied from interface: Choice
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.
Specified by:
delete in interface Choice
Tags copied from interface: Choice
Parameters:
elementNum - the index of the element to be deleted

Throws:
IndexOutOfBoundsException - if elementNum is invalid

getImage

public Image getImage(int elementNum)
Description copied from interface: Choice
Gets the Image part of the element referenced by elementNum. The elementNum parameter must be within the range [0...size()-1] inclusive.
Specified by:
getImage in interface Choice
Tags copied from interface: Choice
Parameters:
elementNum - the number of the element

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

Throws:
IndexOutOfBoundsException - if elementNum is invalid

See Also:
Choice.getString(int)

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)
Description copied from interface: Choice
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).

Specified by:
getSelectedFlags in interface Choice
Tags copied from interface: Choice
Parameters:
selectedArray_return - array to contain the results

Returns:
the number of selected elements in the Choice

Throws:
IllegalArgumentException - if selectedArray_return is shorter than the size of the Choice.
NullPointerException - if selectedArray_return is null

getSelectedIndex

public int getSelectedIndex()
Description copied from interface: Choice
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.

Specified by:
getSelectedIndex in interface Choice
Tags copied from interface: Choice
Returns:
index of selected element, or -1 if none

getString

public String getString(int elementNum)
Description copied from interface: Choice
Gets the String part of the element referenced by elementNum. The elementNum parameter must be within the range [0...size()-1] inclusive.
Specified by:
getString in interface Choice
Tags copied from interface: Choice
Parameters:
elementNum - the index of the element to be queried

Returns:
the string part of the element

Throws:
IndexOutOfBoundsException - if elementNum is invalid

See Also:
Choice.getImage(int)

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)
Description copied from interface: Choice
Inserts an element into the Choice just before the element specified. The size of the Choice grows by one. The elementNum parameter must be within the range [0...size()-1] inclusive.

Specified by:
insert in interface Choice
Tags copied from interface: Choice
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:
IndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

isSelected

public boolean isSelected(int elementNum)
Description copied from interface: Choice
Gets a boolean value indicating whether this element is selected. The elementNum parameter must be within the range [0...size()-1] inclusive.
Specified by:
isSelected in interface Choice
Tags copied from interface: Choice
Parameters:
elementNum - the index of the element to be queried

Returns:
selection state of the element

Throws:
IndexOutOfBoundsException - if elementNum is invalid

set

public void set(int elementNum,
                String stringPart,
                Image imagePart)
Description copied from interface: Choice
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]
Specified by:
set in interface Choice
Tags copied from 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:
IndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)
Description copied from interface: Choice
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.

Specified by:
setSelectedFlags in interface Choice
Tags copied from interface: Choice
Parameters:
selectedArray - an array in which the method collects the selection status

Throws:
IllegalArgumentException - if selectedArray is shorter than the size of the Choice.
NullPointerException - if selectedArray is null

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)
Description copied from interface: Choice
For MULTIPLE, this simply sets an individual element's selected state.

For EXCLUSIVE, this can be used only to select an 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 an 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 a Command.

Specified by:
setSelectedIndex in interface Choice
Tags copied from interface: Choice
Parameters:
elementNum - the index of the element, starting from zero.
selected - the new state of the element, where true means selected, false means not selected.

Throws:
IndexOutOfBoundsException - if elementNum is invalid.

size

public int size()
Description copied from interface: Choice
Gets the number of elements present.
Specified by:
size in interface Choice
Tags copied from interface: Choice
Returns:
the number of elements in the Choice.