FileDocCategorySizeDatePackage
NativeInputMode.javaAPI DocphoneME MR2 API (J2ME)20847Wed May 02 18:00:20 BST 2007com.sun.midp.chameleon.input

NativeInputMode

public class NativeInputMode extends Object implements InputMode

Fields Summary
private static final int
STATE_CALLBACK_RES
this index selects in the function state data array the integer result returned from an interface function
private static final int
STATE_FUNC_TOKEN
this index selects in the function state data array the integer id of interface function to be called
private static final int
STATE_NEXT_STATE
this index selects in the function state data array the integer id of the next state to be entered
private static final int
STATE_INT_ARG
this index selects in the function state data array the integer argument for an interface function
private static final int
STATE_FINAL_RES
this index selects in the function state data array the value to be returned as a result of the enclosing Java function
private static final int
STATE_INTERNAL
this index selects in the function state data array the value to be internally used by native function
private static final int
STATE_INTERNAL_EXT
this index selects in the function state data array the value to be internally used by native function
private static final int
STATE_DATA_ARRAY_SIZE
the number of integer elements in the function state data array
private static final int
MEDIATOR_NOOP
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform no action with the mediator
private static final int
MEDIATOR_COMMIT
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.commit(String) function
private static final int
MEDIATOR_CLEAR
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.clear(int) function
private static final int
MEDIATOR_SUBINPUTMODECHANGED
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.subInputModeChanged() function
private static final int
MEDIATOR_INPUTMODECOMPLETED
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.inputModeCompleted() function
private static final int
MEDIATOR_ISCLEARKEY
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.isClearKey(int) function
private static final int
MEDIATOR_GETAVAILABLESIZE
this value, when stored as stateArgs[STATE_FUNC_TOKEN], tells the executeMediatorCommand function to perform the mediator.getAvailableSize() function
private final int
MAX_STATE_MACHINE_ITERATIONS
This constant limits the number of times a native function may ask the corresponding Java wrapper function to execute a mediator function and re-invoke the native functions after that. Violation of this limit will result in an exception. (A function that need be native but need to call Java functions is implemented as a state machine; the Java wrapper function calls the native function and the Java functions as many times as necessary, provided that the limit MAX_STATE_MACHINE_ITERATIONS is not violated.)
public int
id
Input method identifier. For a given platform, this class may support multiple input methods, and id determines which one is supported by this particular instance.
protected int
instanceData
reserved for instance data
protected InputModeMediator
mediator
The InputModeMediator for the current input session
private boolean[]
isMap
input subset x constraint map
Constructors Summary
public NativeInputMode()
constructor; the real initialization is done in the initialize(int) function

 // must not restrict functionality,
                     // but must detect infinite loops
Methods Summary
public voidbeginInput(InputModeMediator theMediator, java.lang.String inputSubset, int constraints)
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
theMediator the InputModeMediator which is negotiating the relationship between this InputMode and the input session
param
inputSubset current input subset

        mediator = theMediator;
        beginInput0(theMediator, inputSubset, constraints);
public native voidbeginInput0(InputModeMediator theMediator, java.lang.String inputSubset, int constraints)

public voidendInput()
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.
        endInput0();
    
public native voidendInput0()
protected voidexecuteMediatorCommand(int[] stateArgs, java.lang.String stringArg)
Execute a mediator command whose id and integer arguments are stored
in the stateArgs array, and the string argument, if required, is
passed as stringArg; the returned value, if any, is stored
as stateArgs[STATE_CALLBACK_RES].

This function implements the functionality of processKey, but
when it needs to call some mediator function, it stores the current
state into stateArgs and returns; processKey calls the necessary
interface function and calls processKey0 again.

stateArgs[STATE_CALLBACK_RES] -- mediator function result. 

stateArgs[STATE_FUNC_TOKEN] -- the mediator function id. 

stateArgs[STATE_NEXT_STATE] -- not used by executeMediatorCommand,
a native function uses this value to store the integer state id,
the Java function that calls the native function repeats calls
until this value becomes zero. 

stateArgs[STATE_INT_ARG] -- int argument for the mediator function,
if required. 

stateArgs[STATE_FINAL_RES] -- not used by executeMediatorCommand,
the native function store there a result to be returned
by the Java function. 

stateArgs[STATE_INTERNAL] -- for use by native functions. 

stateArgs[STATE_INTERNAL_EXT] -- for use by native functions. 
param
stateArgs the function state data array
param
stringArg the string argument, this value is used only if the
function specified as stateArgs[STATE_FUNC_TOKEN] requires
a string argument.
        if (null == mediator) {
            return;
        }
        switch(stateArgs[STATE_FUNC_TOKEN]) {
            default:
            case MEDIATOR_NOOP:
                break;
            case MEDIATOR_COMMIT:
                mediator.commit(stringArg);
                break;
            case MEDIATOR_CLEAR:
                mediator.clear(stateArgs[STATE_INT_ARG]);
                break;
            case MEDIATOR_SUBINPUTMODECHANGED:
                mediator.subInputModeChanged();
                break;
            case MEDIATOR_INPUTMODECOMPLETED:
                mediator.inputModeCompleted();
                break;
            case MEDIATOR_ISCLEARKEY:
                {
                    boolean res = mediator.isClearKey(stateArgs[STATE_INT_ARG]);
                    stateArgs[STATE_CALLBACK_RES] = res ? 1 : 0;
                }
                break;
            case MEDIATOR_GETAVAILABLESIZE:
                stateArgs[STATE_CALLBACK_RES] = mediator.getAvailableSize();
                break;
        }
        stateArgs[STATE_FUNC_TOKEN] = MEDIATOR_NOOP;
    
private native voidfinalize()
Finalizer. Free the data structures allocated in initialize(int).
public native java.lang.StringgetCommandName()
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 javax.microedition.lcdui.DisplayablegetDisplayable()
Gets displayable for particular input method. If the input method has no
specific displayable representation returns null.
return
displayable
        return null;
    
public boolean[][]getIsConstraintsMap()
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
        return isMap;
    
public native java.lang.String[]getMatchList()
Gets the possible string matches
return
returns the set of options.
public native java.lang.StringgetName()
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 native java.lang.StringgetNextMatch()
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 native chargetPendingChar()
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 booleanhasDisplayable()
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
        return false;
    
public native booleanhasMoreMatches()
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 native intinitialize(int theId)
Initialize the instance.
param
theId the value to be stored as id
return
error code, 0 if ok
public intprocessKey(int keyCode, boolean longPress)
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
true if the key was processed by this InputMode, false
otherwise.
        int iterationCount = 0;
        final int clearKeyFlag =
            mediator == null ? -1 :
            mediator.isClearKey(keyCode) ? 1 : 0;
        int[] stateArgs = new int[STATE_DATA_ARRAY_SIZE];
        String stringArg;
        do {
            if (iterationCount++ > MAX_STATE_MACHINE_ITERATIONS) {
                throw new RuntimeException("too many iterations inside processKey()");
            }
            stringArg = processKey0(keyCode, longPress, clearKeyFlag,stateArgs);
            executeMediatorCommand(stateArgs, stringArg);
        } while (0 != stateArgs[STATE_NEXT_STATE]);

        if (0 != stateArgs[STATE_INTERNAL]
         || 0 != stateArgs[STATE_INTERNAL_EXT]) {
            // If we are here,
            // the programmer has either forgot to free memory,
            // or has not modified the next_state number.
            throw new RuntimeException("the internal state parameter "
                                        +"record have not been released");
        }
        return stateArgs[STATE_FINAL_RES];
    
protected native java.lang.StringprocessKey0(int keyCode, boolean longPress, int isClearKey, int[] stateArgs)
This function is repeatedly called
by procesKey(int keyCode, boolean longPress)
to process the given key code as input.

This function implements the functionality of processKey, but
when it needs to call some mediator function, it stores the current
state into stateArgs and returns; processKey calls the necessary
interface function and calls processKey0 again.

Since the function processKey is a callback invoked when a key
is pressed, it is recommended to finish key processing as soon
as possible. The number of times the function processKey0() may
be called before the function processKey() returns is limited
by the constant MAX_STATE_MACHINE_ITERATIONS, but it does not
mean that it is ok to use so many iterations.

stateArgs[STATE_CALLBACK_RES] -- mediator function result. 

stateArgs[STATE_FUNC_TOKEN] -- the mediator function id. 

stateArgs[STATE_NEXT_STATE] -- the integer id of the next state,
the processKey repeats calling processKey0
until this value becomes zero. 

stateArgs[STATE_INT_ARG] -- int argument for the mediator function,
if required. 

stateArgs[STATE_FINAL_RES] -- the result to be returned
by processKey. 

stateArgs[STATE_INTERNAL] -- may be used by native code implementing
processKey0. 

stateArgs[STATE_INTERNAL_EXT] -- may be used by native code
implementing processKey0. 
param
keyCode the keycode of the key which was input
param
longPress return true if it's long key press otherwise false
param
isClearKey 1 if it's a claer key, 0 if it's not, and -1 if
it cannot be determined because the mediator is null
param
stateArgs contains state information that survives across
repeated reinvocations of this function, and data
to be passed to/from the mediator functions.
return
the string argument to be passed to the mediator function,
or null.
public native booleansupportsConstraints(int constraints)
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 java.lang.StringtoString()

       
        return super.toString()+"[id="+id+"]";