inputmode.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 291 行

/*
 *  
 *
 * 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 com.sun.midp.chameleon.input;
import javax.microedition.lcdui.Displayable;

/**
 * An interface to a text input mode, such as alphanumeric, numeric, etc. 
 *
 * Before sending key input to any InputMode, it should be verified that
 * it supports the input constraints of the target text component. This is
 * done by verifying that the input constraints of the text component
 * (as defined in the MIDP specification for TextField) are supported by
 * this InputMode by calling its supportsConstraints() method.
 *
 * The display name of this InputMode is returned by the getName() method.
 * This value should be a locale appropriate value and suitable for 
 * displaying on the screen, such as an option on the device's system
 * menu.
 *
 * The remaining methods represent a simple state machine with the following
 * characteristics:
 *
 * To begin an input session, the first call MUST be beginInput(). This 
 * establishes an input session with this InputMode and allows the InputMode
 * to perform any session initialization needed. The parameter to beginInput()
 * is the InputModeMediator for the input session. The InputModeMediator is
 * a callback mechanism for the InputMode to automatically commit pending
 * input as well as end the input session.
 *   
 * Subsequent key input is passed to the InputMode via the processKey()
 * method. This method returns a String element. The returned String
 * represents the best possible input value based on the total key input 
 * during the input session. For example, for an AlphaNumeric InputMode, 
 * the pending input will only ever be a single String, representing
 * the character that corresponds to the last key entered. A 'null' return 
 * value from processKey() is an indication that this InputMode did not 
 * process the key at all, and it may need to be processed by other elements
 *  of the system. 
 * 
 * For a predictive
 * text InputMode such as T9, there could be several possible matches.
 * The return value from processKey() in this instance will be what the
 * system believes to be the best possible match. The return value of
 * the hasMoreMatches() method will indicate whether the InputMode has
 * more than one possible match to the given input. The matches can then
 * be retrieved using the getNextMatch() method. 
 *
 * Key processing should be considered complete after the call to the
 * InputMode's endInput() method. At this point, the InputMode should
 * consider the reference to the TextInputMediator passed to its
 * beginInput() method to be no longer valid. 
 *
 * The InputMode may itself at any time commit pending input by calling the
 * InputModeMediator's commitInput() method. The InputMode may also end
 * the input session by calling the inputModeCompleted() method. Calling
 * this method will result in a subsequent call to this InputMode's 
 * endInput() method.
 *
 * A typical call exchange with an InputMode could go as follows:
 *
 * InputMode im = ...;
 * im.beginInput(inputModeHandler);
 *
 * int res = im.processKey([key code for 4]);
 * if (pendingInput == null) {
 *     // The InputMode could not process the key code
 * } else {
 *     // Present the pendingInput value to the user as the
 *     // best possible match
 *     ...
 *     while (im.hasMoreMatches()) {
 *         pendingInput = im.getNextMatch();
 *         // Present the pendingInput value to the user as
 *         // the best possible match
 *     }
 * }
 *
 * im.endInput();
 */
public interface InputMode {

    /** The key code does not mean to be displayed */
    public static final int KEYCODE_INVISIBLE = -4;

    /**
     * The key code is not handled by the input mode.
     * Most likely it is handled by the text component */
    public static final int KEYCODE_NONE = -3; // dont clash

    /** 
     * a sub-inputMode which may be supported by an InputMode.
     * all letters are uppercase  
     */
    public static final int CAPS_ON = 1;

    /** 
     * a sub-inputMode which may be supported by an InputMode.
     * all letters are lowercase  
     */
    public static final int CAPS_OFF = 2;

    /** 
     * a sub-inputMode which may be supported by an InputMode.
     * the first letter is capitalized, the rest of the letters are lowercase  
     */
    public static final int CAPS_SENTENCE = 3;

    /** The limitation for the number of matches */
    public static final int MAX_MATCHES = 20;

    
    /**
     * This method is called to determine if this InputMode supports
     * the given text input constraints. The semantics of the constraints
     * value are defined in the javax.microedition.lcdui.TextField API. 
     * If this InputMode returns false, this InputMode must not be used
     * to process key input for the selected text component.
     *
     * @param constraints text input constraints. The semantics of the 
     * constraints value are defined in the TextField API.
     *
     * @return true if this InputMode supports the given text component
     *         constraints, as defined in the MIDP TextField API
     */
    public boolean supportsConstraints(int constraints);
    
    /**
     * Returns the display name which will represent this InputMode to 
     * the user, such as in a selection list or the softbutton bar.
     *
     * @return the locale-appropriate name to represent this InputMode
     *         to the user
     */
    public String getName();

    /**
     * Returns the command name which will represent this InputMode in
     * the input menu
     *
     * @return the locale-appropriate name to represent this InputMode
     *         to the user
     */
    public String getCommandName();
    
    /**
     * This method will be called before any input keys are passed
     * to this InputMode to allow the InputMode to perform any needed
     * initialization. A reference to the InputModeMediator which is
     * currently managing the relationship between this InputMode and
     * the input session is passed in. This reference can be used
     * by this InputMode to commit text input as well as end the input
     * session with this InputMode. The reference is only valid until
     * this InputMode's endInput() method is called.
     *
     * @param constraints text input constraints. The semantics of the 
     * constraints value are defined in the TextField API.
     *
     * @param mediator the InputModeMediator which is negotiating the
     *        relationship between this InputMode and the input session
     *
     * @param inputSubset current input subset
     */
    public void beginInput(InputModeMediator mediator, String inputSubset,
                           int constraints) 
        throws IllegalStateException;
    
    /**
     * Process the given key code as input.
     * 
     * This method will return true if the key was processed successfully,
     * false otherwise.
     *
     * @param keyCode the keycode of the key which was input
     * @param longPress return true if it's long key press otherwise false
     * @return the key code if the key has been committed for the input, or
     * KEYCODE_NONE if the key has not been habdled by the input mode, or
     * KEYCODE_INVISIBLE if the key has been handled by the input mode but
     * this key has not been displayed
     */
    public int processKey(int keyCode, boolean longPress) 
        throws IllegalStateException;

    /**
     * return the pending char
     * used to bypass the asynchronous commit mechanism
     * e.g. to immediately commit a char before moving the cursor
     * @return return the pending char
     */
    public char getPendingChar();

    /**
     * Return the next possible match for the key input processed thus
     * far by this InputMode. A call to this method should be preceeded
     * by a check of hasMoreMatches(). If the InputMode has more available
     * matches for the given input, this method will return them one by one.
     *
     * @return a String representing the next available match to the key 
     *         input thus far, or 'null' if no pending input is available
     */
    public String getNextMatch();
        
    /**
     * True, if after processing a key, there is more than one possible
     * match to the input. If this method returns true, the getNextMatch()
     * method can be called to return the value.
     *
     * @return true if after processing a key, there is more than the one
     *         possible match to the given input
     */
    public boolean hasMoreMatches();


    /**
     * Gets the possible string matches 
     *
     * @return returns the set of options.
     */
    public String[] getMatchList();
    
    /**
     * Mark the end of this InputMode's processing. The only possible call
     * to this InputMode after a call to endInput() is a call to beginInput()
     * to begin a new input session.
     */
    public void endInput() 
        throws IllegalStateException;

    /**
     * Gets displayable for particular input method. If the input method has no
     * specific displayable representation returns null.  
     * @return displayable 
     */
    public Displayable getDisplayable(); 
    

    /** 
     * Returns true if input mode is using its own displayable, false ifinput
     * mode does not require the speial displayable for its representation 
     * @return true if input mode is using its own displayable, otherwise false
     */
    public boolean hasDisplayable();

    /**
     * Returns the map specifying this input mode is proper one for the
     * particular pair of input subset and constraint. The form of the map is
     *
     *                       |ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL|
     * ---------------------------------------------------------------------
     * IS_FULLWIDTH_DIGITS   |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_FULLWIDTH_LATIN    |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_HALFWIDTH_KATAKANA |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_HANJA              |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_KANJI              |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_LATIN              |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_LATIN_DIGITS       |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_SIMPLIFIED_HANZI   |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * IS_TRADITIONAL_HANZI  |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * MIDP_UPPERCASE_LATIN  |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * MIDP_LOWERCASE_LATIN  |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     * NULL                  |t|f|   t|f   |  t|f  |    t|f    |t|f|  t|f  |
     *
     * @return input subset x constraint map
     */
    public boolean[][] getIsConstraintsMap();
}