File	Doc	Category	Size	Date	Package
ChoiceGroup.java	API Doc	phoneME MR2 API (J2ME)	33215	Wed May 02 18:00:22 BST 2007	javax.microedition.lcdui

ChoiceGroup

• java.lang.Object
  • Item

Fields Summary
ChoiceGroupLF	choiceGroupLF The look&feel associated with this ChoiceGroup. Set in the constructor.
int	choiceType The type of this ChoiceGroup
int	fitPolicy The string fit policy for this ChoiceGroup '0' by default, which is Choice.TEXT_WRAP_DEFAULT
int	numOfEls The number of elements in this ChoiceGroup
CGElement[]	cgElements The array containing the Font of each element (null if no setFont() method was ever called). If fontEls is non-null, only the elements which were set by setFont() are non-null.
static final int	GROW_FACTOR Optimization for CGElement array size management. Notice that cgElements.length is not equal to numOfEls. Use numOfEls only when accessing the array.

Constructors Summary
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. param label the item's label (see {@link Item Item}) param choiceType EXCLUSIVE, MULTIPLE, or POPUP throws IllegalArgumentException if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP see Choice#EXCLUSIVE see Choice#MULTIPLE see Choice#IMPLICIT see Choice#POPUP this(label, choiceType, new String[] {}, null);
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. param label the item's label (see {@link Item Item}) param choiceType EXCLUSIVE, MULTIPLE, or POPUP param stringElements set of strings specifying the string parts of the ChoiceGroup elements param imageElements set of images specifying the image parts of the ChoiceGroup elements throws NullPointerException if stringElements is null throws NullPointerException if the stringElements array contains any null elements throws IllegalArgumentException if the imageElements array is non-null and has a different length from the stringElements array throws IllegalArgumentException if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP see Choice#EXCLUSIVE see Choice#MULTIPLE see Choice#IMPLICIT see Choice#POPUP this(label, choiceType, stringElements, imageElements, false);
ChoiceGroup(String label, int choiceType, String[] stringElements, Image[] imageElements, boolean implicitAllowed) Special constructor used by List param label the item's label (see {@link Item Item}) param choiceType EXCLUSIVE or MULTIPLE param stringElements set of strings specifying the string parts of the ChoiceGroup elements param imageElements set of images specifying the image parts of the ChoiceGroup elements param implicitAllowed Flag to allow implicit selection throws NullPointerException if stringElements is null throws NullPointerException if the stringElements array contains any null elements throws IllegalArgumentException if the imageElements array is non-null and has a different length from the stringElements array throws IllegalArgumentException if choiceType is neither EXCLUSIVE nor MULTIPLE throws IllegalArgumentException if any image in the imageElements array is mutable see Choice#EXCLUSIVE see Choice#MULTIPLE see Choice#IMPLICIT super(label); if (!((choiceType == Choice.MULTIPLE) || (choiceType == Choice.EXCLUSIVE) || ((choiceType == Choice.IMPLICIT) && implicitAllowed) || (choiceType == Choice.POPUP))) { throw new IllegalArgumentException(); } // If stringElements is null NullPointerException will be thrown // as expected for (int x = 0; x < stringElements.length; x++) { if (stringElements[x] == null) { throw new NullPointerException(); } } if (imageElements != null) { if (stringElements.length != imageElements.length) { throw new IllegalArgumentException(); } } synchronized (Display.LCDUILock) { this.choiceType = choiceType; numOfEls = stringElements.length; cgElements = new CGElement[numOfEls + GROW_FACTOR]; if (imageElements != null) { for (int i = 0; i < numOfEls; i++) { cgElements[i] = new CGElement(stringElements[i], imageElements[i]); } } else { for (int i = 0; i < numOfEls; i++) { cgElements[i] = new CGElement(stringElements[i], null /* image */); } } itemLF = choiceGroupLF = LFFactory.getFactory().getChoiceGroupLF(this); // initialize fonts to default one in all elements; // this has to be done after ChoiceGroupLF is created for (int i = 0; i < numOfEls; i++) { cgElements[i].setFont(null); } } // synchronized

Methods Summary
boolean	acceptFocus() Return whether the Item takes user input focus. return return true if contents is not null or have abstract commands. return super.acceptFocus() || numOfEls > 0;
public int	append(java.lang.String stringPart, Image imagePart) Appends an element to the ChoiceGroup. param stringPart the string part of the element to be added param imagePart the image part of the element to be added, or null if there is no image part return the assigned index of the element throws NullPointerException if stringPart is null int elementNum = -1; synchronized (Display.LCDUILock) { checkNull(stringPart); if ((elementNum = insertImpl(numOfEls, stringPart, imagePart)) >= 0) { choiceGroupLF.lInsert(elementNum, stringPart, imagePart); } } return elementNum;
private void	checkFlag(boolean[] flag) Check the validity of the selection array param flag The array of boolean flags representing the selected state of the elements throws NullPointerException If the flag array is null throws IllegalArgumentException If the flag array is not the same size as the element array if (flag == null) { throw new NullPointerException(); } if (flag.length < numOfEls) { throw new IllegalArgumentException(); }
private void	checkIndex(int elementNum) Check the validity of a given element index param elementNum The index to check throws IndexOutOfBoundsException If no element exists at the that index if (elementNum < 0 || elementNum >= numOfEls) { throw new IndexOutOfBoundsException(); }
private void	checkNull(java.lang.String stringPart) Check the given values for null. param stringPart The string part of the element throws NullPointerException If the string part is null if (stringPart == null) { throw new NullPointerException(); }
public void	delete(int elementNum) Deletes the element referenced by elementNum. param elementNum the index of the element to be deleted throws IndexOutOfBoundsException if elementNum is invalid synchronized (Display.LCDUILock) { checkIndex(elementNum); --numOfEls; // setup new elements array if (elementNum != numOfEls) { System.arraycopy(cgElements, elementNum + 1, cgElements, elementNum, numOfEls - elementNum); } // free some memory... (efficient for very large arrays) if (cgElements.length > (GROW_FACTOR * 10) && cgElements.length / numOfEls >= 2) { CGElement[] newArray = new CGElement[numOfEls + GROW_FACTOR]; System.arraycopy(cgElements, 0, newArray, 0, numOfEls); cgElements = newArray; newArray = null; } cgElements[numOfEls] = null; // notify l&f choiceGroupLF.lDelete(elementNum); } // synchronized
public void	deleteAll() Deletes all elements from this ChoiceGroup. synchronized (Display.LCDUILock) { cgElements = new CGElement[GROW_FACTOR]; // initial size numOfEls = 0; choiceGroupLF.lDeleteAll(); }
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. return one of {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON}, or {@link #TEXT_WRAP_OFF} see #setFitPolicy // SYNC NOTE: return of atomic value, no locking necessary return fitPolicy;
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. param elementNum the index of the element, starting from zero return the preferred font to use to render the element throws IndexOutOfBoundsException if elementNum is invalid see #setFont(int elementNum, Font font) synchronized (Display.LCDUILock) { checkIndex(elementNum); return cgElements[elementNum].getFont(); }
public Image	getImage(int elementNum) Gets the Image part of the element referenced by elementNum. param elementNum the number of the element to be queried return the image part of the element, or null if there is no image throws IndexOutOfBoundsException if elementNum is invalid see #getString(int) synchronized (Display.LCDUILock) { checkIndex(elementNum); // return as mutable, if possible return (cgElements[elementNum].mutableImageEl == null ? cgElements[elementNum].imageEl : cgElements[elementNum].mutableImageEl); }
Image[]	getImageElements() Helper method, used solely by the native method call: updatePopupElements() return an array of image elements Image[] ret = new Image[numOfEls]; for (int i = 0; i < numOfEls; i++) { ret[i] = cgElements[i].imageEl; } return ret;
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. return the number of selected elements in the ChoiceGroup param selectedArray_return array to contain the results throws IllegalArgumentException if selectedArray_return is shorter than the size of the ChoiceGroup throws NullPointerException if selectedArray_return is null see #setSelectedFlags checkFlag(selectedArray_return); synchronized (Display.LCDUILock) { int numSelected = 0; if (numOfEls > 0) { numSelected = choiceGroupLF.lGetSelectedFlags(selectedArray_return); } for (int i = numOfEls; i < selectedArray_return.length; i++) { selectedArray_return[i] = false; } return numSelected; }
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 {@link #getSelectedFlags getSelectedFlags}. return index of selected element, or -1 if none see #setSelectedIndex synchronized (Display.LCDUILock) { return choiceGroupLF.lGetSelectedIndex(); }
public java.lang.String	getString(int elementNum) Gets the String part of the element referenced by elementNum. param elementNum the index of the element to be queried return the string part of the element throws IndexOutOfBoundsException if elementNum is invalid see #getImage(int) synchronized (Display.LCDUILock) { checkIndex(elementNum); // return stringEls[elementNum]; return cgElements[elementNum].stringEl; }
java.lang.String[]	getStringElements() Helper method, used solely by the native method call: updatePopupElements() return an array of string elements String[] ret = new String[numOfEls]; for (int i = 0; i < numOfEls; i++) { ret[i] = cgElements[i].stringEl; } return ret;
public void	insert(int elementNum, java.lang.String stringPart, Image imagePart) Inserts an element into the ChoiceGroup just prior to the element specified. param elementNum the index of the element where insertion is to occur param stringPart the string part of the element to be inserted param imagePart the image part of the element to be inserted, or null if there is no image part throws IndexOutOfBoundsException if elementNum is invalid throws NullPointerException if stringPart is null synchronized (Display.LCDUILock) { if (elementNum < 0 || elementNum > numOfEls) { throw new IndexOutOfBoundsException(); } checkNull(stringPart); if (insertImpl(elementNum, stringPart, imagePart) >= 0) { choiceGroupLF.lInsert(elementNum, stringPart, imagePart); } }
private int	insertImpl(int elementNum, java.lang.String stringPart, Image imagePart) Insert a particular element of this ChoiceGroup param elementNum The index to insert the element param stringPart The string part of the element to insert param imagePart The image part of the element to insert return int The index of the newly inserted element // cgElements is created in the constructor and cannot be null // full capacity reached if (numOfEls == cgElements.length) { CGElement[] newCGEls = new CGElement[numOfEls + GROW_FACTOR]; System.arraycopy(cgElements, 0, newCGEls, 0, elementNum); System.arraycopy(cgElements, elementNum, newCGEls, elementNum + 1, numOfEls - elementNum); cgElements = newCGEls; // swap them } else if (elementNum != numOfEls) { // if we're not appending System.arraycopy(cgElements, elementNum, cgElements, elementNum + 1, numOfEls - elementNum); } numOfEls++; cgElements[elementNum] = new CGElement(stringPart, imagePart); return elementNum;
public boolean	isSelected(int elementNum) Gets a boolean value indicating whether this element is selected. param elementNum the index of the element to be queried return selection state of the element throws IndexOutOfBoundsException if elementNum is invalid synchronized (Display.LCDUILock) { checkIndex(elementNum); return choiceGroupLF.lIsSelected(elementNum); }
public void	set(int elementNum, java.lang.String stringPart, Image imagePart) Sets the String and Image parts of the element referenced by elementNum, replacing the previous contents of the element. param elementNum the index of the element to be set param stringPart the string part of the new element param imagePart the image part of the element, or null if there is no image part throws IndexOutOfBoundsException if elementNum is invalid throws NullPointerException if stringPart is null synchronized (Display.LCDUILock) { checkIndex(elementNum); checkNull(stringPart); cgElements[elementNum].set(stringPart, imagePart); choiceGroupLF.lSet(elementNum, stringPart, imagePart); }
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 {@link #TEXT_WRAP_DEFAULT}, {@link #TEXT_WRAP_ON}, and {@link #TEXT_WRAP_OFF}. Fit policy is a hint, and the implementation may disregard the application's preferred policy. param fitPolicy preferred content fit policy for choice elements throws IllegalArgumentException if fitPolicy is invalid see #getFitPolicy if (fitPolicy < TEXT_WRAP_DEFAULT || fitPolicy > TEXT_WRAP_OFF) { throw new IllegalArgumentException(); } synchronized (Display.LCDUILock) { if (this.fitPolicy != fitPolicy) { this.fitPolicy = fitPolicy; choiceGroupLF.lSetFitPolicy(fitPolicy); } }
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. param elementNum the index of the element, starting from zero param font the preferred font to use to render the element throws IndexOutOfBoundsException if elementNum is invalid see #getFont synchronized (Display.LCDUILock) { checkIndex(elementNum); cgElements[elementNum].setFont(font); choiceGroupLF.lSetFont(elementNum, cgElements[elementNum].getFont()); }
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. param selectedArray an array in which the method collect the selection status throws IllegalArgumentException if selectedArray is shorter than the size of the ChoiceGroup throws NullPointerException if the selectedArray is null see #getSelectedFlags synchronized (Display.LCDUILock) { checkFlag(selectedArray); if (numOfEls == 0) { return; } if (choiceType == Choice.MULTIPLE) { for (int i = 0; i < numOfEls; i++) { cgElements[i].setSelected(selectedArray[i]); } choiceGroupLF.lSetSelectedFlags(selectedArray); } else { for (int i = 0; i < numOfEls; i++) { if (selectedArray[i]) { choiceGroupLF.lSetSelectedIndex(i, true); return; } } choiceGroupLF.lSetSelectedIndex(0, true); } } // synchronized
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. param elementNum the number of the element. Indexing of the elements is zero-based param selected the new state of the element true=selected, false=not selected throws IndexOutOfBoundsException if elementNum is invalid see #getSelectedIndex checkIndex(elementNum); synchronized (Display.LCDUILock) { choiceGroupLF.lSetSelectedIndex(elementNum, selected); } // synchronized
public int	size() Returns the number of elements in the ChoiceGroup. return the number of elements in the ChoiceGroup // SYNC NOTE: return of atomic value, no locking necessary return numOfEls;