001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026: package com.sun.midp.chameleon.input;
027:
028: import javax.microedition.lcdui.Displayable;
029:
030: /**
031: * An interface to a text input mode, such as alphanumeric, numeric, etc.
032: *
033: * Before sending key input to any InputMode, it should be verified that
034: * it supports the input constraints of the target text component. This is
035: * done by verifying that the input constraints of the text component
036: * (as defined in the MIDP specification for TextField) are supported by
037: * this InputMode by calling its supportsConstraints() method.
038: *
039: * The display name of this InputMode is returned by the getName() method.
040: * This value should be a locale appropriate value and suitable for
041: * displaying on the screen, such as an option on the device's system
042: * menu.
043: *
044: * The remaining methods represent a simple state machine with the following
045: * characteristics:
046: *
047: * To begin an input session, the first call MUST be beginInput(). This
048: * establishes an input session with this InputMode and allows the InputMode
049: * to perform any session initialization needed. The parameter to beginInput()
050: * is the InputModeMediator for the input session. The InputModeMediator is
051: * a callback mechanism for the InputMode to automatically commit pending
052: * input as well as end the input session.
053: *
054: * Subsequent key input is passed to the InputMode via the processKey()
055: * method. This method returns a String element. The returned String
056: * represents the best possible input value based on the total key input
057: * during the input session. For example, for an AlphaNumeric InputMode,
058: * the pending input will only ever be a single String, representing
059: * the character that corresponds to the last key entered. A 'null' return
060: * value from processKey() is an indication that this InputMode did not
061: * process the key at all, and it may need to be processed by other elements
062: * of the system.
063: *
064: * For a predictive
065: * text InputMode such as T9, there could be several possible matches.
066: * The return value from processKey() in this instance will be what the
067: * system believes to be the best possible match. The return value of
068: * the hasMoreMatches() method will indicate whether the InputMode has
069: * more than one possible match to the given input. The matches can then
070: * be retrieved using the getNextMatch() method.
071: *
072: * Key processing should be considered complete after the call to the
073: * InputMode's endInput() method. At this point, the InputMode should
074: * consider the reference to the TextInputMediator passed to its
075: * beginInput() method to be no longer valid.
076: *
077: * The InputMode may itself at any time commit pending input by calling the
078: * InputModeMediator's commitInput() method. The InputMode may also end
079: * the input session by calling the inputModeCompleted() method. Calling
080: * this method will result in a subsequent call to this InputMode's
081: * endInput() method.
082: *
083: * A typical call exchange with an InputMode could go as follows:
084: *
085: * InputMode im = ...;
086: * im.beginInput(inputModeHandler);
087: *
088: * int res = im.processKey([key code for 4]);
089: * if (pendingInput == null) {
090: * // The InputMode could not process the key code
091: * } else {
092: * // Present the pendingInput value to the user as the
093: * // best possible match
094: * ...
095: * while (im.hasMoreMatches()) {
096: * pendingInput = im.getNextMatch();
097: * // Present the pendingInput value to the user as
098: * // the best possible match
099: * }
100: * }
101: *
102: * im.endInput();
103: */
104: public interface InputMode {
105:
106: /** The key code does not mean to be displayed */
107: public static final int KEYCODE_INVISIBLE = -4;
108:
109: /**
110: * The key code is not handled by the input mode.
111: * Most likely it is handled by the text component */
112: public static final int KEYCODE_NONE = -3; // dont clash
113:
114: /**
115: * a sub-inputMode which may be supported by an InputMode.
116: * all letters are uppercase
117: */
118: public static final int CAPS_ON = 1;
119:
120: /**
121: * a sub-inputMode which may be supported by an InputMode.
122: * all letters are lowercase
123: */
124: public static final int CAPS_OFF = 2;
125:
126: /**
127: * a sub-inputMode which may be supported by an InputMode.
128: * the first letter is capitalized, the rest of the letters are lowercase
129: */
130: public static final int CAPS_SENTENCE = 3;
131:
132: /** The limitation for the number of matches */
133: public static final int MAX_MATCHES = 20;
134:
135: /**
136: * This method is called to determine if this InputMode supports
137: * the given text input constraints. The semantics of the constraints
138: * value are defined in the javax.microedition.lcdui.TextField API.
139: * If this InputMode returns false, this InputMode must not be used
140: * to process key input for the selected text component.
141: *
142: * @param constraints text input constraints. The semantics of the
143: * constraints value are defined in the TextField API.
144: *
145: * @return true if this InputMode supports the given text component
146: * constraints, as defined in the MIDP TextField API
147: */
148: public boolean supportsConstraints(int constraints);
149:
150: /**
151: * Returns the display name which will represent this InputMode to
152: * the user, such as in a selection list or the softbutton bar.
153: *
154: * @return the locale-appropriate name to represent this InputMode
155: * to the user
156: */
157: public String getName();
158:
159: /**
160: * Returns the command name which will represent this InputMode in
161: * the input menu
162: *
163: * @return the locale-appropriate name to represent this InputMode
164: * to the user
165: */
166: public String getCommandName();
167:
168: /**
169: * This method will be called before any input keys are passed
170: * to this InputMode to allow the InputMode to perform any needed
171: * initialization. A reference to the InputModeMediator which is
172: * currently managing the relationship between this InputMode and
173: * the input session is passed in. This reference can be used
174: * by this InputMode to commit text input as well as end the input
175: * session with this InputMode. The reference is only valid until
176: * this InputMode's endInput() method is called.
177: *
178: * @param constraints text input constraints. The semantics of the
179: * constraints value are defined in the TextField API.
180: *
181: * @param mediator the InputModeMediator which is negotiating the
182: * relationship between this InputMode and the input session
183: *
184: * @param inputSubset current input subset
185: */
186: public void beginInput(InputModeMediator mediator,
187: String inputSubset, int constraints)
188: throws IllegalStateException;
189:
190: /**
191: * Process the given key code as input.
192: *
193: * This method will return true if the key was processed successfully,
194: * false otherwise.
195: *
196: * @param keyCode the keycode of the key which was input
197: * @param longPress return true if it's long key press otherwise false
198: * @return the key code if the key has been committed for the input, or
199: * KEYCODE_NONE if the key has not been habdled by the input mode, or
200: * KEYCODE_INVISIBLE if the key has been handled by the input mode but
201: * this key has not been displayed
202: */
203: public int processKey(int keyCode, boolean longPress)
204: throws IllegalStateException;
205:
206: /**
207: * return the pending char
208: * used to bypass the asynchronous commit mechanism
209: * e.g. to immediately commit a char before moving the cursor
210: * @return return the pending char
211: */
212: public char getPendingChar();
213:
214: /**
215: * Return the next possible match for the key input processed thus
216: * far by this InputMode. A call to this method should be preceeded
217: * by a check of hasMoreMatches(). If the InputMode has more available
218: * matches for the given input, this method will return them one by one.
219: *
220: * @return a String representing the next available match to the key
221: * input thus far, or 'null' if no pending input is available
222: */
223: public String getNextMatch();
224:
225: /**
226: * True, if after processing a key, there is more than one possible
227: * match to the input. If this method returns true, the getNextMatch()
228: * method can be called to return the value.
229: *
230: * @return true if after processing a key, there is more than the one
231: * possible match to the given input
232: */
233: public boolean hasMoreMatches();
234:
235: /**
236: * Gets the possible string matches
237: *
238: * @return returns the set of options.
239: */
240: public String[] getMatchList();
241:
242: /**
243: * Mark the end of this InputMode's processing. The only possible call
244: * to this InputMode after a call to endInput() is a call to beginInput()
245: * to begin a new input session.
246: */
247: public void endInput() throws IllegalStateException;
248:
249: /**
250: * Gets displayable for particular input method. If the input method has no
251: * specific displayable representation returns null.
252: * @return displayable
253: */
254: public Displayable getDisplayable();
255:
256: /**
257: * Returns true if input mode is using its own displayable, false ifinput
258: * mode does not require the speial displayable for its representation
259: * @return true if input mode is using its own displayable, otherwise false
260: */
261: public boolean hasDisplayable();
262:
263: /**
264: * Returns the map specifying this input mode is proper one for the
265: * particular pair of input subset and constraint. The form of the map is
266: *
267: * |ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL|
268: * ---------------------------------------------------------------------
269: * IS_FULLWIDTH_DIGITS |t|f| t|f | t|f | t|f |t|f| t|f |
270: * IS_FULLWIDTH_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
271: * IS_HALFWIDTH_KATAKANA |t|f| t|f | t|f | t|f |t|f| t|f |
272: * IS_HANJA |t|f| t|f | t|f | t|f |t|f| t|f |
273: * IS_KANJI |t|f| t|f | t|f | t|f |t|f| t|f |
274: * IS_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
275: * IS_LATIN_DIGITS |t|f| t|f | t|f | t|f |t|f| t|f |
276: * IS_SIMPLIFIED_HANZI |t|f| t|f | t|f | t|f |t|f| t|f |
277: * IS_TRADITIONAL_HANZI |t|f| t|f | t|f | t|f |t|f| t|f |
278: * MIDP_UPPERCASE_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
279: * MIDP_LOWERCASE_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
280: * NULL |t|f| t|f | t|f | t|f |t|f| t|f |
281: *
282: * @return input subset x constraint map
283: */
284: public boolean[][] getIsConstraintsMap();
285: }
|