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: */
032: public class NativeInputMode implements InputMode {
033:
034: /** this index selects in the function state data array
035: * the integer result returned from an interface function */
036: private final static int STATE_CALLBACK_RES = 0;
037: /** this index selects in the function state data array
038: * the integer id of interface function to be called */
039: private final static int STATE_FUNC_TOKEN = 1;
040: /** this index selects in the function state data array
041: * the integer id of the next state to be entered */
042: private final static int STATE_NEXT_STATE = 2;
043: /** this index selects in the function state data array
044: * the integer argument for an interface function */
045: private final static int STATE_INT_ARG = 3;
046: /** this index selects in the function state data array
047: * the value to be returned as a result of the enclosing Java function */
048: private final static int STATE_FINAL_RES = 4;
049: /** this index selects in the function state data array
050: * the value to be internally used by native function */
051: private final static int STATE_INTERNAL = 5;
052: /** this index selects in the function state data array
053: * the value to be internally used by native function */
054: private final static int STATE_INTERNAL_EXT = 6;
055: /** the number of integer elements in the function state data array */
056: private final static int STATE_DATA_ARRAY_SIZE = 7;
057:
058: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
059: * tells the executeMediatorCommand function
060: * to perform no action with the mediator */
061: private final static int MEDIATOR_NOOP = 0;
062: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
063: * tells the executeMediatorCommand function
064: * to perform the mediator.commit(String) function */
065: private final static int MEDIATOR_COMMIT = 1;
066: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
067: * tells the executeMediatorCommand function
068: * to perform the mediator.clear(int) function */
069: private final static int MEDIATOR_CLEAR = 2;
070: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
071: * tells the executeMediatorCommand function
072: * to perform the mediator.subInputModeChanged() function */
073: private final static int MEDIATOR_SUBINPUTMODECHANGED = 3;
074: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
075: * tells the executeMediatorCommand function
076: * to perform the mediator.inputModeCompleted() function */
077: private final static int MEDIATOR_INPUTMODECOMPLETED = 4;
078: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
079: * tells the executeMediatorCommand function
080: * to perform the mediator.isClearKey(int) function */
081: private final static int MEDIATOR_ISCLEARKEY = 5;
082: /** this value, when stored as stateArgs[STATE_FUNC_TOKEN],
083: * tells the executeMediatorCommand function
084: * to perform the mediator.getAvailableSize() function */
085: private final static int MEDIATOR_GETAVAILABLESIZE = 6;
086:
087: /**
088: * This constant limits the number of times a native function may
089: * ask the corresponding Java wrapper function to execute a mediator
090: * function and re-invoke the native functions after that.
091: * Violation of this limit will result in an exception.
092: * (A function that need be native but need to call Java functions is
093: * implemented as a state machine; the Java wrapper function calls
094: * the native function and the Java functions as many times as necessary,
095: * provided that the limit MAX_STATE_MACHINE_ITERATIONS is not violated.)
096: */
097: private final int MAX_STATE_MACHINE_ITERATIONS = 32767; // must not restrict functionality,
098:
099: // but must detect infinite loops
100:
101: /** constructor; the real initialization is done
102: * in the initialize(int) function */
103: public NativeInputMode() {
104: }
105:
106: /**
107: * Initialize the instance.
108: *
109: * @param theId the value to be stored as id
110: * @return error code, 0 if ok
111: */
112: public native int initialize(int theId);
113:
114: /**
115: * Finalizer. Free the data structures allocated in initialize(int).
116: */
117: private native void finalize();
118:
119: /**
120: * Input method identifier. For a given platform, this class may
121: * support multiple input methods, and id determines which one is
122: * supported by this particular instance.
123: */
124: public int id;
125:
126: /** reserved for instance data */
127: protected int instanceData;
128:
129: /** The InputModeMediator for the current input session */
130: protected InputModeMediator mediator;
131:
132: /**
133: * This method is called to determine if this InputMode supports
134: * the given text input constraints. The semantics of the constraints
135: * value are defined in the javax.microedition.lcdui.TextField API.
136: * If this InputMode returns false, this InputMode must not be used
137: * to process key input for the selected text component.
138: *
139: * @param constraints text input constraints. The semantics of the
140: * constraints value are defined in the TextField API.
141: *
142: * @return true if this InputMode supports the given text component
143: * constraints, as defined in the MIDP TextField API
144: */
145: public native boolean supportsConstraints(int constraints);
146:
147: /**
148: * Returns the display name which will represent this InputMode to
149: * the user, such as in a selection list or the softbutton bar.
150: *
151: * @return the locale-appropriate name to represent this InputMode
152: * to the user
153: */
154: public native String getName();
155:
156: /**
157: * Returns the command name which will represent this InputMode in
158: * the input menu
159: *
160: * @return the locale-appropriate name to represent this InputMode
161: * to the user
162: */
163: public native String getCommandName();
164:
165: /**
166: * This method will be called before any input keys are passed
167: * to this InputMode to allow the InputMode to perform any needed
168: * initialization. A reference to the InputModeMediator which is
169: * currently managing the relationship between this InputMode and
170: * the input session is passed in. This reference can be used
171: * by this InputMode to commit text input as well as end the input
172: * session with this InputMode. The reference is only valid until
173: * this InputMode's endInput() method is called.
174: *
175: * @param constraints text input constraints. The semantics of the
176: * constraints value are defined in the TextField API.
177: *
178: * @param theMediator the InputModeMediator which is negotiating the
179: * relationship between this InputMode and the input session
180: *
181: * @param inputSubset current input subset
182: */
183: public void beginInput(InputModeMediator theMediator,
184: String inputSubset, int constraints)
185: throws IllegalStateException {
186: mediator = theMediator;
187: beginInput0(theMediator, inputSubset, constraints);
188: }
189:
190: public native void beginInput0(InputModeMediator theMediator,
191: String inputSubset, int constraints);
192:
193: /**
194: * Process the given key code as input.
195: *
196: * This method will return true if the key was processed successfully,
197: * false otherwise.
198: *
199: * @param keyCode the keycode of the key which was input
200: * @param longPress return true if it's long key press otherwise false
201: * @return true if the key was processed by this InputMode, false
202: * otherwise.
203: */
204: public int processKey(int keyCode, boolean longPress)
205: throws IllegalStateException {
206: int iterationCount = 0;
207: final int clearKeyFlag = mediator == null ? -1 : mediator
208: .isClearKey(keyCode) ? 1 : 0;
209: int[] stateArgs = new int[STATE_DATA_ARRAY_SIZE];
210: String stringArg;
211: do {
212: if (iterationCount++ > MAX_STATE_MACHINE_ITERATIONS) {
213: throw new RuntimeException(
214: "too many iterations inside processKey()");
215: }
216: stringArg = processKey0(keyCode, longPress, clearKeyFlag,
217: stateArgs);
218: executeMediatorCommand(stateArgs, stringArg);
219: } while (0 != stateArgs[STATE_NEXT_STATE]);
220:
221: if (0 != stateArgs[STATE_INTERNAL]
222: || 0 != stateArgs[STATE_INTERNAL_EXT]) {
223: // If we are here,
224: // the programmer has either forgot to free memory,
225: // or has not modified the next_state number.
226: throw new RuntimeException("the internal state parameter "
227: + "record have not been released");
228: }
229: return stateArgs[STATE_FINAL_RES];
230: }
231:
232: /**
233: * Execute a mediator command whose id and integer arguments are stored
234: * in the stateArgs array, and the string argument, if required, is
235: * passed as stringArg; the returned value, if any, is stored
236: * as stateArgs[STATE_CALLBACK_RES].
237: *
238: * This function implements the functionality of processKey, but
239: * when it needs to call some mediator function, it stores the current
240: * state into stateArgs and returns; processKey calls the necessary
241: * interface function and calls processKey0 again.
242: *
243: * stateArgs[STATE_CALLBACK_RES] -- mediator function result. <br>
244: * stateArgs[STATE_FUNC_TOKEN] -- the mediator function id. <br>
245: * stateArgs[STATE_NEXT_STATE] -- not used by executeMediatorCommand,
246: * a native function uses this value to store the integer state id,
247: * the Java function that calls the native function repeats calls
248: * until this value becomes zero. <br>
249: * stateArgs[STATE_INT_ARG] -- int argument for the mediator function,
250: * if required. <br>
251: * stateArgs[STATE_FINAL_RES] -- not used by executeMediatorCommand,
252: * the native function store there a result to be returned
253: * by the Java function. <br>
254: * stateArgs[STATE_INTERNAL] -- for use by native functions. <br>
255: * stateArgs[STATE_INTERNAL_EXT] -- for use by native functions. <br>
256: *
257: * @param stateArgs the function state data array
258: * @param stringArg the string argument, this value is used only if the
259: * function specified as stateArgs[STATE_FUNC_TOKEN] requires
260: * a string argument.
261: */
262: protected void executeMediatorCommand(int[] stateArgs,
263: String stringArg) {
264: if (null == mediator) {
265: return;
266: }
267: switch (stateArgs[STATE_FUNC_TOKEN]) {
268: default:
269: case MEDIATOR_NOOP:
270: break;
271: case MEDIATOR_COMMIT:
272: mediator.commit(stringArg);
273: break;
274: case MEDIATOR_CLEAR:
275: mediator.clear(stateArgs[STATE_INT_ARG]);
276: break;
277: case MEDIATOR_SUBINPUTMODECHANGED:
278: mediator.subInputModeChanged();
279: break;
280: case MEDIATOR_INPUTMODECOMPLETED:
281: mediator.inputModeCompleted();
282: break;
283: case MEDIATOR_ISCLEARKEY: {
284: boolean res = mediator.isClearKey(stateArgs[STATE_INT_ARG]);
285: stateArgs[STATE_CALLBACK_RES] = res ? 1 : 0;
286: }
287: break;
288: case MEDIATOR_GETAVAILABLESIZE:
289: stateArgs[STATE_CALLBACK_RES] = mediator.getAvailableSize();
290: break;
291: }
292: stateArgs[STATE_FUNC_TOKEN] = MEDIATOR_NOOP;
293: }
294:
295: /**
296: * This function is repeatedly called
297: * by procesKey(int keyCode, boolean longPress)
298: * to process the given key code as input.
299: *
300: * This function implements the functionality of processKey, but
301: * when it needs to call some mediator function, it stores the current
302: * state into stateArgs and returns; processKey calls the necessary
303: * interface function and calls processKey0 again.
304: *
305: * Since the function processKey is a callback invoked when a key
306: * is pressed, it is recommended to finish key processing as soon
307: * as possible. The number of times the function processKey0() may
308: * be called before the function processKey() returns is limited
309: * by the constant MAX_STATE_MACHINE_ITERATIONS, but it does not
310: * mean that it is ok to use so many iterations.
311: *
312: * stateArgs[STATE_CALLBACK_RES] -- mediator function result. <br>
313: * stateArgs[STATE_FUNC_TOKEN] -- the mediator function id. <br>
314: * stateArgs[STATE_NEXT_STATE] -- the integer id of the next state,
315: * the processKey repeats calling processKey0
316: * until this value becomes zero. <br>
317: * stateArgs[STATE_INT_ARG] -- int argument for the mediator function,
318: * if required. <br>
319: * stateArgs[STATE_FINAL_RES] -- the result to be returned
320: * by processKey. <br>
321: * stateArgs[STATE_INTERNAL] -- may be used by native code implementing
322: * processKey0. <br>
323: * stateArgs[STATE_INTERNAL_EXT] -- may be used by native code
324: * implementing processKey0. <br>
325: *
326: * @param keyCode the keycode of the key which was input
327: * @param longPress return true if it's long key press otherwise false
328: * @param isClearKey 1 if it's a claer key, 0 if it's not, and -1 if
329: * it cannot be determined because the mediator is null
330: * @param stateArgs contains state information that survives across
331: * repeated reinvocations of this function, and data
332: * to be passed to/from the mediator functions.
333: * @return the string argument to be passed to the mediator function,
334: * or null.
335: */
336: protected native String processKey0(int keyCode, boolean longPress,
337: int isClearKey, int[] stateArgs)
338: throws IllegalStateException;
339:
340: /**
341: * return the pending char
342: * used to bypass the asynchronous commit mechanism
343: * e.g. to immediately commit a char before moving the cursor
344: * @return return the pending char
345: */
346: public native char getPendingChar();
347:
348: /**
349: * Return the next possible match for the key input processed thus
350: * far by this InputMode. A call to this method should be preceeded
351: * by a check of hasMoreMatches(). If the InputMode has more available
352: * matches for the given input, this method will return them one by one.
353: *
354: * @return a String representing the next available match to the key
355: * input thus far, or 'null' if no pending input is available
356: */
357: public native String getNextMatch();
358:
359: /**
360: * True, if after processing a key, there is more than one possible
361: * match to the input. If this method returns true, the getNextMatch()
362: * method can be called to return the value.
363: *
364: * @return true if after processing a key, there is more than the one
365: * possible match to the given input
366: */
367: public native boolean hasMoreMatches();
368:
369: /**
370: * Gets the possible string matches
371: *
372: * @return returns the set of options.
373: */
374: public native String[] getMatchList();
375:
376: /**
377: * Mark the end of this InputMode's processing. The only possible call
378: * to this InputMode after a call to endInput() is a call to beginInput()
379: * to begin a new input session.
380: */
381: public void endInput() throws IllegalStateException {
382: endInput0();
383: }
384:
385: public native void endInput0() throws IllegalStateException;
386:
387: /**
388: * Gets displayable for particular input method. If the input method has no
389: * specific displayable representation returns null.
390: * @return displayable
391: */
392: public Displayable getDisplayable() {
393: return null;
394: }
395:
396: /**
397: * Returns true if input mode is using its own displayable, false ifinput
398: * mode does not require the speial displayable for its representation
399: * @return true if input mode is using its own displayable, otherwise false
400: */
401: public boolean hasDisplayable() {
402: return false;
403: }
404:
405: /**
406: * Returns the map specifying this input mode is proper one for the
407: * particular pair of input subset and constraint. The form of the map is
408: *
409: * |ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL|
410: * ---------------------------------------------------------------------
411: * IS_FULLWIDTH_DIGITS |t|f| t|f | t|f | t|f |t|f| t|f |
412: * IS_FULLWIDTH_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
413: * IS_HALFWIDTH_KATAKANA |t|f| t|f | t|f | t|f |t|f| t|f |
414: * IS_HANJA |t|f| t|f | t|f | t|f |t|f| t|f |
415: * IS_KANJI |t|f| t|f | t|f | t|f |t|f| t|f |
416: * IS_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
417: * IS_LATIN_DIGITS |t|f| t|f | t|f | t|f |t|f| t|f |
418: * IS_SIMPLIFIED_HANZI |t|f| t|f | t|f | t|f |t|f| t|f |
419: * IS_TRADITIONAL_HANZI |t|f| t|f | t|f | t|f |t|f| t|f |
420: * MIDP_UPPERCASE_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
421: * MIDP_LOWERCASE_LATIN |t|f| t|f | t|f | t|f |t|f| t|f |
422: * NULL |t|f| t|f | t|f | t|f |t|f| t|f |
423: *
424: * @return input subset x constraint map
425: */
426: public boolean[][] getIsConstraintsMap() {
427: return isMap;
428: }
429:
430: /** input subset x constraint map */
431: /* private static boolean[][] isMap = {
432: // |ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL
433: { false, false, false, false, false, false }, // IS_FULLWIDTH_DIGITS
434: { false, false, false, false, false, false }, // IS_FULLWIDTH_LATIN
435: { false, false, false, false, false, false }, // IS_HALFWIDTH_KATAKANA
436: { false, false, false, false, false, false }, // IS_HANJA
437: { false, false, false, false, false, false }, // IS_KANJI
438: { false, false, false, false, false, false }, // IS_LATIN
439: { false, false, false, false, false, false }, // IS_LATIN_DIGITS
440: { false, false, false, false, false, false }, // IS_SIMPLIFIED_HANZI
441: { false, false, false, false, false, false }, // IS_TRADITIONAL_HANZI
442: { false, false, false, false, false, false }, // MIDP_UPPERCASE_LATIN
443: { false, false, false, false, false, false }, // MIDP_LOWERCASE_LATIN
444: { false, false, false, false, false, false } // NULL
445: };
446: */
447: /** input subset x constraint map */
448: private boolean[][] isMap = new boolean[][] {
449: // |ANY|EMAILADDR|NUMERIC|PHONENUMBER|URL|DECIMAL
450: { true, true, true, true, true, true }, // IS_FULLWIDTH_DIGITS
451: { true, true, true, true, true, true }, // IS_FULLWIDTH_LATIN
452: { true, true, true, true, true, true }, // IS_HALFWIDTH_KATAKANA
453: { true, true, true, true, true, true }, // IS_HANJA
454: { true, true, true, true, true, true }, // IS_KANJI
455: { true, true, true, true, true, true }, // IS_LATIN
456: { true, true, true, true, true, true }, // IS_LATIN_DIGITS
457: { true, true, true, true, true, true }, // IS_SIMPLIFIED_HANZI
458: { true, true, true, true, true, true }, // IS_TRADITIONAL_HANZI
459: { true, true, true, true, true, true }, // MIDP_UPPERCASE_LATIN
460: { true, true, true, true, true, true }, // MIDP_LOWERCASE_LATIN
461: { true, true, true, true, true, true } // NULL
462: };
463:
464: public String toString() {
465: return super .toString() + "[id=" + id + "]";
466: }
467: }
|