ui/events/keycodes/keyboard_code_conversion.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_
   6 #define UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_
   7
   8 #include "base/compiler_specific.h"
   9 #include "base/strings/string16.h"
  10 #include "ui/events/events_base_export.h"
  11 #include "ui/events/keycodes/keyboard_codes.h"
  12
  13 namespace ui {
  14
  15 enum class DomCode;
  16 enum class DomKey;
  17
  18 // Helper functions to get the meaning of a Windows key code in a
  19 // platform independent way. It supports control characters as well.
  20 // It assumes a US keyboard layout is used, so it may only be used when there
  21 // is no native event or no better way to get the character.
  22 //
  23 // For example, if a virtual keyboard implementation can only generate key
  24 // events with key_code and flags information, then there is no way for us to
  25 // determine the actual character that should be generate by the key. Because
  26 // a key_code only represents a physical key on the keyboard, it has nothing
  27 // to do with the actual character printed on that key. In such case, the only
  28 // thing we can do is to assume that we are using a US keyboard and get the
  29 // character according to US keyboard layout definition. Preferably, such
  30 // events should be created using a full KeyEvent constructor, explicitly
  31 // specifying the character and DOM 3 values as well as the legacy VKEY.
  32 //
  33 // TODO(kpschoedel): replace remaining uses of the ...FromKeyCode() functions
  34 // and remove them, to avoid future creation of underspecified key events.
  35 // crbug.com/444045
  36 EVENTS_BASE_EXPORT base::char16 GetCharacterFromKeyCode(KeyboardCode key_code,
  37                                                         int flags);
  38 EVENTS_BASE_EXPORT bool GetMeaningFromKeyCode(KeyboardCode key_code,
  39                                               int flags,
  40                                               DomKey* dom_key,
  41                                               base::char16* character);
  42
  43 // Helper function to map a physical key state (dom_code and flags)
  44 // to a meaning (dom_key and character, together corresponding to the
  45 // DOM keyboard event |key| value), along with a corresponding non-located
  46 // Windows-based key_code.
  47 //
  48 // This follows a US keyboard layout, so it should only be used when there
  49 // is no other better way to obtain the meaning (e.g. actual keyboard layout).
  50 // Returns true and sets the output parameters if the (dom_code, flags) pair
  51 // has an interpretation in the US English layout; otherwise the output
  52 // parameters are untouched.
  53 EVENTS_BASE_EXPORT bool DomCodeToUsLayoutMeaning(DomCode dom_code,
  54                                                  int flags,
  55                                                  DomKey* dom_key,
  56                                                  base::char16* character,
  57                                                  KeyboardCode* key_code)
  58     WARN_UNUSED_RESULT;
  59
  60 // Obtains the control character corresponding to a physical key;
  61 // that is, the meaning of the physical key state (dom_code, and flags
  62 // containing EF_CONTROL_DOWN) under the base US English layout.
  63 // Returns true and sets the output parameters if the (dom_code, flags) pair
  64 // is interpreted as a control character; otherwise the output parameters
  65 // are untouched.
  66 EVENTS_BASE_EXPORT bool DomCodeToControlCharacter(DomCode dom_code,
  67                                                   int flags,
  68                                                   DomKey* dom_key,
  69                                                   base::char16* character,
  70                                                   KeyboardCode* key_code)
  71     WARN_UNUSED_RESULT;
  72
  73 // Returns the DomKey value associated with an ASCII/Unicode character.
  74 // All printable characters and most other character codes use
  75 // DomKey::CHARACTER, but a few ASCII C0 codes have their own DomKey.
  76 EVENTS_BASE_EXPORT DomKey CharacterToDomKey(uint32 character);
  77
  78 // Returns a Windows-based VKEY for a non-printable DOM Level 3 |key|.
  79 // The returned VKEY is non-located (e.g. VKEY_SHIFT).
  80 EVENTS_BASE_EXPORT KeyboardCode
  81 NonPrintableDomKeyToKeyboardCode(DomKey dom_key);
  82
  83 // Determine the non-located VKEY corresponding to a located VKEY.
  84 // Most modifier keys have two kinds of KeyboardCode: located (e.g.
  85 // VKEY_LSHIFT and VKEY_RSHIFT), that indentify one of two specific
  86 // physical keys, and non-located (e.g. VKEY_SHIFT) that identify
  87 // only the operation. Similarly digit keys have a number-pad variant
  88 // (e.g. VKEY_NUMPAD1 on the number pad vs VKEY_1 on the main keyboard),
  89 // except that in this case the main keyboard code doubles as the
  90 // non-located value.
  91 EVENTS_BASE_EXPORT KeyboardCode
  92 LocatedToNonLocatedKeyboardCode(KeyboardCode key_code);
  93
  94 // Determine the located VKEY corresponding to a non-located VKEY.
  95 EVENTS_BASE_EXPORT KeyboardCode
  96 NonLocatedToLocatedKeyboardCode(KeyboardCode key_code, DomCode dom_code);
  97
  98 // Returns a DOM Level 3 |code| from a Windows-based VKEY value.
  99 // This assumes a US layout and should only be used when |code| cannot be
 100 // determined from a physical scan code, for example when a key event was
 101 // generated synthetically by JavaScript with only a VKEY value supplied.
 102 EVENTS_BASE_EXPORT DomCode UsLayoutKeyboardCodeToDomCode(KeyboardCode key_code);
 103
 104 // Returns the Windows-based VKEY value corresponding to a DOM Level 3 |code|,
 105 // assuming a base US English layout. The returned VKEY is located
 106 // (e.g. VKEY_LSHIFT).
 107 EVENTS_BASE_EXPORT KeyboardCode DomCodeToUsLayoutKeyboardCode(DomCode dom_code);
 108
 109 }  // namespace ui
 110
 111 #endif  // UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_