001: /*
002: *
003: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or have any questions.
024: */
025: package com.sun.midp.chameleon.input;
026:
027: /**
028: * The TextInputSession interface represents the relationship between the
029: * system's key input, the TextInputComponent, the available InputModes,
030: * and the graphical display.
031: */
032: public interface TextInputSession {
033: /** The names of the currently defined input subsets */
034: public static final String[] INPUT_SUBSETS = {
035: "IS_FULLWIDTH_DIGITS", "IS_FULLWIDTH_LATIN",
036: "IS_HALFWIDTH_KATAKANA", "IS_HANJA", "IS_KANJI",
037: "IS_LATIN", "IS_LATIN_DIGITS", "IS_SIMPLIFIED_HANZI",
038: "IS_TRADITIONAL_HANZI", "MIDP_UPPERCASE_LATIN",
039: "MIDP_LOWERCASE_LATIN" };
040:
041: /** max number of constraints */
042: public static final int MAX_CONSTRAINTS = 6;
043:
044: /**
045: * Start a text input session for the given TextInputComponent.
046: * The TextInputComponent can be used to determine the initial
047: * input mode, constraints, etc.
048: *
049: * @param component the TextInputComponent which is receiving text input
050: */
051: public void beginSession(TextInputComponent component);
052:
053: /**
054: * List the appropriate InputModes available for the current input
055: * session. This method may be used by UI components in order to make
056: * certain input mode choices available to the user for selection.
057: * If this handler is not currently in an active text input session,
058: * this method returns null.
059: *
060: * @return an array of InputModes which are available to use given the
061: * current TextInputComponent and its input constraints
062: */
063: public InputMode[] getAvailableModes();
064:
065: /**
066: * Retrieve the InputMode which is the current "active" mode
067: * for this TextInputSession. This does not necessarily mean there is
068: * any pending input with the InputMode itself, it means that if this
069: * TextInputSession receives key input, the returned InputMode will be
070: * the mode which processes that input.
071: *
072: * @return the currently "active" InputMode
073: */
074: public InputMode getCurrentInputMode();
075:
076: /**
077: * Set this TextInputSession's current "active" InputMode to the
078: * given mode. The given mode must be one of the InputModes listed
079: * in the array of InputModes returned from the getAvailableModes()
080: * method of this TextInputSession. Calling this method will terminate
081: * any existing input session with the current InputMode and will
082: * result in any subsequent key input being processed by the given
083: * InputMode. If the given mode is already the current "active"
084: * InputMode, this method has no effect. If this TextInputSession
085: * is not currently in an input session (ie, there is no active
086: * TextInputComponent), this method has no effect.
087: *
088: * @param mode the InputMode to switch key processing to
089: */
090: public void setCurrentInputMode(InputMode mode);
091:
092: /**
093: * This method abstracts key processing to a single call (from
094: * the assorted key press, release, repeat events). This method
095: * should be called from the TextInputComponent to pass along
096: * key input from the user. The TextInputComponent is responsible
097: * for determining what key events should be processed (ie,
098: * key events trigger processing on press or on release).
099: *
100: * @param keyCode the numeric code representing the key which was
101: * pressed
102: * @param longPress return true if it's long key press otherwise false
103: * @return true if the current InputMode processed the key event,
104: * false if the key was not processed at all by the current
105: * InputMode (not all keys apply to input)
106: */
107: public int processKey(int keyCode, boolean longPress);
108:
109: /**
110: * return the pending char
111: * used to bypass the asynchronous commit mechanism
112: * e.g. to immediately commit a char before moving the cursor
113: *
114: * @return return the pending char
115: */
116: public char getPendingChar();
117:
118: /**
119: * An iterative method to return the next available match given
120: * the key processing thus far. If the return value of hasMoreMatches()
121: * is true, this method will return a non-null String and will iterate
122: * through the entire set of available matches until the set is exhausted.
123: *
124: * Each subsequent call to processKey() will reset the iterator over
125: * the set of available matches regardless if the key resulted in a change
126: * to the set.
127: *
128: * The two methods, hasMoreMatches() and getNextMatch(), can be used by
129: * the User Interface system to retrieve the current set of pending inputs
130: * and possibly present a chooser option to the user.
131: *
132: * @return a String representing the best possible pending
133: * input, or null, if there is no pending input
134: */
135: public String getNextMatch();
136:
137: /**
138: * If the InputMode supports multiple matches and more matches are
139: * available this method will return true, false otherwise.
140: *
141: * @return true if the current InputMode supports multiple matches and
142: * there are currently more matches available
143: */
144: public boolean hasMoreMatches();
145:
146: /**
147: * Gets the possible string matches
148: *
149: * @return returns the set of options.
150: */
151: public String[] getMatchList();
152:
153: /**
154: * End the current text input session and do not commit any pending
155: * input to the buffer.
156: */
157: public void endSession();
158:
159: /**
160: * Check if the given char is symbol
161: * @param c char
162: * @return true if the char is symbol otherwise false.
163: */
164: public boolean isSymbol(char c);
165:
166: }
|