Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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, 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 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 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 stringElement, Image imageElement)` 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` | `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 ChoiceGroup.
`void` | `setSelectedIndex(int elementNum, boolean selected)` For ChoiceGroup objects of type 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, 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`, `Choice.IMPLICIT`

### 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 or MULTIPLE. 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.

  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 choiceType is neither EXCLUSIVE nor MULTIPLE
  See Also:
    `Choice.EXCLUSIVE`, `Choice.MULTIPLE`, `Choice.IMPLICIT`

Method Detail

### size

    public int size()

  Description copied from interface: Choice

  Gets the number of elements present.

  Specified by:
    size in interface Choice
  Returns:
    the number of elements in the ChoiceGroup

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

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

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

### insert

    public void insert(int elementNum,
                       String stringElement,
                       Image imageElement)

  Description copied from interface: Choice

  Inserts an element into the Choice just before to 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
  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
    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
  Parameters:
    `elementNum` - the index of the element to be deleted
  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], inclusive.

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

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

### 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, 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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a comment or suggestion Version 0.95 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.