mome.keyb
Class KeyProcessor

java.lang.Object
  mome.keyb.KeyProcessor

public class KeyProcessor
extends Object

This class is intended to associate key (game action) or sequence of keys and/or game actions with command. In this class term "command" is abstracted to an Object (like in mome package). This class maintains association between key codes or game action constants and commands. This associations can be added or removed by addKey(int, Object) method. Command can be looked up by process(int) method. Key - command association can be looked up by calling method process(int) with key code. Game action - command association can be looked up by calling the same method with key code mapped to the given game action or with game action directly.

Based on fact, that key codes and game action constants do not intersect (key code is unicode code of character representation of key or a negative value and game action constants are mapped to control unicode characters), it is possible to look up commands with key codes and game action constants independently. For example methods invocations: processor.process(Canvas.KEY_NUM4); and processor.process(Canvas.LEFT); will return the same result on almost every phone, because mostly key '4' is mapped to game action "LEFT".

Association of sequences of keys and/or game actions with command is based on introduction of alt keys (alt game actions), that can be associated with other KeyProcessors. This class maintains alt key (alt game action) - KeyProcessor association. These associations can be added or removed by addAltKey(int, KeyProcessor) method. If alt key (alt game action) is found method process(int) returns ALT_KEY_ACTIVATED constant. Next invocation of process(int) will look up key or game action at KeyProcessor associated with previous alt key (alt game action), For example, to associate a key sequence '#', '9' with cmd :

                                   ...
                                 KeyProcessor p1 = new KeyProcessor( ... );
                                   ... 
                                 KeyProcessor p = new KeyProcessor( ... );
                                   ... 
                                 p1.addKey( Canvas.KEY_NUM9, cmd);
                                   ...
                                 p.addAltKey( Canvas.KEY_POUND, p1);
                                   ...  
 

Cycle chaining of KeyProcessors (direct or indirect) is detected via IllegalStateException thrown from method process(int), when cycle is actually reached.

Note Game action - command association can be looked up based on key code only if canvas property was set to not null value (via method setCanvas(Canvas) or during instantiation of KeyProcessor via KeyProcessor(Canvas) or KeyProcessor(Canvas, int[], Object[]) or KeyProcessor(Canvas, int[], Object[], int[], mome.keyb.KeyProcessor[])). This limitation exists because Canvas.getGameAction(int) method is not static.

Version:

1.0

Author:

Sergio Morozov

Field Summary

static Object

ALT_KEY_ACTIVATED Command returned by process(int) if alt key or alt game action is found.

Constructor Summary

KeyProcessor()
Instantiates KeyProcessor, with empty maps of key (game action) - command associations and alt key (alt game action) - KeyProcessors associations and null canvas property.

KeyProcessor(Canvas owner)
Instantiates KeyProcessor, with given canvas and empty maps of key (game action) - command associations and alt key (alt game action) - KeyProcessors associations.

KeyProcessor(Canvas owner, int[] keys, Object[] cmds)
Instantiates KeyProcessor with given canvas.

KeyProcessor(Canvas owner, int[] keys, Object[] cmds, int[] altKeys, KeyProcessor[] processors)
Instantiates KeyProcessor with given canvas.

Method Summary

void	addAltKey(int key, KeyProcessor processor) Adds alt key (alt game action) - KeyProcessor association or removes it if processor is null.
void	addKey(int key, Object cmd) Adds key (game action) - command association to the KeyProcessor or removes it if cmd is null.
Object	process(int key) Returns an object identifying command associated with given key-code (game action constant) or game action mapped to given key code.
protected Object	process(int key, Vector fProcessors) Returns an object identifying command associated with given key-code (game action constant) or game action mapped to given key code.
void	setCanvas(Canvas owner) Sets the canvas property to the given value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ALT_KEY_ACTIVATED

public static final Object ALT_KEY_ACTIVATED

Command returned by process(int) if alt key or alt game action is found.

Constructor Detail

KeyProcessor

public KeyProcessor()

Instantiates KeyProcessor, with empty maps of key (game action) - command associations and alt key (alt game action) - KeyProcessors associations and null canvas property.

KeyProcessor

public KeyProcessor(Canvas owner)

Instantiates KeyProcessor, with given canvas and empty maps of key (game action) - command associations and alt key (alt game action) - KeyProcessors associations.

Parameters:

owner - Canvas to be associated with this KeyProcessor. This property is needed to get game action constant from key code, due to non static Canvas.getGameAction(int) method.

KeyProcessor

public KeyProcessor(Canvas owner,
                    int[] keys,
                    Object[] cmds)

Instantiates KeyProcessor with given canvas. Takes array of key codes (game actions) and array of commands as arguments. keys array's length must be equal or less then cmds array. All extra commands are ignored. If keys is null no commands are added and cmds parameter is ignored. cmds parameter can't be null. Key codes or game action values and commands are associated based on position in array.

Parameters:

owner - Canvas to be associated with this KeyProcessor. This property is needed to get game action value from key code, due to non static Canvas.getGameAction(int) method.

keys - array of key codes and/or game action constants.

cmds - array of commands to be associated with key codes or game action constants. Can't be null.

Throws:

NullPointerException - when cmds is null or some element of cmds is null and keys is not null.

KeyProcessor

public KeyProcessor(Canvas owner,
                    int[] keys,
                    Object[] cmds,
                    int[] altKeys,
                    KeyProcessor[] processors)

Instantiates KeyProcessor with given canvas. Takes array of key codes (game actions), array of commands, and array of alt key codes (alt game actions), array of processors as arguments. keys array's length must be equal or less then cmds array. altKeys array's length must be equal or less then processors array. All extra commands or processors are ignored. If keys is null no commands are added and cmds parameter is ignored. If altKeys is null no processors are added and processors parameter is ignored. cmds and processors parameters can't be null. Key codes (game action constants) and commands are associated based on position in array. Alt key codes (alt game action constants) and processors are associated based on position in array.

Parameters:

owner - Canvas to be associated with this KeyProcessor. This property is needed to get game action value from key code, due to non static Canvas.getGameAction(int) method.

keys - array of key codes and/or game action constants.

cmds - array of commands to be associated with key codes or game action constants. Can't be null.

altKeys - array of alt key codes and/or alt game action constants.

processors - array of processors to be associated with key codes or game action constants. Can't be null.

Throws:

NullPointerException - when cmds is null or some element of cmds is null and keys is not null or when processors is null or some element of processors is null and altKeys is not null.

Method Detail

setCanvas

public void setCanvas(Canvas owner)

Sets the canvas property to the given value.

Parameters:

owner - Canvas to be associated with this KeyProcessor. This property is needed to get game action value from key code, due to non static Canvas.getGameAction(int) method.

addKey

public void addKey(int key,
                   Object cmd)

Adds key (game action) - command association to the KeyProcessor or removes it if cmd is null.

Parameters:

key - key code or game action constant.

cmd - command to be associated with given key or game action or null to remove key (game action) - command association.

addAltKey

public void addAltKey(int key,
                      KeyProcessor processor)

Adds alt key (alt game action) - KeyProcessor association or removes it if processor is null.

Parameters:

key - key code or game action constant.

processor - KeyProcessor to be associated with given key or game action or null to remove key (game action) - KeyProcessor association.

process

public Object process(int key)

Returns an object identifying command associated with given key-code (game action constant) or game action mapped to given key code. If there is alt key associated with specified key-code key-code (game action constant) or game action mapped to given key code this method returns ALT_KEY_ACTIVATED constant and moves KeyProcessor to "alt" state. In this state next invocation of process(int) will lookup key or game action codes at KeyProcessor associated with previous alt key (alt game action), returns the result and moves KeyProcessor to regular state, if nested alt key is not found.

Parameters:

key - key code or game action constant.

Returns:

an object identifying command associated with key or game action, ALT_KEY_ACTIVATED if key is alt Key (alt game action) or null if not found.

Throws:

IllegalStateException - KeyProcessors cycle is reached.

process

protected Object process(int key,
                         Vector fProcessors)

Returns an object identifying command associated with given key-code (game action constant) or game action mapped to given key code. If there is alt key associated with specified key-code key-code (game action constant) or game action mapped to given key code this method returns ALT_KEY_ACTIVATED constant and moves KeyProcessor to "alt" state. In this state next invocation of process(int) will lookup key or game action codes at KeyProcessor associated with previous alt key (alt game action), returns the result and moves KeyProcessor to regular state, if nested alt key is not found.

Parameters:

key - key code or game action constant.

fProcessors - processors looked up before this one in this sequence of keys and/or game actions.

Returns:

an object identifying command associated with key or game action, ALT_KEY_ACTIVATED if key is alt Key (alt game action) or null if not found.

Throws:

IllegalStateException - KeyProcessors cycle is reached.