textbox.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 437 行 · 第 1/2 页

/*
 *   
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program 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 version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package javax.microedition.lcdui;

/**
 * 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 {@link #getMaxSize() getMaxSize()}.  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 {@link TextField#ANY}
 * 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 {@link
 * TextField TextField}
 * 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.
 * 
 * @since MIDP 1.0
 */

public class TextBox extends Screen {

    /**
     * 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,
     * <code>null</code> 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 {@link #getMaxSize()}.
     * @param constraints see <a href="TextField.html#constraints">input
     * constraints</a>
     *
     * @throws IllegalArgumentException if <code>maxSize</code> is zero or less
     * @throws IllegalArgumentException if the <code>constraints</code>
     * parameter is invalid
     * @throws IllegalArgumentException if <code>text</code> is illegal
     * for the specified constraints
     * @throws IllegalArgumentException if the length of the string exceeds
     * the requested maximum capacity
     */
    public TextBox(String title, String text, int maxSize, int constraints) {
        super(title);

        synchronized (Display.LCDUILock) {

            textField = new TextField(null, text, maxSize, constraints, true);
            textField.lSetOwner(this);

            displayableLF = textBoxLF = LFFactory.getFactory().getTextBoxFormLF(this);
        }
    }

    /**
     * Gets the contents of the <code>TextBox</code> as a string value.
     *
     * @return the current contents
     * @see #setString
     */
    public String getString() {
        return textField.getString();
    }

    /**
     * Sets the contents of the <code>TextBox</code> as a string
     * value, replacing the previous contents.
     *
     * @param text the new value of the <code>TextBox</code>, or
     * <code>null</code> if the <code>TextBox</code> is to 
     * be made empty
     * @throws IllegalArgumentException if <code>text</code>
     * is illegal for the current 
     * <a href="TextField.html#constraints">input constraints</a>
     * @throws IllegalArgumentException if the text would exceed the current
     * maximum capacity
     * @see #getString
     */
    public void setString(String text) {
        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 <code>data</code> is <code>null</code>
     * @see #setChars
     */
    public int getChars(char[] data) {
        return 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>
     * 
     * @param data the source of the character data
     * @param offset the beginning of the region of characters to copy
     * @param length the number of characters to copy
     * @throws ArrayIndexOutOfBoundsException if <code>offset</code>
     * and <code>length</code> do not specify
     * a valid range within the data array
     * @throws IllegalArgumentException if <code>data</code>
     * is illegal for the current 
     * <a href="TextField.html#constraints">input constraints</a>
     * @throws IllegalArgumentException if the text would exceed the current
     * maximum capacity
     * @see #getChars
     */
    public void setChars(char[] data, int offset, int length) {
        textField.setChars(data, offset, length);
    }

    /**
     * Inserts a string into the contents of the <code>TextBox</code>.