textbox.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;


/**
 * The <code>TextBox</code> class is a <code>Screen</code> that allows the user to enter and edit text.
 * 
 * <p>A <code>TextBox</code> has a maximum size, which is the maximum
 * number of characters
 * that can be stored in the object at any time (its capacity). This limit is
 * enforced when the <code>TextBox</code> instance is constructed,
 * when the user is editing text within the <code>TextBox</code>, as well as
 * when the application program calls methods on the
 * <code>TextBox</code> that modify its
 * contents. The maximum size is the maximum stored capacity and is unrelated
 * to the number of characters that may be displayed at any given time.
 * The number of characters displayed and their arrangement into rows and
 * columns are determined by the device. </p>
 * 
 * <p>The implementation may place a boundary on the maximum size, and the
 * maximum size actually assigned may be smaller than the application had
 * requested.  The value actually assigned will be reflected in the value
 * returned by <A HREF="../../../javax/microedition/lcdui/TextBox.html#getMaxSize()"><CODE>getMaxSize()</CODE></A>.  A defensively-written
 * application should compare this value to the maximum size requested and be
 * prepared to handle cases where they differ.</p>
 * 
 * <p>The text contained within a <code>TextBox</code> may be more
 * than can be displayed at
 * one time. If this is the case, the implementation will let the user scroll
 * to view and edit any part of the text. This scrolling occurs transparently
 * to the application. </p>
 * 
 * <p>If the constraints are set to <A HREF="../../../javax/microedition/lcdui/TextField.html#ANY"><CODE>TextField.ANY</CODE></A>
 * The text may contain <A HREF="Form.html#linebreak">line breaks</A>.
 * The display of the text must break accordingly and the user must be
 * able to enter line break characters. </p>
 * 
 * <p><code>TextBox</code> has the concept of
 * <em>input constraints</em> that is identical to
 * <code>TextField</code>. The <code>constraints</code> parameters of
 * methods within the
 * <code>TextBox</code> class use constants defined in the <A HREF="../../../javax/microedition/lcdui/TextField.html"><CODE>TextField</CODE></A>
 * class. See the description of
 * <a href="TextField.html#constraints">input constraints</a>
 * in the <code>TextField</code> class for the definition of these
 * constants.  <code>TextBox</code> also has the same notions as
 * <code>TextField</code> of the <em>actual contents</em> and the
 * <em>displayed contents</em>, described in the same section.
 * </p>
 * 
 * <p><code>TextBox</code> also has the concept of <em>input
 * modes</em> that is identical
 * to <code>TextField</code>. See the description of <a
 * href="TextField.html#modes">input
 * modes</a> in the <code>TextField</code> class for more details.
 * <HR>
 * 
 * 
 * @since MIDP 1.0
 */
public class TextBox extends Screen
{
	
	protected TextField textField;

	/**
	 * Creates a new <code>TextBox</code> object with the given title
	 * string, initial
	 * contents, maximum size in characters, and constraints.
	 * If the text parameter is <code>null</code>, the
	 * <code>TextBox</code> is created empty.
	 * The <code>maxSize</code> parameter must be greater than zero.
	 * An <code>IllegalArgumentException</code> is thrown if the
	 * length of the initial contents string exceeds <code>maxSize</code>.
	 * However,
	 * the implementation may assign a maximum size smaller than the
	 * application had requested.  If this occurs, and if the length of the
	 * contents exceeds the newly assigned maximum size, the contents are
	 * truncated from the end in order to fit, and no exception is thrown.
	 * 
	 * @param title the title text to be shown with the display
	 * @param text the initial contents of the text editing area, null may be used to indicate no initial content
	 * @param maxSize the maximum capacity in characters. The implementation may limit boundary maximum capacity and the actually assigned capacity may me smaller than requested. A defensive application will test the actually given capacity with getMaxSize().
	 * @param constraints see input constraints
	 * @throws IllegalArgumentException if maxSize is zero or less
	 * 				or if the constraints parameter is invalid
	 * 				or if text is illegal for the specified constraints
	 * 				or if the length of the string exceeds the requested maximum capacity
	 */
	public TextBox( String title, String text, int maxSize, int constraints)
	{
		this( title, text, maxSize, constraints, null );
	}

	/**
	 * Creates a new <code>TextBox</code> object with the given title
	 * string, initial
	 * contents, maximum size in characters, and constraints.
	 * If the text parameter is <code>null</code>, the
	 * <code>TextBox</code> is created empty.
	 * The <code>maxSize</code> parameter must be greater than zero.
	 * An <code>IllegalArgumentException</code> is thrown if the
	 * length of the initial contents string exceeds <code>maxSize</code>.
	 * However,
	 * the implementation may assign a maximum size smaller than the
	 * application had requested.  If this occurs, and if the length of the
	 * contents exceeds the newly assigned maximum size, the contents are
	 * truncated from the end in order to fit, and no exception is thrown.
	 * 
	 * @param title the title text to be shown with the display
	 * @param text the initial contents of the text editing area, null may be used to indicate no initial content
	 * @param maxSize the maximum capacity in characters. The implementation may limit boundary maximum capacity and the actually assigned capacity may me smaller than requested. A defensive application will test the actually given capacity with getMaxSize().
	 * @param constraints see input constraints
	 * @param style the style for this screen
	 * @throws IllegalArgumentException if maxSize is zero or less
	 * 				or if the constraints parameter is invalid
	 * 				or if text is illegal for the specified constraints
	 * 				or if the length of the string exceeds the requested maximum capacity
	 */
	public TextBox( String title, String text, int maxSize, int constraints, Style style)
	{
		super( title, style, true );
		this.textField = new TextField( null, text, maxSize, constraints, style );
		if (title != null) {
			this.textField.title = title;
		}
		this.container.add( this.textField );
	}
	
	/**
	 * Gets the contents of the <code>TextBox</code> as a string value.
	 * 
	 * @return the current contents
	 * @see #setString(java.lang.String)
	 */
	public String getString()
	{
		return this.textField.getText();
	}

	/**
	 * Sets the contents of the <code>TextBox</code> as a string
	 * value, replacing the previous contents.
	 * 
	 * @param text the new value of the TextBox, or null if the TextBox is to be made empty
	 * @throws IllegalArgumentException if text is illegal for the current input constraints
	 * 									or if the text would exceed the current maximum capacity
	 * @see #getString()
	 */
	public void setString( String text)
	{
		this.textField.setString(text);
	}

	/**
	 * Copies the contents of the <code>TextBox</code> into a
	 * character array starting at
	 * index zero. Array elements beyond the characters copied are left
	 * unchanged.
	 * 
	 * @param data the character array to receive the value
	 * @return the number of characters copied
	 * @throws ArrayIndexOutOfBoundsException - if the array is too short for the contents
	 * @throws NullPointerException - if data is null
	 * @see #setChars(char[], int, int)
	 */
	public int getChars(char[] data)
	{
		return this.textField.getChars(data);
	}

	/**
	 * Sets the contents of the <code>TextBox</code> from a character
	 * array, replacing the
	 * previous contents. Characters are copied from the region of the
	 * <code>data</code> array
	 * starting at array index <code>offset</code> and running for
	 * <code>length</code> characters.
	 * If the data array is <code>null</code>, the <code>TextBox</code>
	 * is set to be empty and the other parameters are ignored.
	 * 
	 * <p>The <code>offset</code> and <code>length</code> parameters must
	 * specify a valid range of characters within
	 * the character array <code>data</code>.
	 * The <code>offset</code> parameter must be within the
	 * range <code>[0..(data.length)]</code>, inclusive.
	 * The <code>length</code> parameter
	 * must be a non-negative integer such that
	 * <code>(offset + length) &lt;= data.length</code>.</p>