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

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

Field Summary

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

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

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.