textbox.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)TextBox.java	1.186 01/08/10
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */

package javax.microedition.lcdui;

import com.sun.midp.lcdui.InputMethodClient;
import com.sun.midp.lcdui.InputMethodHandler;
import com.sun.midp.lcdui.EventHandler;

/**
 * <p>The TextBox class is a Screen that allows the user to enter and edit 
 * text.</p>
 *
 * <p>A TextBox 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 TextBox instance is constructed,
 * when the user is editing text within the TextBox, as well as
 * when the application program calls methods on the TextBox 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 TextBox 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>TextBox has the concept of <em>input constraints</em> that is identical to
 * TextField. The <code>constraints</code> parameters of methods within the
 * TextBox class use constants defined in the {@link TextField TextField}
 * class. See the description of
 * <a href="TextField.html#constraints">input constraints</a>
 * in the TextField class for the definition of these constants.</p>
 */
public class TextBox extends Screen {

    /** Internal flag representing the enabled state of the cursor */
    private boolean cursorEnabled = true;
    /** Special set of keyboard characters */
    private char[] keyBoardChar = new char[1];
    /** Internal text handler */
    TextBasic sD;
   
    /**
     * Creates a new TextBox object with the given title string, initial
     * contents, maximum size in characters, and constraints.
     * If the text parameter is null, the TextBox is created empty.
     * The maxSize parameter must be greater than zero.
     *
     * @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 {@link #getMaxSize()}.
     * @param constraints see <a href="TextField.html#constraints">
     * input constraints</a>
     *
     * @throws IllegalArgumentException if maxSize is zero or less
     * @throws IllegalArgumentException if the constraints parameter
     * is invalid
     * @throws IllegalArgumentException if text is illegal
     * for the specified constraints
     * @throws IllegalArgumentException if the length of the string exceeds
     * the requested maximum capacity
     * or the maximum capacity actually assigned
     */
    public TextBox(String title, String text, int maxSize, int constraints) {
        super(title);
        synchronized (Display.LCDUILock) {
            initializeTextBasic(constraints, maxSize, text);
            hasBorder = true;
        }
    }

    /**
     * Gets the contents of the TextBox as a string value.
     *
     * @return the current contents
     *
     * @see #setString
     */
    public String getString() {
        synchronized (Display.LCDUILock) {
            return new String(sD.buffer, 0, sD.numChars);
        }
        // garbage unavoidable
    }

    /**
     * Sets the contents of the TextBox 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 the text 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) {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0, sD.setString(text));
        }
    }
    
    /**
     * Copies the contents of the TextBox 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) {
        synchronized (Display.LCDUILock) {
            return sD.getChars(data);
        }
    }

    /**
     * Sets the contents of the TextBox 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 null, the TextBox
     * is set to be empty and the other parameters are ignored.
     *
     * @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 offset and length do not
     * specify a valid range within the data array
     * @throws IllegalArgumentException if the text 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) {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0, sD.setChars(data, offset, length));
        }
    }

    /**
     * <p>Inserts a string into the contents of the TextBox.  The string is
     * inserted just prior to the character indicated by the
     * <code>position</code> parameter, where zero specifies the first
     * character of the contents of the TextBox.  If <code>position</code> is
     * less than or equal to zero, the insertion occurs at the beginning of
     * the contents, thus effecting a prepend operation.  If
     * <code>position</code> is greater than or equal to the current size of
     * the contents, the insertion occurs immediately after the end of the
     * contents, thus effecting an append operation.  For example,
     * <code>text.insert(s, text.size())</code> always appends the string 
     * s to the current contents.</p>
     * 
     * <p>The current size of the contents is increased by the number of
     * inserted characters. The resulting string must fit within the current
     * maximum capacity. </p>
     *
     * <p>If the application needs to simulate typing of characters it can
     * determining the location of the current insertion point ("caret")
     * using the with {@link #getCaretPosition() getCaretPosition()} method.  
     * For example,
     * <code>text.insert(s, text.getCaretPosition())</code> inserts the string 
     * s at the current caret position.</p>
     *
     * @param src the String to be inserted
     * @param position the position at which insertion is to occur
     * 
     * @throws IllegalArgumentException if the resulting contents are illegal
     * for the current <a href="TextField.html#constraints">
     * input constraints</a>
     * @throws IllegalArgumentException if the insertion would exceed the
     * current maximum capacity
     * @throws NullPointerException if <code>src</code> is <code>null</code>
     */
    public void insert(String src, int position)  {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0, sD.insert(src, position));
        }
    }

    /**
     * <p>Inserts a subrange of an array of characters into the contents of
     * the TextBox.  The offset and length parameters indicate the subrange of
     * the data array to be used for insertion. Behavior is otherwise
     * identical to {@link #insert(String, int) insert(String, int)}. </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
     * @param position the position at which insertion is to occur
     * 
     * @throws ArrayIndexOutOfBoundsException if offset and length do not
     * specify a valid range within the data array
     * @throws IllegalArgumentException if the resulting contents are illegal
     * for the current <a href="TextField.html#constraints">
     * input constraints</a>
     * @throws IllegalArgumentException if the insertion would exceed the 
     * current maximum capacity
     * @throws NullPointerException if <code>data</code> is <code>null</code>
     */
    public void insert(char[] data, int offset, int length, int position)  {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0,
                           sD.insert(data, offset, length, position));
        }
    }

    /**
     * <p>Deletes characters from the TextBox.</p>
     *
     * @param offset the beginning of the region to be deleted
     * @param length the number of characters to be deleted
     *
     * @throws StringIndexOutOfBoundsException if offset and length do not
     * specify a valid range within the contents of the TextBox
     */
    public void delete(int offset, int length) {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0, sD.deleteChars(offset, length));
        }
    }

    /**
     * Returns the maximum size (number of characters) that can
     * be stored in this TextBox.
     * @return the maximum size in characters
     *
     * @see #setMaxSize
     */
    public int getMaxSize() {
        // SYNC NOTE: return of atomic value, no locking necessary
        synchronized (Display.LCDUILock) {
            return sD.buffer.length;
        }
    }

    /**
     * Sets the maximum size (number of characters) that can be
     * contained in this
     * TextBox. If the current contents of the TextBox are larger than
     * maxSize, the contents are truncated to fit.
     *
     * @param maxSize the new maximum size
     *
     * @return assigned maximum capacity - may be smaller than requested.
     * @throws IllegalArgumentException if maxSize is zero or less.
     *
     * @see #getMaxSize
     */
    public int setMaxSize(int maxSize)  {
        synchronized (Display.LCDUILock) {
            contentChanged(null, 0, 0, sD.setMaxSize(maxSize));
            return sD.buffer.length;
        }
    }

    /**
     * Gets the number of characters that are currently stored in this
     * TextBox.
     * @return the number of characters
     */
    public int size() {
        // returns a value relative to the display text including formatting
        synchronized (Display.LCDUILock) {
            return sD.numChars;
        }
    }

    /**
     * Gets the current input position.
     * For some UIs this may block some time and ask the user about
     * the intended caret 
     * position, on some UIs may just return the caret position.
     * @return the current caret position, 0 if in the beginning.
     */
    public int getCaretPosition() {
        // returns a value relative to the flat input text
        synchronized (Display.LCDUILock) {
            return sD.curPos;
        }
    }

    /**
     * Sets the input constraints of the TextBox. If the current contents
     * of the TextBox do not match the new constraints, the contents are
     * set to empty.
     *
     * @param constraints see
     * <a href="TextField.html#constraints">input constraints</a>
     *
     * @throws IllegalArgumentException if the value of the constraints
     * parameter is invalid
     *
     * @see #getConstraints
     */
    public void setConstraints(int constraints) {
        synchronized (Display.LCDUILock) {
            int deltaHeight = sD.setConstraints(constraints);
            deltaHeight += sD.setMaxSize(sD.buffer.length);
            contentChanged(null, 0, 0, deltaHeight);
        }
    }

    /**
     * Get the current input constraints of the TextBox.
     *
     * @return the current constraints value (see
     * <a href="TextField.html#constraints">input constraints</a>)
     *
     * @see #setConstraints
     */
    public int getConstraints() {
        synchronized (Display.LCDUILock) {
            return sD.constraints;
        }
    }

    /*
     * package private
     */

    /**
     * Initialize the internal text handler
     *
     * @param constraints The constraints on the text object
     * @param maxSize The maximum size of the text object
     * @param text The initial text of the text object
     */
    void initializeTextBasic(int constraints, int maxSize, String text) {
        sD = new TextBasic(constraints,  maxSize, text);
    }

    /**
     * Paint the content of this TextBox
     *
     * @param g The Graphics object to paint to