MID Profile

javax.microedition.lcdui
Class ChoiceGroup

java.lang.Object
  |
  +--javax.microedition.lcdui.Item
        |
        +--javax.microedition.lcdui.ChoiceGroup
All Implemented Interfaces:
Choice

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 specified in the Choice interface.

Since:
MIDP 1.0

Fields inherited from class javax.microedition.lcdui.Item
BUTTON, HYPERLINK, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, PLAIN
 
Fields inherited from interface javax.microedition.lcdui.Choice
EXCLUSIVE, IMPLICIT, MULTIPLE, POPUP, TEXT_WRAP_DEFAULT, TEXT_WRAP_OFF, TEXT_WRAP_ON
 
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, the type of the ChoiceGroup, 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 ChoiceGroup.
 void delete(int elementNum)
          Deletes the element referenced by elementNum.
 void deleteAll()
          Deletes all elements from this ChoiceGroup.
 int getFitPolicy()
          Gets the application's preferred policy for fitting Choice element contents to the available screen space.
 Font getFont(int elementNum)
          Gets the application's preferred font for rendering the specified element of this Choice.
 Image getImage(int elementNum)
          Gets the Image part of the element referenced by elementNum.
 int getSelectedFlags(boolean[] selectedArray_return)
          Queries the state of a ChoiceGroup and returns the state of all elements in the boolean array selectedArray_return.
 int getSelectedIndex()
          Returns the index number of an element in the ChoiceGroup 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 ChoiceGroup just prior to 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 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, Font font)
          Sets the application's preferred font for rendering the specified element of this Choice.
 void setSelectedFlags(boolean[] selectedArray)
          Attempts to set the selected state of every element in the ChoiceGroup.
 void setSelectedIndex(int elementNum, boolean selected)
          For ChoiceGroup objects of type MULTIPLE, this simply sets an individual element's selected state.
 int size()
          Returns the number of elements in the ChoiceGroup.
 
Methods inherited from class javax.microedition.lcdui.Item
addCommand, getLabel, getLayout, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, notifyStateChanged, removeCommand, setDefaultCommand, setItemCommandListener, setLabel, setLayout, setPreferredSize
 
Methods inherited from class java.lang.Object
equals, 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, MULTIPLE, or POPUP. The IMPLICIT choice type is not allowed within a ChoiceGroup.
Parameters:
label - the item's label (see Item)
choiceType - EXCLUSIVE, MULTIPLE, or POPUP
Throws:
IllegalArgumentException - if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP
See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

ChoiceGroup

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

The type must be one of EXCLUSIVE, MULTIPLE, or POPUP. The IMPLICIT 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. Non-null elements of the imageElements array may refer to mutable or immutable images.

Parameters:
label - the item's label (see Item)
choiceType - EXCLUSIVE, MULTIPLE, or POPUP
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 choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP
See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP
Method Detail

size

public int size()
Returns the number of elements in the ChoiceGroup.
Specified by:
size in interface Choice
Returns:
the number of elements in the ChoiceGroup

getString

public 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:
IndexOutOfBoundsException - if elementNum is invalid
See Also:
getImage(int)

getImage

public 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:
IndexOutOfBoundsException - if elementNum is invalid
See Also:
getString(int)

append

public int append(String stringPart,
                  Image imagePart)
Appends an element to the ChoiceGroup.
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:
NullPointerException - if stringPart is null

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)
Inserts an element into the ChoiceGroup 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:
IndexOutOfBoundsException - if elementNum is invalid
NullPointerException - if stringPart is null

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:
IndexOutOfBoundsException - if elementNum is invalid

deleteAll

public void deleteAll()
Deletes all elements from this ChoiceGroup.
Specified by:
deleteAll in interface Choice

set

public void set(int elementNum,
                String stringPart,
                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:
IndexOutOfBoundsException - if elementNum is invalid
NullPointerException - if stringPart is null

isSelected

public boolean isSelected(int elementNum)
Gets a boolean value indicating whether this element is selected.
Specified by:
isSelected in interface Choice
Parameters:
elementNum - the index of the element to be queried
Returns:
selection state of the element
Throws:
IndexOutOfBoundsException - if elementNum is invalid

getSelectedIndex

public int getSelectedIndex()
Returns the index number of an element in the ChoiceGroup that is selected. For ChoiceGroup objects of type EXCLUSIVE and POPUP 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 ChoiceGroup.

For ChoiceGroup objects of type MULTIPLE, this always returns -1 because no single value can in general represent the state of such a ChoiceGroup. To get the complete state of a MULTIPLE Choice, see getSelectedFlags.

Specified by:
getSelectedIndex in interface Choice
Returns:
index of selected element, or -1 if none
See Also:
setSelectedIndex(int, boolean)

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)
Queries the state of a ChoiceGroup 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 ChoiceGroup as returned by size(). If the array is longer, the extra elements are set to false.

For ChoiceGroup objects of type MULTIPLE, any number of elements may be selected and set to true in the result array. For ChoiceGroup objects of type EXCLUSIVE and POPUP exactly one element will be selected, unless there are zero elements in the ChoiceGroup.

Specified by:
getSelectedFlags in interface Choice
Parameters:
selectedArray_return - array to contain the results
Returns:
the number of selected elements in the ChoiceGroup
Throws:
IllegalArgumentException - if selectedArray_return is shorter than the size of the ChoiceGroup
NullPointerException - if selectedArray_return is null
See Also:
setSelectedFlags(boolean[])

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)
For ChoiceGroup objects of type MULTIPLE, this simply sets an individual element's selected state.

For ChoiceGroup objects of type EXCLUSIVE and POPUP, 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 both list types, the elementNum parameter must be within the range [0..size()-1], inclusive.

Specified by:
setSelectedIndex in interface Choice
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:
IndexOutOfBoundsException - if elementNum is invalid
See Also:
getSelectedIndex()

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)
Attempts to set the selected state of every element in the ChoiceGroup. The array must be at least as long as the size of the ChoiceGroup. If the array is longer, the additional values are ignored.

For ChoiceGroup objects of type MULTIPLE, this sets the selected state of every element in the Choice. An arbitrary number of elements may be selected.

For ChoiceGroup objects of type EXCLUSIVE and POPUP, 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
Parameters:
selectedArray - an array in which the method collect the selection status
Throws:
IllegalArgumentException - if selectedArray is shorter than the size of the ChoiceGroup
NullPointerException - if the selectedArray is null
See Also:
getSelectedFlags(boolean[])

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:
IllegalArgumentException - if fitPolicy is invalid
Since:
MIDP 2.0
See Also:
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:
setFitPolicy(int)

setFont

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.

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:
IndexOutOfBoundsException - if elementNum is invalid
Since:
MIDP 2.0
See Also:
getFont(int)

getFont

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.

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:
IndexOutOfBoundsException - if elementNum is invalid
Since:
MIDP 2.0
See Also:
setFont(int elementNum, Font font)

MID Profile

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