Keyboard -Mapping DLL Tutorial

diff -r ae94777fff8f -r 59758314f811 Symbian3/PDK/Source/GUID-D34DB4A1-1B17-5FAF-A48B-E06D247B0A83.dita --- a/Symbian3/PDK/Source/GUID-D34DB4A1-1B17-5FAF-A48B-E06D247B0A83.dita Fri Jun 11 12:39:03 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-D34DB4A1-1B17-5FAF-A48B-E06D247B0A83.dita Fri Jun 11 15:24:34 2010 +0100 @@ -1,82 +1,82 @@ - - - - - -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 organised 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 ports for -the H4 reference board provide useful examples of how the tables can be constructed.

The following list outlines the structure of the tables.

The tables are organised -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.
- -
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.
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.
- -
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.
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:
- -
If no keycode can be -found that matches the scancode, for a given modifier combination, then the -algorithm returns the EKeyNull keycode.