Package mome.keyb

This package is intended to associate key (game action) or sequence of keys and/or game actions with command and issue it to the commands execution thread.

See:
Description

Class Summary

KeyProcessor	This class is intended to associate key (game action) or sequence of keys and/or game actions with command.
XCanvas	A Canvas subclass that translates key events to commands and issues them to commands execution thread and implements double buffering.

Package mome.keyb Description

This package is intended to associate key (game action) or sequence of keys and/or game actions with command and issue it to the commands execution thread. This package depends on mome package. This package contains two classes:

• KeyProcessor used to map key (game action) or sequence of keys and/or game actions to command.
• XCanvas - Canvas subclass that translates key events to commands and issues them to commands execution thread and implements double buffering.

XCanvas

This is a Canvas subclass that translates key events to commands and issues them to commands execution thread, implements double buffering.

To use this class

• subclass it, implementing needed rendering behavior,
• set executor property (e.g. to MoXMIDlet.getExecutor() method or any other Executor instance, as Executor can be used independenly from MoXMIDlet),
• instantiate, configure KeyProcessor and set it via setKeyProcessor(mome.keyb.KeyProcessor) method.

Thats all. All key events will be translated to commands and issued to the commands execution thread.

It uses KeyProcessor to map key (game action) or sequence of keys and/or game actions to command. KeyProcessor can be set and returned by setKeyProcessor(KeyProcessor), getKeyProcessor() methods respectively. It also uses Executor to issue found command to the commands execution thread. Executor can be set and returned by setExecutor(Executor), getExecutor() methods respectively.

To realize double buffering it contains methods getGraphics() to get Graphics instance associated with buffer. and flushGraphics() to flush contents of the buffer.

KeyProcessor

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). Key - command association can be looked up by calling method KeyProcessor.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. If alt key (alt game action) is found method KeyProcessor.process(int) returns KeyProcessor.ALT_KEY_ACTIVATED constant. Next invocation of KeyProcessor.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 KeyProcessor.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 KeyProcessor.setCanvas(Canvas) or during instantiation of KeyProcessor via KeyProcessor.KeyProcessor(Canvas) or KeyProcessor.KeyProcessor(Canvas, int[], Object[]) or KeyProcessor.KeyProcessor(Canvas, int[], Object[], int[], mome.keyb.KeyProcessor[])). This limitation exists because Canvas.getGameAction(int) method is not static.

Author:

Sergio Morozov