diff -r 578be2adaf3e -r 307f4279f433 Adaptation/GUID-D34DB4A1-1B17-5FAF-A48B-E06D247B0A83.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Adaptation/GUID-D34DB4A1-1B17-5FAF-A48B-E06D247B0A83.dita Fri Oct 15 14:32:18 2010 +0100 @@ -0,0 +1,85 @@ + + + + + +Keyboard Mapping DLL Tutorial +

A keyboard mapping DLL provides a set of lookup tables that the +generic ektran.dll uses to convert scancodes +to keycodes. A keyboard mapping DLL is implemented in a base port.

+

The basic purpose of the tables is to provide a mapping from scancodes +to keycodes, so that, given a scancode, the corresponding keycode +can be found. The tables are organized so that there is, in effect, +one set of lookup tables for each likely combination of modifier key +states. ektran.dll compares the modifier keys +that have been pressed with the stored modifier key state combinations +to decide which set of lookup tables to use.

+

An outline set of tables is provided in the template port.

+

The following list outlines the structure of the tables.

+
    +

  1. The tables are +organized in a hierarchical structure. The start of this hierarchy +is the root table, defined by a SConvTable struct. +This contains:

      +

    • an array of +pointers to nodes, where each node is defined by the SConvTableNode struct. Each node corresponds to a specific combination of modifier +key states.

      • +

    • a field containing +the total number of such nodes.

      • +
    +Keyboard Mapping Table + +
    2. +

  2. The combination +of modifier key states that each node represents is encapsulated by +a TMaskedModifiers object. One of these objects +is embedded within each node.

    A TMaskedModifiers object consists of a mask, and a value for comparison. For example, +if an instance is set to the following:

    iMask = EModifierShift | EModifierCtrl | EModifierFunc +iValue = EModifierShift | EModifierFunc

    then a match +occurs only for the following combination of modifier key states:

    ctrl + shift + not Fn

    i.e. a match occurs only if ctrl and shift are pressed, and only if Fn is not pressed. Other modifier keys are ignored, +i.e. it does not matter whether or not they are pressed.

    In +C++ code, this is expressed as:

    inline TBool MatchesMaskedValue(TInt aModifiers,const TMaskedModifiers &aMaskedModifiers) + { + return (TBool)((aModifiers & aMaskedModifiers.iMask) == aMaskedModifiers.iValue); + }

    where aModifiers contains the +modifier key combination to be tested.

    3. +

  3. In principle, +each node represents scancode-to-keycode mappings by associating one +or more pairs (or range) of scancodes with corresponding blocks +of keycodes. Each pair represents an inclusive and contiguous range +of scancodes.

    Each pair (or range) of scancodes may be "discontiguous" +from the next.

    The association is made through a table defined +by the SConvSubTable struct. This has:

      +

    • a SScanCodeBlockList object that contains pointers to a number of SScanCodeBlock objects, each of which contains the start and end values defining +a range of scancodes.

      • +

    • a pointer to +a table containing the target keycodes. The target keycodes are arranged +so that successive scancode pairs are associated with successive blocks +of keycodes as the following diagram shows.

      • +
    +Target keycodes + +

    This means that successive scancodes, for example, from +"A1" through to "B1" are represented by the successive keycodes "keycode +for A1" through to "keycode for B1"; scancode "A2" is represented +by "keycode for A2", which follows "keycode for B1" in the keycode +table.

    4. +

  4. To allow for +possible reuse of keycode tables, a node can point to more than one SConvSubTable. The following diagram shows an example of +this:

    +Reusing keycode tables + +
    5. +

  5. If no keycode +can be found that matches the scancode, for a given modifier combination, +then the algorithm returns the EKeyNull keycode.

    6. +
+
See +also

Concepts

+ \ No newline at end of file