MID Profile

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

When a ChoiceGroup 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 user does the select operation of some application defined Command is fired. When this occurs a high-level event is delivered to the List's listener. The event delivery is done with commandAction . Also ItemStateListener is called when the user changes the selection state of the ChoiceGroup. At this time the application can query the ChoiceGroup 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.


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 arrays of Strings and Images to be used as its initial contents.
 
Method Summary
 int appendElement(String stringPart, Image imagePart)
          Implementation of appendElement of interface Choice.
 void deleteElement(int elementNum)
          Implementation of deleteElement of interface Choice.
 Image getImage(int elementNum)
          Implementation of getImage of interface Choice.
 int getSelectedFlags(boolean[] selectedArray_return)
          Implementation of getSelectedFlags of interface Choice.
 int getSelectedIndex()
          Implementation of getSelectedIndex of interface Choice.
 int getSize()
          Implementation of getString of interface Choice.
 String getString(int elementNum)
          Implementation of getString of interface Choice.
 void insertElement(int elementNum, String stringElement, Image imageElement)
          Implementation of insertElement of interface Choice.
 boolean isSelected(int elementNum)
          Implementation of isSelected of interface Choice.
 void setElement(int elementNum, String stringPart, Image imagePart)
          Implementation of setElement of interface Choice.
 void setSelectedFlags(boolean[] selectedArray)
          Implementation of setSelectedFlags of interface Choice.
 void setSelectedIndex(int elementNum, boolean selected)
          Implementation of getSelectedIndex of interface Choice.
 
Methods inherited from class javax.microedition.lcdui.Item
getLabel, setLabel
 
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 or MULTIPLE. The IMPLICIT choice type is not allowed within a ChoiceGroup.

Parameters:
label - the label {@see javax.microedition.lcdui.Item}
choiceType - either EXCLUSIVE or MULTIPLE
Throws:
IllegalArgumentException - if choice type is not EXCLUSIVE or MULTIPLE
See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   String[] stringElements,
                   Image[] imageElements)
Creates a new ChoiceGroup, specifying its title, its type, and arrays 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 within a ChoiceGroup.

Parameters:
label - the label {@see javax.microedition.lcdui.Item}
choiceType - either EXCLUSIVE or MULTIPLE
stringElements - set of strings specifying the visible representation of the elements. Empty String is marked with null and if no strings are given, whole list is empty (null).
imageElements - set of images specifying the visible representation of the elements. Empty image is marked with null and if no images are given, whole list is empty (null).
Throws:
IllegalArgumentException - if the length of stringElements is different from imageElements and imageElements is non-null.
IllegalArgumentException - if any of the images are mutable. I.e., created with createImage(width, height)
IllegalArgumentException - if choice type is not EXCLUSIVE or MULTIPLE
See Also:
Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT
Method Detail

getSize

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

getString

public String getString(int elementNum)
Implementation of getString of interface Choice.
Specified by:
getString in interface Choice
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)
Implementation of getImage of interface Choice.
Specified by:
getImage in interface Choice
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)
Implementation of appendElement of interface Choice.
Specified by:
appendElement 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 number of the element
Throws:
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

insertElement

public void insertElement(int elementNum,
                          String stringElement,
                          Image imageElement)
Implementation of insertElement of interface Choice.
Specified by:
insertElement in 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:
ArrayIndexOutOfBoundsException - if elementNum is invalid
IllegalArgumentException - if the image is mutable
NullPointerException - if stringPart is null

deleteElement

public void deleteElement(int elementNum)
Implementation of deleteElement of interface Choice.
Specified by:
deleteElement in interface 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)
Implementation of setElement of interface Choice.
Specified by:
setElement in interface Choice
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)
Implementation of isSelected of interface Choice.
Specified by:
isSelected in interface Choice
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()
Implementation of getSelectedIndex of interface Choice.
Specified by:
getSelectedIndex in interface Choice
Returns:
index of selected element

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)
Implementation of getSelectedFlags of interface Choice.
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.

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)
Implementation of getSelectedIndex of interface Choice.
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:
ArrayIndexOutOfBoundsException - if elementNum specifies an invalid element.

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)
Implementation of setSelectedFlags of interface Choice.
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.

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.