choicegroup.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

	{
		this( label, choiceType, items, null, false );
	}

	/**
	 * Creates a new <code>ChoiceGroup</code>, specifying its title,
	 * the type of the
	 * <code>ChoiceGroup</code>, and an array of <code>ChoiceItem</code>s
	 * to be used as its initial contents.
	 * 
	 * <p>The type must be one of <code>EXCLUSIVE</code>,
	 * <code>MULTIPLE</code>, or <code>POPUP</code>.  The
	 * <code>IMPLICIT</code>
	 * type is not allowed for <code>ChoiceGroup</code>.</p>
	 * 
	 * <p>The <code>items</code>s array must be non-null and
	 * every <code>ChoiceItem</code> must have its text be a non-null
	 * <code>String</code>.
	 * The length of the <code>items</code> array
	 * determines the number of elements in the <code>ChoiceGroup</code>.</p>
	 * 
	 * @param label the item's label (see Item)
	 * @param choiceType EXCLUSIVE, MULTIPLE, or POPUP
	 * @param items set of <code>ChoiceItem</code>s specifying the ChoiceGroup elements
	 * @param style The CSS style for this item
	 * @throws NullPointerException if <code>items</code> is null 
	 *         or if getText() for one of the <code>ChoiceItem</code> in the array 
	 *         retuns a null <code>String</code>.
	 * @throws IllegalArgumentException if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)
	 * @see Choice#EXCLUSIVE
	 * @see Choice#MULTIPLE
	 * @see Choice#IMPLICIT
	 * @see Choice#POPUP
	 */
	public ChoiceGroup( String label, int choiceType, ChoiceItem[] items, Style style )
	{
		this( label, choiceType, items, style, false );
	}

	/**
	 * Creates a new <code>ChoiceGroup</code>, specifying its title,
	 * the type of the
	 * <code>ChoiceGroup</code>, and an array of <code>ChoiceItem</code>s
	 * to be used as its initial contents.
	 * 
	 * <p>The type must be one of <code>EXCLUSIVE</code>,
	 * <code>MULTIPLE</code>, or <code>POPUP</code>.  The
	 * <code>IMPLICIT</code>
	 * type is not allowed for <code>ChoiceGroup</code>.</p>
	 * 
	 * <p>The <code>items</code>s array must be non-null and
	 * every <code>ChoiceItem</code> must have its text be a non-null
	 * <code>String</code>.
	 * The length of the <code>items</code> array
	 * determines the number of elements in the <code>ChoiceGroup</code>.</p>
	 * 
	 * @param label the item's label (see Item)
	 * @param choiceType EXCLUSIVE, MULTIPLE, or POPUP
	 * @param items set of <code>ChoiceItem</code>s specifying the ChoiceGroup elements
	 * @param style The CSS style for this item
	 * @param allowImplicit true when the Choice.IMPLICIT choiceType is also allowed
	 * @throws NullPointerException if <code>items</code> is null 
	 *         or if getText() for one of the <code>ChoiceItem</code> in the array 
	 *         retuns a null <code>String</code>.
	 * @throws IllegalArgumentException if choiceType is not one of EXCLUSIVE, MULTIPLE, or POPUP (unless allowImplicit is defined)
	 * @see Choice#EXCLUSIVE
	 * @see Choice#MULTIPLE
	 * @see Choice#IMPLICIT
	 * @see Choice#POPUP
	 */
	public ChoiceGroup( String label, int choiceType, ChoiceItem[] items, Style style, boolean allowImplicit )
	{
		super( label, false, style, -1 );
		if (choiceType == Choice.EXCLUSIVE) {
			//this.isExclusive = true;
		} else if (choiceType == Choice.MULTIPLE) {
			this.isMultiple = true;
		//#ifdef polish.usePopupItem
		//# } else if (choiceType == Choice.POPUP) {
			//# this.isPopup = true;
			//# this.isPopupClosed = true;
			//# this.popupItem = new IconItem( null, null, style );
			//# this.popupItem.setImageAlign( Graphics.RIGHT );
			//# this.popupItem.setAppearanceMode( BUTTON );
			//# this.popupItem.parent = this;
		//#endif
		} else if (choiceType == Choice.IMPLICIT && allowImplicit ) {
			this.isImplicit = true;
			this.autoFocusEnabled = true;
		} else {
			//#ifdef polish.verboseDebug
				//# throw new IllegalArgumentException("invalid choiceType [" + choiceType + "] - IMPLICIT=" + Choice.IMPLICIT + ".");
			//#else
				throw new IllegalArgumentException();
			//#endif
		}
		this.choiceType = choiceType;
		for (int i = 0; i < items.length; i++) {
			ChoiceItem item = items[i];
			append( item );
		}
	}
	
	/**
	 * Builds an array of <code>ChoiceItems</code> out of
	 * an array of <code>String</code>s and <code>Image</code>s,
	 * specifying the <code>choiceType</code> and <code>style</code>
	 * common to any <code>ChoiceItem</code> in the resulting array.
	 * 
	 * @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 choiceType EXCLUSIVE, MULTIPLE, or POPUP
	 * @param style The CSS style for this item
	 * @return an aray of choice items
	 * @throws NullPointerException if stringElements is null or 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
	 * @see Choice#EXCLUSIVE
	 * @see Choice#MULTIPLE
	 * @see Choice#IMPLICIT
	 * @see Choice#POPUP
	 */
	protected static ChoiceItem[] buildChoiceItems(String[] stringElements, Image[] imageElements, int choiceType, Style style)
	{
		//#ifndef polish.skipArgumentCheck
			if (imageElements != null && imageElements.length != stringElements.length) {
				//#ifdef polish.verboseDebug
					//# throw new IllegalArgumentException("imageElements need to have the same length as the stringElements.");
				//#else
					throw new IllegalArgumentException();
				//#endif
			}
		//#endif
		ChoiceItem[] items = new ChoiceItem[stringElements.length];
		for (int i = 0; i < stringElements.length; ++i) {
			Image img = null;
			if (imageElements != null) {
				img = imageElements[i];
			}
			items[i] = new ChoiceItem( stringElements[i], img, choiceType, style );
		}
		return items;
	}
	
	//#ifdef polish.usePopupItem
	//# /**
	 //# * Creates or returns the default image for popup groups.
	 //# * 
	 //# * @return the default popup image
	 //# */
	//# protected Image createPopupImage() {
		//# if (popupImage == null) {
			//# popupImage = Image.createImage( 9, 12 );
			//# Graphics g = popupImage.getGraphics();
			//# g.setColor( this.popupBackgroundColor );
			//# g.fillRect(0, 0, 10, 13 );
			//# g.setColor( this.popupColor );
			//# g.drawLine(0, 0, 9, 0 );
			//# g.drawLine( 3, 3, 3, 9 );
			//# g.drawLine( 4, 3, 4, 10 );
			//# g.drawLine( 5, 3, 5, 9 );
			//# g.drawLine( 2, 8, 6, 8 );	
			//# g.drawLine( 1, 7, 7, 7 );	
		//# }
		//# return popupImage;
	//# }
	//#endif

	/**
	 * Gets the <code>String</code> part of the element referenced by
	 * <code>elementNum</code>.
	 * 
	 * @param elementNum the index of the element to be queried
	 * @return the string part of the element
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 * @see Choice#getString(int) in interface Choice
	 * @see #getImage(int)
	 */
	public String getString(int elementNum)
	{
		ChoiceItem item = (ChoiceItem) this.itemsList.get( elementNum );
		return item.getText();
	}

	/**
	 * Gets the <code>Image</code> part of the element referenced by
	 * <code>elementNum</code>.
	 * 
	 * @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 Choice#getImage(int) in interface Choice
	 * @see #getString(int)
	 */
	public Image getImage(int elementNum)
	{
		ChoiceItem item = (ChoiceItem) this.itemsList.get( elementNum );
		return item.getImage();
	}

	/**
	 * Gets the <code>ChoiceItem</code> of the element referenced by
	 * <code>elementNum</code>.
	 *
	 * @param elementNum the number of the element to be queried
	 * @return the ChoiceItem of the element
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 */
	public ChoiceItem getItem( int elementNum )
	{
		return (ChoiceItem)this.itemsList.get( elementNum );
	}

	/**
	 * Appends an element to the <code>ChoiceGroup</code>.
	 * 
	 * @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
	 * @see Choice#append( String, Image) in interface Choice
	 */
	public int append( String stringPart, Image imagePart)
	{
		return append( stringPart, imagePart, null );
	}
	
	/**
	 * Appends an element to the <code>ChoiceGroup</code>.
	 * 
	 * @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
	 * @param elementStyle the style for the appended ChoiceItem
	 * @return the assigned index of the element
	 * @throws NullPointerException if stringPart is null
	 * @see Choice#append( String, Image) in interface Choice
	 */
	public int append( String stringPart, Image imagePart, Style elementStyle )
	{
		ChoiceItem item = new ChoiceItem( stringPart, imagePart, this.choiceType, elementStyle );
		return append( item, elementStyle );
	}
	
	/**
	 * Appends a ChoiceItem to this choice group.
	 * 
	 * @param item the item
	 * @return the assigned index of the element
	 */
	public int append( ChoiceItem item ) {
		return append( item, null );
	}
	/**
	 * Appends a ChoiceItem to this choice group.
	 * 
	 * @param item the item
	 * @param elementStyle the style of the item, ignored when null
	 * @return the assigned index of the element
	 */
	public int append( ChoiceItem item, Style elementStyle ) {
		add( item );
		if ( elementStyle != null ) {
			item.setStyle( elementStyle );
		}
		//#ifdef polish.usePopupItem
			//# if (this.isPopup && this.isPopupClosed && this.selectedIndex == -1) {
				//# this.popupItem.setText( item.text );
				//# this.selectedIndex = 0;
			//# }
		//#endif
		return this.itemsList.size() - 1;
	}

	/**
	 * Inserts an element into the <code>ChoiceGroup</code> 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
	 * @see Choice#insert(int, String, Image)  in interface Choice
	 */
	public void insert(int elementNum, String stringPart, Image imagePart)
	{
		insert( elementNum, stringPart, imagePart, null );
	}

	/**
	 * Inserts an element into the <code>ChoiceGroup</code> 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
	 * @param elementStyle the style for the inserted ChoiceItem
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 * @throws NullPointerException if stringPart is null
	 * @see Choice#insert(int, String, Image)  in interface Choice
	 */
	public void insert(int elementNum, String stringPart, Image imagePart, Style elementStyle)
	{
		ChoiceItem item = new ChoiceItem( stringPart, imagePart, this.choiceType, elementStyle );
		add(elementNum, item);
	}

	/**
	 * Inserts an element into the <code>ChoiceGroup</code> just prior to
	 * the element specified.
	 * 
	 * @param elementNum the index of the element where insertion is to occur
	 * @param item ChoiceItem of the element to be inserted
	 * @throws IndexOutOfBoundsException if elementNum is invalid
	 */
	public void insert(int elementNum, ChoiceItem item)
	{
		add(elementNum, item);
	}

	/**
	 * Sets the <code>String</code> and <code>Image</code> parts of the
	 * element referenced by <code>elementNum</code>,
	 * 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
	 * @see Choice#set(int, String, Image) in interface Choice
	 */
	public void set(int elementNum, String stringPart, Image imagePart)
	{
		set( elementNum, stringPart, imagePart, null );
	}

	/**
	 * Sets the <code>String</code> and <code>Image</code> parts of the
	 * element referenced by <code>elementNum</code>,
	 * replacing the previous contents of the element.
	 * 
	 * @param elementNum the index of the element to be set