MoMEKeyb Guide

Sergio Morozov


A short & concise guide.

Overview

MoMEKeyb – is package of MoMELib library. It is intended for processing key events. This package depends on mome package. It offers a possibility to associate key (game action) or sequence of keys and/or game actions with command and issue it to the commands execution thread.

Note Like with any J2ME library it is recommended to use obfuscator to minimize memory usage.

Installation

Installation of MoMEKeyb is like installation of any other j2me library. Just make classes contained in jar file accessible for class loaders and make sure they are in jar file of your project. To do this follow instruction of your IDE.

Note This package depends on mome package and is packaged together with it.

Usage

The usage of this package is easy. Developer should instantiate and configure KeyProcessor to associate key (game action) or sequence of keys and/or game actions with command, subclass XCanvas (Canvas subclass) implementing rendering behavior needed for your application and supply it with KeyProcessor and Executor (e.g. from MoXMIDlet.getExecutor()) For example:

  KeyProcessor kProc = ... ;
  ...
  XCanvas canvas = new XCanvas();
  canvas.setExecutor( this.getExecutor);
  canvas.setKeyProcessor( kProc);
  ...

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

The simplest way to instantiate and configure KeyProcessor for associating key and/or game actions with commands is by KeyProcessor(Canvas canvas, int[] keys, Object[] cmds) constructor. This constructor takes two arrays as parameters, The first is an array of key codes and/or game action constants and the second is an array of commands. For example:

  KeyProcessor kProc = new KeyProcessor( canvas, 
    new int[] { Canvas.DOWN, Canvas.UP, Canvas.KEY_NUM0}, 
    new Object[] { NEXT_LINE, PREV_LINE, TO_TOP});
    // this will associate game action DOWN with NEXT_LINE command, 
    //game action UP with PREV_LINE and key '0' with TO_TOP command.

It is also possible to associate a sequence of commands and/or game actions with command. This 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 key) returns KeyProcessor.ALT_KEY_ACTIVATED constant. Next invocation of KeyProcessor.process(int key) will look up key or game action at KeyProcessor associated with previous alt key (alt game action), To instantiate and configure KeyProcessor in this case better to use KeyProcessor(Canvas canvas, int[] keys, Object[] cmds, int[] altKeys, mome.keyb.KeyProcessor[] processors) constructor. For example:

  KeyProcessor kProc2 = new KeyProcessor( canvas, new int[] { Canvas.DOWN, Canvas.UP}, 
    new Object[] { TO_BOTTOM, TO_TOP});
    // this will associate game action DOWN with TO_BOTTOM command and 
    // game action UP with TO_TOP command.

  KeyProcessor kProc = new KeyProcessor( canvas, new int[] { Canvas.DOWN, Canvas.UP}, 
    new Object[] { NEXT_LINE, PREV_LINE, TO_TOP}, new int[] {Canvas.KEY_NUM0}, 
    new KeyProcessor[] { kProc2});
    // this will associate game action DOWN with NEXT_LINE command, game action UP with PREV_LINE and 
    // key '0' with kProc2 processor.
    
    // key sequence '0', UP will result to TO_TOP command and '0', DOWN to TO_BOTTOM.

KeyProcessors can be nested any number of times (if there is a need). Cycle chaining of KeyProcessors (direct or indirect) is detected via IllegalStateException thrown from method KeyProcessor.process(int key), when cycle is actually reached.

Developer also can instantiate KeyProcessor by use of KeyProcessor(Canvas), KeyProcessor() constructors and configure it later by addKey(int key, Object cmd), addAltKey(int key, KeyProcessor processor) methods.

Canvas property is needed because Canvas.getGameAction() method is not static. I don't know why. To my mind, It should be static (it is stateless method). Because of that, it is impossible to convert key code to game action without an instance of canvas.

KeyProcessor can be used independently from XCanvas. To look up command based on key code just call KeyProcessor.process(int key) method. Key - command association can be looked up by calling method KeyProcessor.process(int key) 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.


Sergio Morozov. 2007 SourceForge.net Logo