de.enough.polish.ui
Class ChoiceGroup

java.lang.Object
  de.enough.polish.ui.Item
      de.enough.polish.ui.Container
          de.enough.polish.ui.ChoiceGroup

All Implemented Interfaces:

Animatable, Choice, ItemCommandListener, UiElement

public class ChoiceGroup
extends Container
implements Choice, ItemCommandListener

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

Author:

Robert Virkus, robert@enough.de

Field Summary

protected int	choiceType
static Command	MARK_COMMAND
static Command	UNMARK_COMMAND

Fields inherited from class de.enough.polish.ui.Container

allowCycling, autoFocusEnabled, autoFocusIndex, containerView, enableScrolling, focusAllStyle, focusedIndex, focusedItem, focusedStyleFirst, focusedStyleLast, isExpandItems, itemsList, itemStyle, lastPointerPressTime, lastPointerPressY, lastPointerPressYOffset, plainStyle, SCROLL_DEFAULT, SCROLL_SMOOTH, scrollHeight, scrollSmooth, targetYOffset, yOffset

Fields inherited from class de.enough.polish.ui.Item

_androidView, _bbField, appearanceMode, availableHeight, availableWidth, availContentHeight, availContentWidth, background, backgroundHeight, backgroundWidth, backgroundYOffset, bgBorder, border, BUTTON, cacheItemImage, colSpan, commands, completeBackground, completeBackgroundPadding, completeBorder, contentHeight, contentWidth, contentX, contentXAdjustment, contentY, contentYAdjustment, cssHeight, cssSelector, cssWidth, defaultCommand, focusedStyle, HORIZONTAL, HYPERLINK, ignoreRepaintRequests, includeLabel, INTERACTIVE, internalHeight, internalWidth, internalX, internalY, isContentVisible, isFocused, isInlineLabel, isInvisible, isJustFocused, isLayoutCenter, isLayoutExpand, isLayoutRight, isPressed, isShown, isStyleInitialized, itemCommandListener, itemHeight, itemWidth, label, labelStyle, landscapeStyle, layout, 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, marginBottom, marginLeft, marginRight, marginTop, maximumHeight, maximumItemHeight, maximumItemWidth, maximumWidth, minimumHeight, minimumItemHeight, minimumItemWidth, minimumWidth, nativeItem, NO_POSITION_SET, opacity, opacityPaintNormally, opacityRgbData, paddingBottom, paddingHorizontal, paddingLeft, paddingRight, paddingTop, paddingVertical, parent, PLAIN, portraitStyle, preferredHeight, preferredWidth, preserveViewType, relativeX, relativeY, rowSpan, screen, setView, style, TRANSPARENT, useSingleRow, VERTICAL, view, xAdjustment, yAdjustment

Fields inherited from interface de.enough.polish.ui.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, ChoiceItem[] items)
Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems to be used as its initial contents.

ChoiceGroup(String label, int choiceType, ChoiceItem[] items, Style style)
Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems to be used as its initial contents.

ChoiceGroup(String label, int choiceType, ChoiceItem[] items, Style style, boolean allowImplicit)
Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems to be used as its initial contents.

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.

ChoiceGroup(String label, int choiceType, String[] stringElements, Image[] imageElements, Style style)
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.

ChoiceGroup(String label, int choiceType, String[] stringElements, Image[] imageElements, Style style, boolean allowImplicit)
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.

ChoiceGroup(String label, int choiceType, Style style)
Creates a new, empty ChoiceGroup, specifying its title and its type.

Method Summary

int	append(ChoiceItem item) Appends a ChoiceItem to this choice group.
int	append(ChoiceItem item, Style elementStyle) Appends a ChoiceItem to this choice group.
int	append(String stringPart, Image imagePart) Appends an element to the ChoiceGroup.
int	append(String stringPart, Image imagePart, Style elementStyle) Appends an element to the ChoiceGroup.
protected static ChoiceItem[]	buildChoiceItems(String[] stringElements, Image[] imageElements, int choiceType, Style style) Builds an array of ChoiceItems out of an array of Strings and Images, specifying the choiceType and style common to any ChoiceItem in the resulting array.
void	clear() Removes all items from this container.
void	commandAction(Command c, Item item) Called by the system to indicate that a command has been invoked on a particular item.
protected String	createCssSelector() Retrieves the CSS selector for this item.
protected Image	createPopupImage() Creates or returns the default image for popup groups.
void	defocus(Style originalStyle) Removes the focus from this item.
void	delete(int elementNum) Deletes the element referenced by elementNum.
void	deleteAll() Deletes all elements from this ChoiceGroup.
protected Style	focus(Style focusStyle, int direction) Focuses this item.
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.
ChoiceItem	getItem(int elementNum) Gets the ChoiceItem 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.
int	getType() Retrieves the choice type of this group
protected boolean	handleCommand(Command cmd) Tries to handle the specified command.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handleKeyReleased(int keyCode, int gameAction) Handles the key-released event.
protected boolean	handleNavigate(int keyCode, int gameAction) Handles a keyPressed or keyRepeated event for navigating in the container.
protected boolean	handlePointerPressed(int relX, int relY) Handles the event when a pointer has been pressed at the specified position.
protected boolean	handlePointerReleased(int relX, int relY) Handles the event when a pointer has been released at the specified position.
protected void	hideNotify() Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible.
protected void	init(int firstLineWidth, int availWidth, int availHeight) Initializes this item.
protected void	initContent(int firstLineWidth, int availWidth, int availHeight) Initialises this item.
void	insert(int elementNum, ChoiceItem item) Inserts an element into the ChoiceGroup just prior to the element specified.
void	insert(int elementNum, ChoiceItem item, Style elementStyle) Inserts an element into the ChoiceGroup just prior to the element specified.
void	insert(int elementNum, String stringPart, Image imagePart) Inserts an element into the ChoiceGroup just prior to the element specified.
void	insert(int elementNum, String stringPart, Image imagePart, Style elementStyle) Inserts an element into the ChoiceGroup just prior to the element specified.
boolean	isInContentArea(int relX, int relY) Determines whether the given relative x/y position is inside of this item's (visible) content area.
boolean	isInItemArea(int relX, int relY) Determines whether the given relative x/y position is inside of this item's area including paddings, margins and label.
boolean	isPopupClosed() Checks if the popup window is currently closed for a POPUP ChoiceGroup.
boolean	isSelected(int elementNum) Gets a boolean value indicating whether this element is selected.
void	paintContent(int x, int y, int leftBorder, int rightBorder, Graphics g) Paints the content of this item.
protected void	selectChoiceItem(ChoiceItem item, boolean isSelected) Selects a choice 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	set(int elementNum, String stringPart, Image imagePart, Style elementStyle) Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.
void	setDefaultCommand(Command cmd) Sets the command for selecting this (and opening this POPUP) choicegroup.
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	setItemsList(ArrayList itemsList) Sets a list of items for this container.
protected void	setSelectCommand(Command command) Sets the select command for this choice group.
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.
void	setStyle(Style style, boolean resetStyle) Sets the style of this item for animatable CSS attributes.
void	setStyleWithBackground(Style style, boolean ignoreBackground) Sets the style of this container.
protected void	updateInternalPosition(Item item) Updates the internal position of this container according to the specified item's one

Methods inherited from class de.enough.polish.ui.Container

add, add, add, add, add, add, add, addRepaintArea, animate, changeChildStyles, changeChildStyles, contains, destroy, fireEvent, focusChild, focusChild, focusClosestItem, focusClosestItemAbove, get, getChildAt, getChildAtImpl, getChildHeight, getChildWidth, getCurrentScrollYOffset, getFocusedChild, getFocusedIndex, getFocusedItem, getFocusedStyle, getFocusListener, getInternalArray, getItemAreaHeight, getItemAt, getItems, getNumberOfInteractiveItems, getPosition, getRelativeScrollYOffset, getScrollHeight, getScrollYOffset, getSynchronizationLock, getView, getView, handleKeyRepeated, handleOnFocusSoftKeyboardDisplayBehavior, handlePointerDragged, handlePointerDragged, handlePointerScrollReleased, handlePointerTouchDown, handlePointerTouchUp, indexOf, initLayout, initMargin, isItemVisible, isScrolling, isVerticalLayout, notifyItemPressedEnd, notifyItemPressedStart, onScreenSizeChanged, paintBackgroundAndBorder, parseIndexUrl, releaseResources, remove, remove, requestDefocus, requestFullInit, resetLastPointerPressYOffset, resetStyle, scroll, scroll, scroll, scrollToBottom, scrollToTop, set, set, set, setAppearanceMode, setAutoFocusEnabled, setContentHeight, setContentWidth, setFocusListener, setItemWidth, setScrollHeight, setScrollYOffset, setScrollYOffset, setStyle, setView, showCommands, showNotify, size, startScroll, toString

Methods inherited from class de.enough.polish.ui.Item

addCommand, addCommand, addCommand, addCommands, addRelativeToBackgroundRegion, addRelativeToBackgroundRegion, addRelativeToContentRegion, animate, containsCommand, fireContinueCycle, getAbsoluteX, getAbsoluteY, getAfterWidthWithPadding, getAppearanceMode, getAttribute, getAttributes, getAvailableContentHeight, getAvailableContentWidth, getAvailableHeight, getAvailableWidth, getBackgroundHeight, getBackgroundWidth, getBackgroundX, getBackgroundY, getBeforeWidthWithPadding, getBorderWidthBottom, getBorderWidthLeft, getBorderWidthRight, getBorderWidthTop, getContentHeight, getContentWidth, getContentX, getContentY, getCycleListener, getDefaultCommand, getFocusedStyle, getInternalHeight, getInternalWidth, getInternalX, getInternalY, getItemCommandListener, getItemCommands, getItemHeight, getItemHeight, getItemStateListener, getItemWidth, getItemWidth, getLabel, getLabelItem, getLayout, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getMaximumHeight, getMaximumHeight, getMaximumWidth, getMaximumWidth, getMinimumHeight, getMinimumHeight, getMinimumWidth, getMinimumWidth, getNativeItem, getPaddingBottom, getPaddingHorizontal, getPaddingLeft, getPaddingRight, getPaddingTop, getPaddingVertical, getParent, getParentRoot, getpreferredHeight, getpreferredWidth, getRgbData, getRgbData, getScreen, getStyle, getUiEventListener, handleCommand, handleGesture, handleGestureHold, handleGestureSwipeLeft, handleGestureSwipeRight, initPadding, initStyle, isFocused, isInContentWithPaddingArea, isInItemArea, isInitialized, isInteractive, isLayoutBottom, isLayoutCenter, isLayoutExpand, isLayoutLeft, isLayoutNewlineAfter, isLayoutNewlineBefore, isLayoutRight, isLayoutShrink, isLayoutTop, isLayoutVerticalCenter, isLayoutVerticalExpand, isLayoutVerticalShrink, isPressed, isSameRowForContentAndLabel, isVisible, notifyStateChanged, notifyUnvisited, notifyValueChanged, notifyVisited, paint, paintBackground, paintBorder, paintCommands, paintFilter, removeAttribute, removeCommand, repaint, repaint, repaintFully, requestInit, setAbsoluteY, setAttribute, setBackground, setBorder, setCycleListener, setDefaultCommand, setInitialized, setItemCommandListener, setItemHeight, setItemStateListener, setItemTransition, setLabel, setLayout, setNativeItem, setParent, setParent, setpreferredSize, setSameRowForContentAndLabel, setStyle, setUiEventListener, setVisible, show, show, toImage, toRgbImage, updateInternalArea

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface de.enough.polish.ui.Choice

size

Field Detail

MARK_COMMAND

public static Command MARK_COMMAND

UNMARK_COMMAND

public static Command UNMARK_COMMAND

choiceType

protected int choiceType

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,
                   Style style)

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

style - the CSS style for this item

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 or 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 or 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,
                   Style style)

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

style - The CSS style for this item

Throws:

NullPointerException - if stringElements is null or 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 or 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,
                   Style style,
                   boolean allowImplicit)

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

style - The CSS style for this item

allowImplicit - true when the Choice.IMPLICIT choiceType is also allowed

Throws:

NullPointerException - if stringElements is null or 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 or if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   ChoiceItem[] items)

Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems 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 itemss array must be non-null and every ChoiceItem must have its text be a non-null String. The length of the items array determines the number of elements in the ChoiceGroup.

Parameters:

label - the item's label (see Item)

choiceType - EXCLUSIVE, MULTIPLE, or POPUP

items - set of ChoiceItems specifying the ChoiceGroup elements

Throws:

NullPointerException - if items is null or if getText() for one of the ChoiceItem in the array retuns a null String.

IllegalArgumentException - if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   ChoiceItem[] items,
                   Style style)

Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems 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 itemss array must be non-null and every ChoiceItem must have its text be a non-null String. The length of the items array determines the number of elements in the ChoiceGroup.

Parameters:

label - the item's label (see Item)

choiceType - EXCLUSIVE, MULTIPLE, or POPUP

items - set of ChoiceItems specifying the ChoiceGroup elements

style - The CSS style for this item

Throws:

NullPointerException - if items is null or if getText() for one of the ChoiceItem in the array retuns a null String.

IllegalArgumentException - if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

ChoiceGroup

public ChoiceGroup(String label,
                   int choiceType,
                   ChoiceItem[] items,
                   Style style,
                   boolean allowImplicit)

Creates a new ChoiceGroup, specifying its title, the type of the ChoiceGroup, and an array of ChoiceItems 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 itemss array must be non-null and every ChoiceItem must have its text be a non-null String. The length of the items array determines the number of elements in the ChoiceGroup.

Parameters:

label - the item's label (see Item)

choiceType - EXCLUSIVE, MULTIPLE, or POPUP

items - set of ChoiceItems specifying the ChoiceGroup elements

style - The CSS style for this item

allowImplicit - true when the Choice.IMPLICIT choiceType is also allowed

Throws:

IllegalArgumentException - if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

Method Detail

buildChoiceItems

protected static ChoiceItem[] buildChoiceItems(String[] stringElements,
                                               Image[] imageElements,
                                               int choiceType,
                                               Style style)

Builds an array of ChoiceItems out of an array of Strings and Images, specifying the choiceType and style common to any ChoiceItem in the resulting array.

Parameters:

stringElements - set of strings specifying the string parts of the ChoiceGroup elements

imageElements - set of images specifying the image parts of the ChoiceGroup elements

choiceType - EXCLUSIVE, MULTIPLE, or POPUP

style - The CSS style for this item

Returns:

an aray of choice items

Throws:

NullPointerException - if stringElements is null or 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

See Also:

Choice.EXCLUSIVE, Choice.MULTIPLE, Choice.IMPLICIT, Choice.POPUP

createPopupImage

protected Image createPopupImage()

Creates or returns the default image for popup groups.

Returns:

the default popup image

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:

in interface Choice, 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:

in interface Choice, getString(int)

getItem

public ChoiceItem getItem(int elementNum)

Gets the ChoiceItem of the element referenced by elementNum.

Parameters:

elementNum - the number of the element to be queried

Returns:

the ChoiceItem of the element

Throws:

IndexOutOfBoundsException - if elementNum is invalid

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

See Also:

in interface Choice

append

public int append(String stringPart,
                  Image imagePart,
                  Style elementStyle)

Appends an element to the ChoiceGroup.

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

elementStyle - the style for the appended ChoiceItem

Returns:

the assigned index of the element

Throws:

NullPointerException - if stringPart is null

See Also:

in interface Choice

append

public int append(ChoiceItem item)

Appends a ChoiceItem to this choice group.

Parameters:

item - the item

Returns:

the assigned index of the element

append

public int append(ChoiceItem item,
                  Style elementStyle)

Appends a ChoiceItem to this choice group.

Parameters:

item - the item

elementStyle - the style of the item, ignored when null

Returns:

the assigned index of the element

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

See Also:

in interface Choice

insert

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

Inserts an element into the ChoiceGroup just prior to the element specified.

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

elementStyle - the style for the inserted ChoiceItem

Throws:

IndexOutOfBoundsException - if elementNum is invalid

NullPointerException - if stringPart is null

See Also:

in interface Choice

insert

public void insert(int elementNum,
                   ChoiceItem item)

Inserts an element into the ChoiceGroup just prior to the element specified.

Parameters:

elementNum - the index of the element where insertion is to occur

item - ChoiceItem of the element to be inserted

Throws:

IndexOutOfBoundsException - if elementNum is invalid

insert

public void insert(int elementNum,
                   ChoiceItem item,
                   Style elementStyle)

Inserts an element into the ChoiceGroup just prior to the element specified.

Parameters:

elementNum - the index of the element where insertion is to occur

item - ChoiceItem of the element to be inserted

elementStyle - the style for the inserted ChoiceItem

Throws:

IndexOutOfBoundsException - if elementNum is invalid

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

See Also:

in interface Choice

set

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

Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element.

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

elementStyle - the style for the new list element.

Throws:

IndexOutOfBoundsException - if elementNum is invalid

NullPointerException - if stringPart is null

See Also:

in interface Choice

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

See Also:

in interface Choice

deleteAll

public void deleteAll()

Deletes all elements from this ChoiceGroup.

Specified by:

deleteAll in interface Choice

See Also:

in interface Choice

clear

public void clear()

Description copied from class: Container

Removes all items from this container.

Overrides:

clear in class Container

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

See Also:

in interface Choice

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:

in interface Choice, 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:

in interface Choice, 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:

in interface Choice, 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:

in interface Choice, 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. The J2ME Polish implementation always uses the TEXT_WRAP_ON policy.

Specified by:

setFitPolicy in interface Choice

Parameters:

fitPolicy - preferred content fit policy for choice elements

Since:

MIDP 2.0

See Also:

in interface Choice, 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:

always Choice.TEXT_WRAP_ON

Since:

MIDP 2.0

See Also:

in interface Choice, 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 J2ME Polish implementation uses the font defined by the appropriate CSS style and ignores the font which is set here.

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:

in interface Choice, 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:

in interface Choice, setFont(int elementNum, Font font)

hideNotify

protected void hideNotify()

Description copied from class: Container

Called by the system to notify the item that it is now completely invisible, when it previously had been at least partially visible. No further paint() calls will be made on this item until after a showNotify() has been called again.

The container implementation calls hideNotify() on the embedded items.

Overrides:

hideNotify in class Container

paintContent

public void paintContent(int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         Graphics g)

Description copied from class: Item

Paints the content of this item. The background has already been painted and the border will be added after this method returns.

Overrides:

paintContent in class Container

Parameters:

x - the left start position

y - the upper start position

leftBorder - the left border, nothing must be painted left of this position

rightBorder - the right border, nothing must be painted right of this position

g - the Graphics on which this item should be painted.

init

protected void init(int firstLineWidth,
                    int availWidth,
                    int availHeight)

Description copied from class: Item

Initializes this item. You should always call super.init( firstLineWidth, lineWidth) when overriding this method. This method call either ItemView.initContent() or Item.initContent() to initialize the actual content. A valid case for overriding would be if additional initialization needs to be done even when an ItemView is associated with this Item. Usually implementing initContent() should suffice.

Overrides:

init in class Item

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the maximum width of any following lines

availHeight - the maximum height that can be used without scrolling

See Also:

Item.initContent(int, int, int), ItemView.initContent(Item, int, int, int)

initContent

protected void initContent(int firstLineWidth,
                           int availWidth,
                           int availHeight)

Description copied from class: Item

Initialises this item. The implementation needs to calculate and set the contentWidth and contentHeight fields. The implementation should take the fields preferredWidth and preferredHeight into account.

Overrides:

initContent in class Container

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the available maximum width of this item in pixels

availHeight - the available maximum height of this item in pixels

See Also:

Item.contentWidth, Item.contentHeight, Item.preferredWidth, Item.preferredHeight

updateInternalPosition

protected void updateInternalPosition(Item item)

Description copied from class: Container

Updates the internal position of this container according to the specified item's one

Overrides:

updateInternalPosition in class Container

Parameters:

item - the (assumed focused) item

createCssSelector

protected String createCssSelector()

Description copied from class: Item

Retrieves the CSS selector for this item. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the item and not by a predefined style-name. With the #style preprocessing command styles are set fix, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "Form>p", than the selector of the item is needed.
This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles
The returned selector needs to be in lower case.

Overrides:

createCssSelector in class Container

Returns:

the appropriate CSS selector for this item. The selector needs to be in lower case.

isPopupClosed

public boolean isPopupClosed()

Checks if the popup window is currently closed for a POPUP ChoiceGroup.

Returns:

true when this is a POPUP ChoiceGroup and the popup is closed

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: Item

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation just handles the FIRE game-action when a default-command and an item-command-listener have been registered.

Overrides:

handleKeyPressed in class Container

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

handleNavigate

protected boolean handleNavigate(int keyCode,
                                 int gameAction)

Description copied from class: Container

Handles a keyPressed or keyRepeated event for navigating in the container.

Overrides:

handleNavigate in class Container

Parameters:

keyCode - the code of the keypress/keyrepeat event

gameAction - the associated game action

Returns:

true when the key was handled

selectChoiceItem

protected void selectChoiceItem(ChoiceItem item,
                                boolean isSelected)

Selects a choice item.

Parameters:

item - the item

isSelected - true when it should be marked as selected

handleKeyReleased

protected boolean handleKeyReleased(int keyCode,
                                    int gameAction)

Description copied from class: Item

Handles the key-released event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation invokes the default command if one is present

Overrides:

handleKeyReleased in class Container

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

See Also:

Item.handleKeyPressed(int, int)

handlePointerPressed

protected boolean handlePointerPressed(int relX,
                                       int relY)

Description copied from class: Item

Handles the event when a pointer has been pressed at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyPressed event, which is subsequently handled by the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Overrides:

handlePointerPressed in class Container

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

true when the pressing of the pointer was actually handled by this item.

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, Item.handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

handlePointerReleased

protected boolean handlePointerReleased(int relX,
                                        int relY)

Description copied from class: Item

Handles the event when a pointer has been released at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyReleased event, which is subsequently handled bu the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Overrides:

handlePointerReleased in class Container

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

true when the pressing of the pointer was actually handled by this item.

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, Item.handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

isInContentArea

public boolean isInContentArea(int relX,
                               int relY)

Description copied from class: Item

Determines whether the given relative x/y position is inside of this item's (visible) content area. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method or possibly the getContentX(), getContentY() methods. It is assumed that the item has been initialized before.

Overrides:

isInContentArea in class Item

Parameters:

relX - the x position relative to this item's left position

relY - the y position relative to this item's top position

Returns:

true when the relX/relY coordinate is within this item's content area.

See Also:

Item.initContent(int, int, int)

isInItemArea

public boolean isInItemArea(int relX,
                            int relY)

Description copied from class: Item

Determines whether the given relative x/y position is inside of this item's area including paddings, margins and label. Subclasses which extend their area over the declared/official content area, which is determined in the initContent() method (like popup items), might want to override this method. It is assumed that the item has been initialized before.

Overrides:

isInItemArea in class Container

Parameters:

relX - the x position relative to this item's left position

relY - the y position relative to this item's top position

Returns:

true when the relX/relY coordinate is within this item's area.

See Also:

Item.initContent(int, int, int)

setSelectCommand

protected void setSelectCommand(Command command)

Sets the select command for this choice group.

Parameters:

command - the new select command

setDefaultCommand

public void setDefaultCommand(Command cmd)

Sets the command for selecting this (and opening this POPUP) choicegroup. This implementation only works like described when not all ChoiceGroup commands are deactivated by specifying the and preprocessing variables. When all commands are deactivated by the mentioned preprocessing variables, the implementation of Item is used instead.

Overrides:

setDefaultCommand in class Item

Parameters:

cmd - the new command for selecting this choice group

defocus

public void defocus(Style originalStyle)

Description copied from class: Item

Removes the focus from this item.

Overrides:

defocus in class Container

Parameters:

originalStyle - the original style which will be restored.

focus

protected Style focus(Style focusStyle,
                      int direction)

Description copied from class: Item

Focuses this item.

Overrides:

focus in class Container

Parameters:

focusStyle - the style which is used to indicate the focused state

direction - the direction from which this item is focused, either Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT or 0. When 0 is given, the direction is unknown.

Returns:

the current style of this item

setStyleWithBackground

public void setStyleWithBackground(Style style,
                                   boolean ignoreBackground)

Description copied from class: Container

Sets the style of this container.

Overrides:

setStyleWithBackground in class Container

Parameters:

style - the style

ignoreBackground - when true is given, the background and border-settings will be ignored.

setStyle

public void setStyle(Style style,
                     boolean resetStyle)

Description copied from class: Item

Sets the style of this item for animatable CSS attributes.

Specified by:

setStyle in interface UiElement

Overrides:

setStyle in class Container

Parameters:

style - the new style for this element.

resetStyle - true when style settings should be resetted. This is not the case when styles are animated, for example.

commandAction

public void commandAction(Command c,
                          Item item)

Description copied from interface: ItemCommandListener

Called by the system to indicate that a command has been invoked on a particular item.

Specified by:

commandAction in interface ItemCommandListener

Parameters:

c - the Command that was invoked

item - the Item on which the command was invoked

handleCommand

protected boolean handleCommand(Command cmd)

Description copied from class: Item

Tries to handle the specified command. The item checks if the command belongs to this item and if it has an associated ItemCommandListener. Only then it handles the command.

Overrides:

handleCommand in class Container

Parameters:

cmd - the command

Returns:

true when the command has been handled by this item

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. When no listener is registered, J2ME Polish notifies the command-listener of the current screen, when an item command has been selected.

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.

setItemsList

public void setItemsList(ArrayList itemsList)

Description copied from class: Container

Sets a list of items for this container. Use this direct access only when you know what you are doing.

Overrides:

setItemsList in class Container

Parameters:

itemsList - the list of items to set

getType

public int getType()

Retrieves the choice type of this group

Returns:

the choice type, either MULTIPLE, EXCLUSIVE or POPUP