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

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

void	addCommand(Command cmd) Adds a context sensitive Command to the item.
int	append(String stringPart, Image imagePart) Appends an element to the Choice.
void	delete(int elementNum) Deletes the element referenced by elementNum.
void	deleteAll() Deletes all elements from this Choice, leaving it with zero elements.
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 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 prior to the element specified.
boolean	isSelected(int elementNum) Gets a boolean value indicating whether this element is selected.
void	notifyStateChanged() Called when the state of this item changes
void	removeCommand(Command cmd) Removes the context sensitive command from item.
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	setDefaultCommand(Command cmd) Sets default Command for this Item.
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	setItemCommandListener(ItemCommandListener l) Sets a listener for Commands to this Item, replacing any previous ItemCommandListener.
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, getLayout, getMinimumHeight, getMinimumWidth, getPreferredHeight, getPreferredWidth, 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

notifyStateChanged

public void notifyStateChanged()

Called when the state of this item changes

Overrides:

notifyStateChanged in class Item

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)

Description copied from interface: Choice

Inserts an element into the Choice just prior to the element specified. The size of the Choice grows by one. The elementNum parameter must be within the range [0..size()], inclusive. The index of the last element is size()-1, and so there is actually no element whose index is size(). If this value is used for elementNum, the new element is inserted immediately after the last element. In this case, the effect is identical to append().

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

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

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

deleteAll

public void deleteAll()

Deletes all elements from this Choice, leaving it with zero elements. This method does nothing if the Choice is already empty.

Specified by:

deleteAll in interface Choice

Since:

MIDP 2.0

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)

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)

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)

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 index of the element to be queried

Returns:

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

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, POPUP, and IMPLICIT exactly one element will be selected (unless there are zero elements in the Choice).

Specified by:

getSelectedFlags in interface Choice

Parameters:

selectedArray_return - array to contain the results

Returns:

the number of selected elements in the Choice

See Also:

Choice.setSelectedFlags(boolean[])

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, POPUP, and IMPLICIT there is at most one element selected, so this method is useful for determining the user's choice. Returns -1 if the Choice has no elements (and therefore has no selected elements).

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

Returns:

index of selected element, or -1 if none

See Also:

Choice.setSelectedIndex(int, boolean)

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

See Also:

Choice.getImage(int)

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

set

public void set(int elementNum,
                String stringPart,
                Image imagePart)

Description copied from interface: Choice

Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element. The elementNum parameter must be within the range [0..size()-1], inclusive. The font attribute of the element is left unchanged.

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

setFitPolicy

public void setFitPolicy(int fitPolicy)

Description copied from interface: Choice

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

See Also:

Choice.getFitPolicy()

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

Parameters:

selectedArray - an array in which the method collect the selection status

See Also:

Choice.getSelectedFlags(boolean[])

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 and POPUP, this can be used only to select any 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. If element was already selected, the call has no effect.

For IMPLICIT, this can be used only to select any 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. If element was already selected, the call has no effect.

The call to setSelectedIndex does not cause implicit activation of any Command.

For all list types, the elementNum parameter must be within the range [0..size()-1], inclusive.

Specified by:

setSelectedIndex in interface Choice

Parameters:

elementNum - the index of the element, starting from zero

selected - the state of the element, where true means selected and false means not selected

See Also:

Choice.getSelectedIndex()

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 Choice

addCommand

public void addCommand(Command cmd)

Description copied from class: Item

Adds a context sensitive Command to the item. The semantic type of Command should be ITEM. The implementation will present the command only when the the item is active, for example, highlighted.

If the added command is already in the item (tested by comparing the object references), the method has no effect. If the item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

addCommand in class Item

Parameters:

cmd - the command to be added

removeCommand

public void removeCommand(Command cmd)

Description copied from class: Item

Removes the context sensitive command from item. If the command is not in the Item (tested by comparing the object references), the method has no effect. If the Item is actually visible on the display, and this call affects the set of visible commands, the implementation should update the display as soon as it is feasible to do so. If the command to be removed happens to be the default command, the command is removed and the default command on this Item is set to null. The following code:

     // Command c is the default command on Item item
     item.removeCommand(c);
 

is equivalent to the following code:

     // Command c is the default command on Item item
     item.setDefaultCommand(null);
     item.removeCommand(c);
 

Overrides:

removeCommand in class Item

Parameters:

cmd - the command to be removed

setDefaultCommand

public void setDefaultCommand(Command cmd)

Description copied from class: Item

Sets default Command for this Item. If the Item previously had a default Command, that Command is no longer the default, but it remains present on the Item.

If not null, the Command object passed becomes the default Command for this Item. If the Command object passed is not currently present on this Item, it is added as if Item.addCommand(javax.microedition.lcdui.Command) had been called before it is made the default Command.

If null is passed, the Item is set to have no default Command. The previous default Command, if any, remains present on the Item.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setDefaultCommand in class Item

Parameters:

cmd - the command to be used as this Item's default Command, or null if there is to be no default command

setItemCommandListener

public void setItemCommandListener(ItemCommandListener l)

Description copied from class: Item

Sets a listener for Commands to this Item, replacing any previous ItemCommandListener. A null reference is allowed and has the effect of removing any existing listener.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setItemCommandListener in class Item

Parameters:

l - the new listener, or null.