1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Declares main application class.

    15  *

    16 */

    17 

    18 

    19 #ifndef __LAYOUT_H

    20 #define __LAYOUT_H

    21 

    22 #include <e32std.h>

    23 #include <e32base.h>

    24 #include "hidlayoutplugininterface.h"

    25 

    26 // FORWARD DECLARATIONS

    27 class TLockKeys;

    28 class THidModifier;

    29 

    30 // CLASS DECLARATION

    31 

    32 /*!

    33  CKeyboardLayout is the abstract base class for all keyboard layouts.

    34  */

    35 class CKeyboardLayout : public CHidLayoutPluginInterface

    36     {

    37 public:

    38     /*!

    39      Translate a HID usage into a Symbian raw scan code value,

    40      taking into account both the current modifier state, and the

    41      lock key (Num Lock, Caps Lock) state.

    42 

    43      This function is called by the default implementation of

    44      TranslateKey().

    45 

    46      @param aHidKey The HID usage ID of the key

    47      @param aUsagePage The HID usage page of the key

    48      @param aModifiers The current modifier state

    49      @param aLockKeys The current lock key state

    50      

    51      @result A Symbian Unicode key value, cf TKeyCode. EKeyNull (0)

    52      if the key code could not be translated.

    53      */

    54     virtual TUint16 TranslateKey(TInt aHidKey, TInt aUsagePage,

    55             THidModifier aModifiers, TLockKeys aLockKeys) const;

    56 

    57     /*!

    58      Translate a HID usage ID (keyboard usage page, 0x07) into a

    59      Symbian Unicode key value, taking into account the current

    60      modifier state. This is normally just an interface to one or

    61      more static look up tables.

    62      

    63      Unicode() is pure virtual.

    64 

    65      @param aHidKey The HID usage ID of the key

    66      @param aModifiers The current modifier state

    67      

    68      @result A Symbian Unicode key value, cf TKeyCode. EKeyNull (0)

    69      if the key code could not be translated.

    70      */

    71     virtual TUint16 Unicode(TInt aHidKey, THidModifier aModifiers) const = 0;

    72 

    73     /*!

    74      Translate a HID usage into a Symbian raw scan code value,

    75      taking into account the current modifier state.

    76 

    77      This function is called by the default implementation of

    78      TranslateKey().

    79 

    80      @param aHidKey The HID usage ID of the key

    81      @param aUsagePage The HID usage page of the key

    82      @param aModifiers The current modifier state

    83      

    84      @result A Symbian raw scan code value, cf TStdScanCode.

    85      EStdKeyNull (0) if the key code could not be translated.

    86      */

    87     virtual TInt RawScanCode(TInt aHidKey, TInt aUsagePage,

    88             THidModifier aModifiers) const;

    89 

    90     /*!

    91      Determine if a given Unicode key value corresponds to an

    92      auto-repeating key.

    93 

    94      @param aUnicodeKey Symbian Unicode key value

    95 

    96      @result ETrue if the key should be allowed to repeat.

    97      */

    98     virtual TBool IsRepeatingKey(TInt aUnicodeKey) const;

    99 

   100     /*!

   101      Determine if the given Unicode key value corresponds to a

   102      dead key.

   103 

   104      @param aUnicodeKey Symbian Unicode key value

   105 

   106      @result ETrue if the key is a dead key.

   107      */

   108     virtual TBool IsDeadKey(TInt aUnicodeKey) const;

   109 

   110     /*!

   111      Find the Unicode character, if any, which results from a

   112      combination of the dead key, aDeadKeyUnicode, followed by the

   113      second key press, aUnicodeKey.

   114 

   115      @result Symbian Unicode key value for the combination

   116      character. EKeyNull (0) if the combination wasn't found.

   117      */

   118     virtual TUint16 FindCombiningChar(TUint16 aDeadKeyUnicode,

   119             TUint16 aUnicodeKey) const;

   120 

   121     /*!

   122      Determine if the given HID key code behaves as if the shift

   123      modifier is inverted when Num Lock is active. This function is

   124      called by the default implementation of TranslateKey().

   125 

   126      @param aHidKey The HID usage ID of the key (keyboard usage page, 0x07)

   127 

   128      @result ETrue if the key changes with Num Lock

   129      */

   130     virtual TBool ChangesWithNumLock(TInt aHidKey) const;

   131 

   132     /*!

   133      Determine if the given HID key code behaves as if the shift

   134      modifier is inverted when Caps Lock is active, taking into

   135      account the current modifier state. This function is

   136      called by the default implementation of TranslateKey().

   137 

   138      @param aHidKey The HID usage ID of the key (keyboard usage page, 0x07)

   139      @param aModifiers The current modifier state

   140 

   141      @result ETrue if the key changes with Caps Lock

   142      */

   143     virtual TBool

   144             ChangesWithCapsLock(TInt aHidKey, THidModifier aModifiers) const;

   145 

   146     /*!

   147      Determine if the right Alt key (Alt Gr) should produce the same

   148      effect as pressing Control-Alt.

   149      

   150      @result ETrue if Alt Gr is equivalent to Control-Alt

   151      */

   152     virtual TBool AltGrIsControlAlt() const;

   153 

   154     /*!

   155      Return the keyboard layout ID for a given layout.

   156      */

   157     virtual TInt LayoutId() const = 0;

   158 

   159 protected:

   160     TUint16 TranslateKeyboardKey(TInt aHidKey, THidModifier aModifiers,

   161             TLockKeys aLockKeys) const;

   162     TUint16 TranslateOtherKey(TInt aHidKey, TInt aUsagePage,

   163             THidModifier aModifiers, TLockKeys aLockKeys) const;

   164 

   165 private:

   166     static TInt CheckChangingKeys(TInt aHidKey, THidModifier aModifiers);

   167     static TInt CheckModifierKeys(TInt aHidKey);

   168     static TInt CheckSpecialRawCode(TInt aHidKey, TInt aUsagePage);

   169 

   170 protected:

   171     // Scan code look-up tables:

   172 

   173     static const TInt KRawCodes[]; // standard keys from HID usage page 7

   174 

   175     struct TUsagePageKey

   176         {

   177         TInt iHidPage;

   178         TInt iHidId;

   179         TInt iScanCode;

   180         TUint16 iCode;

   181         };

   182 

   183     static const TUsagePageKey KEnhancedKeyCodes[]; // Usage page != 0x07

   184     };

   185 

   186 // ----------------------------------------------------------------------

   187 

   188 /*!

   189  Base class for all standard keyboard layouts. Assumes a specific

   190  configuration of look-up tables:

   191  

   192  - A main look-up table, indexed by HID code. This contains one or

   193  more columns of data, where each column corresponds to a particular

   194  modifier state. The size of the table is specified in the constructor. 

   195  

   196  - A list of the modifier states that correspond to each column in

   197  the main table.

   198  

   199  - A table containing special cases.  This is intended to reduce the

   200  number of columns needed in the main table.  This table is searched

   201  linearly and is zero terminated.

   202  

   203  An implementation of CKeyboardLayout::Unicode() is provided that

   204  performs a HID key look-up using the main table, and then, if

   205  no match was found, searches the special case table.

   206  */

   207 class CStandardKeyboardLayout : public CKeyboardLayout

   208     {

   209 public:

   210     /*!

   211      TSpecialKey items are used to create a standard special case

   212      table. If the HID usage ID of the key matches iHidKey, and the

   213      current modifier state matches iFoldedModifiers, then the decoded

   214      key code will be iUnicode.

   215      */

   216     struct TSpecialKey

   217         {

   218         TUint16 iHidKey; //!< HID key usage (keyboard usage page)

   219         TUint8 iFoldedModifiers; //!< Modifiers, as from THidModifier::Fold()

   220         TUint16 iUnicode; //!< The resulting Unicode value

   221         };

   222 

   223 public:

   224     /*!

   225      Constructor

   226 

   227      @param aColumnMap Mapping from modifier state to main table columns

   228      @param aMapSize Size of the columns map, in bytes

   229      @param aKeyCodes The main look-up table

   230      @param aTableSize Size of the main table, in bytes

   231      @param aSpecialCases The special case table

   232      */

   233     CStandardKeyboardLayout(const TInt* aColumnMap, TInt aMapSize,

   234             const TUint16* aKeyCodes, TInt aTableSize,

   235             const TSpecialKey* aSpecialCases);

   236 

   237     /*!

   238      Translate a HID usage ID (keyboard usage page, 0x07) into a

   239      Symbian Unicode key value, taking into account the current

   240      modifier state.      

   241 

   242      @param aHidKey The HID usage ID of the key

   243      @param aModifiers The current modifier state

   244      

   245      @result A Symbian Unicode key value, cf TKeyCode.  EKeyNull (0)

   246      if the key code could not be translated.

   247      */

   248     virtual TUint16 Unicode(TInt aHidKey, THidModifier aModifiers) const;

   249 

   250 protected:

   251     /*!

   252      Search for a given HID usage ID (keyboard usage page, 0x07)

   253      in the special case table.

   254 

   255      @param aMap The special case table

   256      @param aHidKey HID usage ID to search for

   257      @param aFoldedModifiers Modifier state to search for

   258 

   259      @result A Symbian Unicode key value, cf TKeyCode. EKeyNull (0)

   260      if the key code could not be translated.

   261      */

   262     static TUint16 FindSpecialKey(const TSpecialKey* aMap, TInt aHidKey,

   263             TUint8 aFoldedModifiers);

   264 

   265 protected:

   266     // Standard look-up table:

   267     const TInt* iColumnMap;

   268     const TUint16* iKeyCodes;

   269 

   270     const TInt iNumColumns;

   271     const TInt iNumKeys;

   272 

   273     // Special cases:

   274     const TSpecialKey* iSpecialCases;

   275     };

   276 

   277 // ----------------------------------------------------------------------

   278 

   279 /*!

   280  Base class for keyboard layouts that use dead keys, derived from

   281  CStandardKeyboardLayout. Assumes a specific configuration of look-up

   282  tables:

   283  

   284  - An index table containing one TIndexPair entry for each dead

   285  key. The TIndexPair provides the unicode value for the dead key,

   286  and a link to a TKeyPair table.

   287  

   288  - One table of TKeyPair items for each dead key. Each TKeyPair

   289  contains the Unicode value for the combination (second) key press

   290  together with the Unicode key value that should result.

   291  

   292  - Other tables as for CStandardKeyboardLayout

   293  

   294  Implementations of CKeyboardLayout::IsDeadKey() and

   295  CKeyboardLayout::FindCombiningChar() are provided that can

   296  use these dead keys tables.

   297  */

   298 class CDeadKeyLayout : public CStandardKeyboardLayout

   299     {

   300 public:

   301     /*!

   302      TKeyPair items are used to create dead key tables. The dead key

   303      followed by a Unicode key code iBaseChar will produce the decoded

   304      Unicode value of iComboChar. The Unicode value for the dead key

   305      itself is given in a TIndexPair structure.

   306      */

   307     struct TKeyPair

   308         {

   309         TUint16 iBaseChar; //!< Unicode character that follows the dead key

   310         TUint16 iComboChar; //!< Resulting Unicode value

   311         };

   312 

   313     /*!

   314      TIndexPair items are used to create dead key tables. There is one

   315      TIndexPair for each possible dead key. Each TIndexPair links in turn

   316      to a table of TKeyPair items.

   317      */

   318     struct TIndexPair

   319         {

   320         TUint16 iUnicode; //!< Unicode value for the dead key

   321         const TKeyPair *iMap; //!< Corresponding table of TKeyPair items

   322         };

   323 

   324 public:

   325     /*!

   326      Constructor

   327 

   328      @param aColumnMap Mapping from modifier state to main table columns

   329      @param aMapSize Size of the columns map, in bytes

   330      @param aKeyCodes The main look-up table

   331      @param aTableSize Size of the main table, in bytes

   332      @param aSpecialCases The special case table

   333      @param aDeadKeyIndex The dead key index table

   334      */

   335             CDeadKeyLayout(const TInt* aColumnMap, TInt aMapSize,

   336                     const TUint16* aKeyCodes, TInt aTableSize,

   337                     const TSpecialKey* aSpecialCases,

   338                     const TIndexPair* aDeadKeyIndex);

   339 

   340     /*!

   341      Determine if the given Unicode key value corresponds to a

   342      dead key.

   343 

   344      @param aUnicodeKey Symbian Unicode key value

   345 

   346      @result ETrue if the key is a dead key.

   347      */

   348     virtual TBool IsDeadKey(TInt aUnicodeKey) const;

   349 

   350     /*!

   351      Find the Unicode character, if any, which results from a

   352      combination of the dead key, aDeadKeyUnicode, followed by the

   353      second key press, aUnicodeKey.

   354 

   355      @result Symbian Unicode key value for the combination

   356      character. EKeyNull (0) if the combination wasn't found.

   357      */

   358     virtual TUint16 FindCombiningChar(TUint16 aDeadKeyUnicode,

   359             TUint16 aKeyCode) const;

   360 

   361 protected:

   362     const TIndexPair* iDeadKeyIndex;

   363 

   364     };

   365 

   366 // ----------------------------------------------------------------------

   367 

   368 #endif