list.java

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

//#condition polish.usePolishGui
// generated by de.enough.doc2java.Doc2Java (www.enough.de) on Sat Dec 06 15:06:45 CET 2003
/*
 * Copyright (c) 2004-2005 Robert Virkus / Enough Software
 *
 * This file is part of J2ME Polish.
 *
 * J2ME Polish is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * J2ME Polish is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with J2ME Polish; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * Commercial licenses are also available, please
 * refer to the accompanying LICENSE.txt or visit
 * http://www.j2mepolish.org for details.
 */
package de.enough.polish.ui;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Font;
import javax.microedition.lcdui.Image;

import de.enough.polish.util.ArrayList;
import de.enough.polish.util.Locale;


/**
 * A Screen containing list of choices.
 * 
 * The dynamic CSS selector is "list".
 * 
 * A <code>Screen</code> containing list of choices. Most of its
 * behavior is common with
 * class <A HREF="../../../javax/microedition/lcdui/ChoiceGroup.html"><CODE>ChoiceGroup</CODE></A>, and their common API. The
 * different <code>List</code> types in particular, are defined in
 * interface <A HREF="../../../javax/microedition/lcdui/Choice.html"><CODE>Choice</CODE></A>.  When a <code>List</code> is present on the display, the
 * user can interact with
 * it by selecting elements and possibly by traversing and scrolling among
 * them.  Traversing and scrolling operations do not cause application-visible
 * events. The system notifies the application only when a <A HREF="../../../javax/microedition/lcdui/Command.html"><CODE>Command</CODE></A> is invoked by notifying its <A HREF="../../../javax/microedition/lcdui/CommandListener.html"><CODE>CommandListener</CODE></A>.  The
 * <code>List</code>
 * class also supports a select command that may be invoked specially
 * depending upon the capabilities of the device.
 * 
 * <p>The notion of a <em>select</em> operation on a <code>List</code>
 * element is central
 * to the user's interaction with the <code>List</code>.  On devices
 * that have a dedicated
 * hardware &quot;select&quot; or &quot;go&quot; key, the select
 * operation is implemented with
 * that key.  Devices that do not have a dedicated key must provide another
 * means to do the select operation, for example, using a soft key.  The
 * behavior of the select operation within the different types of lists is
 * described in the following sections.</p>
 * 
 * <p><code>List</code> objects may be created with <code>Choice</code> types of
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#EXCLUSIVE"><CODE>Choice.EXCLUSIVE</CODE></A>, <A HREF="../../../javax/microedition/lcdui/Choice.html#MULTIPLE"><CODE>Choice.MULTIPLE</CODE></A>, and
 * <A HREF="../../../javax/microedition/lcdui/Choice.html#IMPLICIT"><CODE>Choice.IMPLICIT</CODE></A>.  The <code>Choice</code> type <A HREF="../../../javax/microedition/lcdui/Choice.html#POPUP"><CODE>Choice.POPUP</CODE></A>
 * is not allowed on <code>List</code> objects.</p>
 * 
 * <h3>Selection in <code>EXCLUSIVE</code> and <code>MULTIPLE</code> Lists</h3>
 * 
 * <p>The select operation is not associated with a
 * <code>Command</code> object, so the
 * application has no means of setting a label for it or being notified when
 * the operation is performed.  In <code>Lists</code> of type
 * <code>EXCLUSIVE</code>, the select
 * operation selects the target element and deselects the previously selected
 * element.  In <code>Lists</code> of type <code>MULTIPLE</code>, the
 * select operation toggles the
 * selected state of the target element, leaving the selected state of other
 * elements unchanged.  Devices that implement the select operation using a
 * soft key will need to provide a label for it.  The label should be something
 * similar to &quot;Select&quot; for <code>Lists</code> of type
 * <code>EXCLUSIVE</code>, and it should be something
 * similar to &quot;Mark&quot; or &quot;Unmark&quot; for
 * <code>Lists</code> of type <code>MULTIPLE</code>.</p>
 * 
 * <h3>Selection in <code>IMPLICIT</code> Lists</h3>
 * 
 * <p>The select operation is associated with a <code>Command</code>
 * object referred to as
 * the <em>select command</em>.  When the user performs the select operation,
 * the system will invoke the select command by notifying the
 * <code>List's</code> <CODE>CommandListener</CODE>.  The default select command is the
 * system-provided command <code>SELECT_COMMAND</code>.  The select
 * command may be modified
 * by the application through use of the <A HREF="../../../javax/microedition/lcdui/List.html#setSelectCommand(javax.microedition.lcdui.Command)"><CODE>setSelectCommand</CODE></A> method.  Devices that implement the select
 * operation using a soft key will use the label from the select command.  If
 * the select command is <code>SELECT_COMMAND</code>, the device may
 * choose to provide its
 * own label instead of using the label attribute of
 * <code>SELECT_COMMAND</code>.
 * Applications should generally provide their own select command to replace
 * <code>SELECT_COMMAND</code>.  This allows applications to provide a
 * meaningful label,
 * instead of relying on the one provided by the system for
 * <code>SELECT_COMMAND</code>.
 * The implementation must <em>not</em> invoke the select command if there are
 * no elements in the <code>List</code>, because if the
 * <code>List</code> is empty the selection does
 * not exist.  In this case the implementation should remove or disable the
 * select command if it would appear explicitly on a soft button or in a menu.
 * Other commands can be invoked normally when the <code>List</code>
 * is empty.</p>
 * 
 * <h3>Use of <code>IMPLICIT</code> Lists</h3>
 * 
 * <p> <code>IMPLICIT</code> <code>Lists</code> can be used to
 * construct menus by providing operations
 * as <code>List</code> elements.  The application provides a
 * <code>Command</code> that is used to
 * select a <code>List</code> element and then defines this
 * <code>Command</code> to be used as the
 * select command.  The application must also register a
 * <code>CommandListener</code> that
 * is called when the user selects or activates the <code>Command</code>:</p>
 * 
 * <TABLE BORDER="2">
 * <TR>
 * <TD ROWSPAN="1" COLSPAN="1">
 * <pre><code>
 * String[] elements = { ... }; //Menu items as List elements
 * List menuList = new List("Menu", List.IMPLICIT, elements, null);
 * Command selectCommand = new Command("Open", Command.ITEM, 1);
 * menuList.setSelectCommand(selectCommand);
 * menuList.setCommandListener(...);     </code></pre>
 * </TD>
 * </TR>
 * </TABLE>
 * 
 * <p>The listener can query the <code>List</code> to determine which
 * element is selected
 * and then perform the corresponding action.  Note that setting a command as
 * the select command adds it to the <code>List</code> as a side effect.</p>
 * 
 * <p> The select command should be considered as a <em>default operation</em>
 * that takes place when a select key is pressed.  For example, a
 * <code>List</code>
 * displaying email headers might have three operations: read, reply, and
 * delete. Read is considered to be the default operation.  </p>
 * 
 * <pre><code>
 * List list = new List("Email", List.IMPLICIT, headers);
 * readCommand = new Command("Read", Command.ITEM, 1);
 * replyCommand = new Command("Reply", Command.ITEM, 2);
 * deleteCommand = new Command("Delete", Command.ITEM, 3);
 * list.setSelectCommand(readCommand);
 * list.addCommand(replyCommand);
 * list.addCommand(deleteCommand);
 * list.setCommandListener(...);     
 * </code></pre>
 * 
 * <p>On a device with a dedicated select key, pressing this key will invoke
 * <code>readCommand</code>.  On a device without a select key, the user is
 * still able to invoke the read command, since it is also provided as an
 * ordinary <code>Command</code>.</p>
 * 
 * <p> It should be noted that this kind of default operation must be used
 * carefully, and the usability of the resulting user interface must always
 * kept in mind. The default operation should always be the most intuitive
 * operation on a particular List.  </p>
 * <HR>
 * 
 * 
 * @since MIDP 1.0
 */
public class List extends Screen implements Choice
{
	/**
	 * The default select command for <code>IMPLICIT</code> <code>Lists</code>.
	 * Applications using an <code>IMPLICIT</code> <code>List</code>
	 * should set their own select command
	 * using
	 * <A HREF="../../../javax/microedition/lcdui/List.html#setSelectCommand(javax.microedition.lcdui.Command)"><CODE>setSelectCommand</CODE></A>.
	 * 
	 * <p>
	 * The field values of <code>SELECT_COMMAND</code> are:<br>
	 * - <code>label = &quot;&quot;</code> (an empty string)<br>
	 * - <code>type = SCREEN</code><br>
	 * - <code>priority = 0</code><br>
	 * </p>
	 * <p>(It would be more appropriate if the type were
	 * <code>ITEM</code>, but the type of
	 * <code>SCREEN</code> is retained for historical purposes.)</p>
	 * <p>
	 * The application should not use these values for recognizing
	 * the <code>SELECT_COMMAND</code>. Instead, object identities of
	 * the <code>Command</code> and
	 * <code>Displayable</code> (<code>List</code>) should be used.
	 * </p>
	 * 
	 * <p><code>SELECT_COMMAND</code> is treated as an ordinary
	 * <code>Command</code> if it is used with other <code>Displayable</code>
	 * types.</p>
	 */
	//#ifdef polish.i18n.useDynamicTranslations
		//# public static Command SELECT_COMMAND = new Command( "Select", Command.ITEM, 3 );
	//#elifdef polish.command.select:defined
public static final Command SELECT_COMMAND = new Command("Select", Command.ITEM, 3 );
	//#else
		//# public static final Command SELECT_COMMAND = new Command( "Select", Command.ITEM, 3 );
	//#endif

	private Command selectCommand = SELECT_COMMAND;
	private int listType;
	private ChoiceGroup choiceGroup;
	//#ifdef polish.css.show-text-in-title
		//# private ArrayList titles;
		//# private boolean showTextInTitle;
	//#endif

	/**
	 * Creates a new, empty <code>List</code>, specifying its title
	 * and the type of the list.
	 * 
	 * @param title the screen's title (see Displayable)
	 * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @throws IllegalArgumentException if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @see Choice
	 */
	public List( String title, int listType)
	{
		this( title, listType, new String[0], null, null );
	}

	/**
	 * Creates a new, empty <code>List</code>, specifying its title
	 * and the type of the
	 * list.
	 * 
	 * @param title the screen's title (see Displayable)
	 * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @param style the style of this list
	 * @throws IllegalArgumentException if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @see Choice
	 */
	public List( String title, int listType, Style style)
	{
		this( title, listType, new String[0], new Image[0], style );
	}

	/**
	 * Creates a new <code>List</code>, specifying its title, the type
	 * of the <code>List</code>, and
	 * an array of <code>Strings</code> and <code>Images</code> to be
	 * used as its initial contents.
	 * 
	 * <p>The <code>stringElements</code> array must be non-null and
	 * every array element
	 * must also be non-null.  The length of the
	 * <code>stringElements</code> array
	 * determines the number of elements in the <code>List</code>.
	 * The <code>imageElements</code> array
	 * may be <code>null</code> to indicate that the <code>List</code>
	 * elements have no images.  If the
	 * <code>imageElements</code> array is non-null, it must be the
	 * same length as the
	 * <code>stringElements</code> array.  Individual elements of the
	 * <code>imageElements</code> array
	 * may be <code>null</code> in order to indicate the absence of an
	 * image for the
	 * corresponding <code>List</code> element. Non-null elements of the
	 * <code>imageElements</code> array may refer to mutable or
	 * immutable images.</p>
	 * 
	 * @param title the screen's title (see Displayable)
	 * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @param stringElements set of strings specifying the string parts of the List elements
	 * @param imageElements set of images specifying the image parts of the List elements
	 * @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
	 *         or if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @see Choice#EXCLUSIVE
	 * @see Choice#MULTIPLE
	 * @see Choice#IMPLICIT
	 */
	public List( String title, int listType, String[] stringElements, Image[] imageElements)
	{
		this( title, listType, stringElements, imageElements, null );
	}

	/**
	 * Creates a new <code>List</code>, specifying its title, the type
	 * of the <code>List</code>, and
	 * an array of <code>Strings</code> and <code>Images</code> to be
	 * used as its initial contents.
	 * 
	 * <p>The <code>stringElements</code> array must be non-null and
	 * every array element
	 * must also be non-null.  The length of the
	 * <code>stringElements</code> array
	 * determines the number of elements in the <code>List</code>.
	 * The <code>imageElements</code> array
	 * may be <code>null</code> to indicate that the <code>List</code>
	 * elements have no images.  If the
	 * <code>imageElements</code> array is non-null, it must be the
	 * same length as the
	 * <code>stringElements</code> array.  Individual elements of the
	 * <code>imageElements</code> array
	 * may be <code>null</code> in order to indicate the absence of an
	 * image for the
	 * corresponding <code>List</code> element. Non-null elements of the
	 * <code>imageElements</code> array may refer to mutable or
	 * immutable images.</p>
	 * 
	 * @param title the screen's title (see Displayable)
	 * @param listType one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @param stringElements set of strings specifying the string parts of the List elements
	 * @param imageElements set of images specifying the image parts of the List elements
	 * @param style the style of this list
	 * @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
	 *         or if listType is not one of IMPLICIT, EXCLUSIVE, or MULTIPLE
	 * @see Choice#EXCLUSIVE
	 * @see Choice#MULTIPLE
	 * @see Choice#IMPLICIT
	 */
	public List( String title, int listType, String[] stringElements, Image[] imageElements, Style style)
	{
		this( title, listType, ChoiceGroup.buildChoiceItems(stringElements, imageElements, listType, style), style);
//		super( title, style, false );
//		//#ifndef polish.skipArgumentCheck
//			if (listType != Choice.EXCLUSIVE && listType != Choice.MULTIPLE && listType != Choice.IMPLICIT ) {
//				//#ifdef polish.debugVerbose
//					throw new IllegalArgumentException("invalid list-type: " + listType );
//				//#else
//					//# throw new IllegalArgumentException();