Merge pull request #720 from CapeLeidokos/pr_keycode_redesign

Key union converted to a proper class

NEWS.md

@@ -156,6 +156,22 @@ The [FirmwareDump](doc/plugin/FirmwareDump.md) plugin makes it possible to dump
 
 ## Breaking changes
 
+### Implementation of type Key internally changed from C++ union to class
+
+Type `Key` was originally implemented as a C++ union. For technical reasons
+it had to be converted to a C++ class. This implies that the double usage
+of the original union, holding either raw data (member `raw`) or key code/key flags
+data (members `keyCode` and `flags`) is no more possible. 
+
+Direct use of member `raw` will 
+emit a diagnostic compiler message but will cause the firmware linking 
+process to fail. For a deprecation
+periode `keyCode` and `flags` keep on being supported but will cause 
+deprecation warnings during compile. 
+
+Please see the [relevant upgrade notes](UPGRADING.md##implementation-of-type-key-internally-changed-from-union-to-class)
+for information about how to upgrade legacy code.
+
 ### The `NumPad` plugin no longer toggles `NumLock`
 
 The `NumPad` plugin used to toggle `NumLock` when switching to the NumPad layer. This caused issues on OSX where `NumLock` is interpreted as `Clear`. For this reason, the plugin no longer does this. As a consequence, everyone's encouraged to update their keymap so that the numpad layer uses normal number keys instead of the keypad numbers. See [Model01-Firmware#79](https://github.com/keyboardio/Model01-Firmware/pull/79) for an example about how to do this.

UPGRADING.md

@@ -12,6 +12,7 @@ If any of this does not make sense to you, or you have trouble updating your .in
     - [Bidirectional communication for plugins](#bidirectional-communication-for-plugins)
     - [Consistent timing](#consistent-timing)
   + [Breaking changes](#breaking-changes)
+    - [Implementation of type Key internally changed from C++ union to class](#implementation-of-type-key-internally-changed-from-union-to-class)
     - [The `RxCy` macros and peeking into the keyswitch state](#the-rxcy-macros-and-peeking-into-the-keyswitch-state)
     - [HostOS](#hostos)
     - [MagicCombo](#magiccombo)
@@ -33,11 +34,11 @@ If any of this does not make sense to you, or you have trouble updating your .in
 
 We are introducing - or rather, replacing - the older hardware plugins, with a system that's much more composable, more extensible, and will allow us to better support new devices, different MCUs, and so on.
 
-### For end-users
+#### For end-users
 
 For end users, this doesn't come with any breaking changes. A few things have been deprecated (`ROWS`, `COLS`, `LED_COUNT`, `KeyboardHardware`), but they still function for the time being.
 
-### For developers
+#### For developers
 
 For those wishing to port Kaleidoscope to devices it doesn't support yet, the new API should make most things considerably easier. Please see the (work in progress) documentation in [doc/device-apis.md](doc/device-apis.md).
 
@@ -313,6 +314,45 @@ As a developer, one can continue using `millis()`, but migrating to `Kaleidoscop
 
 ## Breaking changes
 
+### Implementation of type Key internally changed from C++ union to class
+
+#### For end-users
+
+This is a breaking change only if your code accesses the member `raw` of
+type `Key` directly, for instance in a construct like
+
+```cpp
+Key k;
+k.raw = Key_A.raw;
+```
+
+This can easily be fixed by replacing read access to `Key::raw` with `Key::getRaw()`
+and write access with `Key::setRaw(...)`.
+
+```cpp
+Key k;
+k.setRaw(Key_A.getRaw());
+```
+
+Moreover, the compiler will still emit warnings in places of the code where
+members `keyCode` and `flags` of the original type `Key` are used, like e.g.
+
+```cpp
+Key k;
+k.keyCode = Key_A.keyCode;
+k.flags = Key_A.flags;
+```
+
+These warnings can be also resolved by using the appropriate accessor methods
+`Key::getKeyCode()`/`Key::setKeyCode()` and `Key::getFlags()`/`Key::setKlags()`
+instead.
+
+```cpp
+Key k;
+k.setKeyCode(Key_A.getKeyCode());
+k.setFlags(Key_A.getFlags());
+```
+
 ### The `RxCy` macros and peeking into the keyswitch state
 
 The `RxCy` macros changed from being indexes into a per-hand bitmap to being an

doc/plugin/Cycle.md

@@ -25,10 +25,10 @@ Key_Cycle
 
 // later in the Sketch:
 void cycleAction(Key previous_key, uint8_t cycle_count) {
-  bool is_shifted = previous_key.flags & SHIFT_HELD;
+  bool is_shifted = previous_key.getFlags() & SHIFT_HELD;
-  if (previous_key.keyCode == Key_A.keyCode && is_shifted)
+  if (previous_key.getKeyCode() == Key_A.getKeyCode() && is_shifted)
       cycleThrough (LSHIFT(Key_A), LSHIFT(Key_B), LSHIFT(Key_C));
-  if (previous_key.keyCode == Key_A.keyCode && !is_shifted)
+  if (previous_key.getKeyCode() == Key_A.getKeyCode() && !is_shifted)
       cycleThrough (Key_A, Key_B, Key_C);
 }
 

examples/Keystrokes/Cycle/Cycle.ino

@@ -40,7 +40,7 @@ KEYMAPS(
 // *INDENT-ON*
 
 void cycleAction(Key previous_key, uint8_t cycle_count) {
-  if (previous_key.raw == Key_E.raw) {
+  if (previous_key == Key_E) {
     if (cycle_count == 1) {
       Cycle.replace(Key_F);
     } else if (cycle_count == 2) {
@@ -48,10 +48,10 @@ void cycleAction(Key previous_key, uint8_t cycle_count) {
     }
   }
 
-  bool is_shifted = previous_key.flags & SHIFT_HELD;
+  bool is_shifted = previous_key.getFlags() & SHIFT_HELD;
-  if (previous_key.keyCode == Key_A.keyCode && is_shifted)
+  if (previous_key.getKeyCode() == Key_A.getKeyCode() && is_shifted)
     cycleThrough(LSHIFT(Key_A), LSHIFT(Key_B), LSHIFT(Key_C), LSHIFT(Key_D));
-  if (previous_key.keyCode == Key_A.keyCode && !is_shifted)
+  if (previous_key.getKeyCode() == Key_A.getKeyCode() && !is_shifted)
     cycleThrough(Key_A, Key_B, Key_C, Key_D);
 }
 

examples/LEDs/LED-AlphaSquare/LED-AlphaSquare.ino

@@ -47,7 +47,7 @@ const macro_t *macroAction(uint8_t macro_index, uint8_t key_state) {
     return MACRO_NONE;
 
   if (macro_index == 0) {
-    for (uint8_t i = Key_A.keyCode; i <= Key_0.keyCode; i++) {
+    for (uint8_t i = Key_A.getKeyCode(); i <= Key_0.getKeyCode(); i++) {
       LEDControl.set_all_leds_to(0, 0, 0);
       LEDControl.syncLeds();
       delay(100);

src/kaleidoscope/hooks.h

@@ -19,7 +19,7 @@
 #include <Arduino.h>
 
 namespace kaleidoscope {
-union Key;
+class Key;
 }
 
 #include "kaleidoscope/KeyAddr.h"

src/kaleidoscope/key_defs.h

@@ -30,63 +30,163 @@
 
 namespace kaleidoscope {
 
-union Key {
+class Key {
 
-  struct {
+ public:
-    uint8_t keyCode;
+
-    uint8_t flags;
+  typedef uint16_t StorageType;
-  };
-  uint16_t raw;
 
   Key() = default;
 
-  constexpr Key(uint8_t __keyCode, uint8_t __flags)
+  constexpr Key(uint16_t raw)
-    : keyCode(__keyCode), flags(__flags) {
+    : Key{(uint8_t)(raw & 0x00FF), (uint8_t)(raw >> 8)}
+  {}
+
+  constexpr Key(uint8_t key_code, uint8_t flags)
+    : keyCode{key_code},
+      flags{flags}
+  {}
+
+  void setFlags(uint8_t new_flags) {
+    flags.value_ = new_flags;
+  }
+  constexpr const uint8_t &getFlags() const {
+    return flags.value_;
+  }
+
+  void setKeyCode(uint8_t key_code) {
+    keyCode.value_ = key_code;
+  }
+  constexpr const uint8_t &getKeyCode() const {
+    return keyCode.value_;
   }
 
-  constexpr Key(uint16_t __raw)
+  void setRaw(uint16_t raw) {
-    : raw(__raw) {
+    flags.value_  = (uint8_t)(raw >> 8);
+    keyCode.value_ = (uint8_t)(raw & 0x00FF);
+  }
+  constexpr uint16_t getRaw() const {
+    return (uint16_t)(
+             ((uint16_t)flags.value_ << 8)
+             + (uint16_t)keyCode.value_
+           );
   }
 
-  constexpr bool operator==(const uint16_t rhs) const {
+  constexpr bool operator==(const StorageType rhs) const {
-    return this->raw == rhs;
+    return this->getRaw() == rhs;
   }
   constexpr bool operator==(const Key& rhs) const {
-    return this->raw == rhs.raw;
+    return (this->keyCode.value_ == rhs.keyCode.value_)
+           && (this->flags.value_ == rhs.flags.value_);
   }
-  Key& operator=(const uint16_t raw) {
+  Key& operator=(const StorageType raw) {
-    this->raw = raw;
+    this->setRaw(raw);
     return *this;
   }
   constexpr bool operator!=(const Key& rhs) const {
     return !(*this == rhs);
   }
-  constexpr bool operator>=(const uint16_t raw) const {
+  constexpr bool operator>=(const StorageType raw) const {
-    return this->raw >= raw;
+    return this->getRaw() >= raw;
   }
-  constexpr bool operator<=(const uint16_t raw) const {
+  constexpr bool operator<=(const StorageType raw) const {
-    return this->raw <= raw;
+    return this->getRaw() <= raw;
   }
-  constexpr bool operator>(const uint16_t raw) const {
+  constexpr bool operator>(const StorageType raw) const {
-    return this->raw > raw;
+    return this->getRaw() > raw;
   }
-  constexpr bool operator<(const uint16_t raw) const {
+  constexpr bool operator<(const StorageType raw) const {
-    return this->raw < raw;
+    return this->getRaw() < raw;
   }
   constexpr bool operator>=(const Key& other) const {
-    return this->raw >= other.raw;
+    return this->getRaw() >= other.getRaw();
   }
   constexpr bool operator<=(const Key& other) const {
-    return this->raw <= other.raw;
+    return this->getRaw() <= other.getRaw();
   }
   constexpr bool operator>(const Key& other) const {
-    return this->raw > other.raw;
+    return this->getRaw() > other.getRaw();
   }
   constexpr bool operator<(const Key& other) const {
-    return this->raw < other.raw;
+    return this->getRaw() < other.getRaw();
+  }
+
+  Key readFromProgmem() const {
+    return Key{pgm_read_byte(&(this->getKeyCode())),
+               pgm_read_byte(&(this->getFlags()))};
   }
+
+  // The data proxy objects are required to only emit deprecation
+  // messages when members 'keyCode' and 'flags' are accessed directly
+  // but not if accessed by class Key.
+  //
+  // Once the deprecation periode elapsed both proxy members 'keyCode'
+  // and 'flags' of class Key can be converted to private uint8_t members
+  // of class Key. Class DataProxy can then be safely removed.
+  //
+  class DataProxy {
+
+    friend class Key;
+
+   public:
+
+    DataProxy() = default;
+
+    constexpr DataProxy(uint8_t value) : value_{value} {}
+
+    DEPRECATED(DIRECT_KEY_MEMBER_ACCESS)
+    DataProxy &operator=(uint8_t value) {
+      value_ = value;
+      return *this;
+    }
+
+    DEPRECATED(DIRECT_KEY_MEMBER_ACCESS)
+    constexpr operator uint8_t () const {
+      return value_;
+    }
+
+   private:
+    uint8_t value_;
+  };
+
+  DataProxy keyCode;
+  DataProxy flags;
+
+  // For technical reasons the implementation of type Key has been changed
+  // from a C++ union to a class.
+  //
+  // Although it is not entirely possible to retain all features of the
+  // union-based implementation, we can still warn for access to member raw.
+  //
+  // After converting Key::raw to a static member, it can now still be accessed
+  // as before. But accessing it will trigger a compiler message that informs
+  // the user about the importance of replacing its access
+  // with Key::getRaw() or Key::setRaw().
+  //
+  // This is not a deprecation! All code that accesses Key::raw directly
+  // will fail to link instead.
+  //
+  // This is because there is no instance provided for the static fake
+  // member Key::raw. Because of that, this approach does not mean
+  // any harm. The emitted diagnostics help pointing users
+  // to the places in the code where changes are required.
+  //
+  DEPRECATED(KEY_MEMBER_RAW_ACCESS)
+  static uint16_t raw;
 };
 
+static_assert(sizeof(Key) == 2, "sizeof(Key) changed");
+
+// Overload this function to define alternative conversions to type Key.
+//
+constexpr Key convertToKey(Key k) {
+  return k;
+}
+
+constexpr Key addFlags(Key k, uint8_t add_flags) {
+  return Key(k.getKeyCode(), k.getFlags() | add_flags);
+}
+
 } // namespace kaleidoscope
 
 // For compatibility reasons make the Key class also available
@@ -105,11 +205,11 @@ typedef kaleidoscope::Key Key_;
 #define SYNTHETIC         B01000000
 #define RESERVED          B10000000
 
-#define LCTRL(k)  Key(k.keyCode, k.flags | CTRL_HELD)
+#define LCTRL(k)  Key(k.getKeyCode(), k.getFlags() | CTRL_HELD)
-#define LALT(k)   Key(k.keyCode, k.flags | LALT_HELD)
+#define LALT(k)   Key(k.getKeyCode(), k.getFlags() | LALT_HELD)
-#define RALT(k)   Key(k.keyCode, k.flags | RALT_HELD)
+#define RALT(k)   Key(k.getKeyCode(), k.getFlags() | RALT_HELD)
-#define LSHIFT(k) Key(k.keyCode, k.flags | SHIFT_HELD)
+#define LSHIFT(k) Key(k.getKeyCode(), k.getFlags() | SHIFT_HELD)
-#define LGUI(k)   Key(k.keyCode, k.flags | GUI_HELD)
+#define LGUI(k)   Key(k.getKeyCode(), k.getFlags() | GUI_HELD)
 
 // we assert that synthetic keys can never have keys held, so we reuse the _HELD bits
 #define IS_SYSCTL                  B00000001
@@ -153,5 +253,9 @@ typedef kaleidoscope::Key Key_;
    use the 10 lsb as the HID Consumer code. If you need to get the keycode of a Consumer key
    use the CONSUMER(key) macro this will return the 10bit keycode.
 */
-#define CONSUMER(key) (key.raw & 0x03FF)
+#define CONSUMER(key) (key.getRaw() & 0x03FF)
 #define CONSUMER_KEY(code, flags) Key((code) | ((flags | SYNTHETIC|IS_CONSUMER) << 8))
+
+namespace kaleidoscope {
+constexpr Key bad_keymap_key{0, RESERVED};
+}

src/kaleidoscope/key_events.cpp

@@ -19,24 +19,24 @@
 #include "kaleidoscope/plugin.h"
 
 static bool handleSyntheticKeyswitchEvent(Key mappedKey, uint8_t keyState) {
-  if (mappedKey.flags & RESERVED)
+  if (mappedKey.getFlags() & RESERVED)
     return false;
 
-  if (!(mappedKey.flags & SYNTHETIC))
+  if (!(mappedKey.getFlags() & SYNTHETIC))
     return false;
 
-  if (mappedKey.flags & IS_CONSUMER) {
+  if (mappedKey.getFlags() & IS_CONSUMER) {
     if (keyIsPressed(keyState))
       kaleidoscope::hid::pressConsumerControl(mappedKey);
-  } else if (mappedKey.flags & IS_SYSCTL) {
+  } else if (mappedKey.getFlags() & IS_SYSCTL) {
     if (keyIsPressed(keyState)) {
     } else if (keyWasPressed(keyState)) {
       kaleidoscope::hid::pressSystemControl(mappedKey);
       kaleidoscope::hid::releaseSystemControl(mappedKey);
     }
-  } else if (mappedKey.flags & IS_INTERNAL) {
+  } else if (mappedKey.getFlags() & IS_INTERNAL) {
     return false;
-  } else if (mappedKey.flags & SWITCH_TO_KEYMAP) {
+  } else if (mappedKey.getFlags() & SWITCH_TO_KEYMAP) {
     // Should not happen, handled elsewhere.
   }
 
@@ -47,7 +47,7 @@ static bool handleKeyswitchEventDefault(Key mappedKey, KeyAddr key_addr, uint8_t
   //for every newly pressed button, figure out what logical key it is and send a key down event
   // for every newly released button, figure out what logical key it is and send a key up event
 
-  if (mappedKey.flags & SYNTHETIC) {
+  if (mappedKey.getFlags() & SYNTHETIC) {
     handleSyntheticKeyswitchEvent(mappedKey, keyState);
   } else if (keyToggledOn(keyState)) {
     kaleidoscope::hid::pressKey(mappedKey);
@@ -82,7 +82,7 @@ void handleKeyswitchEvent(Key mappedKey, KeyAddr key_addr, uint8_t keyState) {
     /* If a key had an on event, we update the live composite keymap. See
      * layers.h for an explanation about the different caches we have. */
     if (keyToggledOn(keyState)) {
-      if (mappedKey.raw == Key_NoKey.raw || keyState & EPHEMERAL) {
+      if (mappedKey == Key_NoKey || keyState & EPHEMERAL) {
         Layer.updateLiveCompositeKeymap(key_addr);
       } else {
         Layer.updateLiveCompositeKeymap(key_addr, mappedKey);
@@ -108,7 +108,7 @@ void handleKeyswitchEvent(Key mappedKey, KeyAddr key_addr, uint8_t keyState) {
      * The condition here means that if mappedKey and key_addr are both valid,
      *   the mappedKey wins - we don't re-look-up the mappedKey
      */
-    if (mappedKey.raw == Key_NoKey.raw) {
+    if (mappedKey == Key_NoKey) {
       mappedKey = Layer.lookup(key_addr);
     }
 
@@ -133,7 +133,7 @@ void handleKeyswitchEvent(Key mappedKey, KeyAddr key_addr, uint8_t keyState) {
     return;
 
   mappedKey = Layer.eventHandler(mappedKey, key_addr, keyState);
-  if (mappedKey.raw == Key_NoKey.raw)
+  if (mappedKey == Key_NoKey)
     return;
   handleKeyswitchEventDefault(mappedKey, key_addr, keyState);
 }

src/kaleidoscope/keymaps.h

@@ -24,7 +24,7 @@ namespace kaleidoscope {
 
 inline
 Key keyFromKeymap(uint8_t layer, KeyAddr key_addr) {
-  return pgm_read_word(&keymaps_linear[layer][key_addr.toInt()].raw);
+  return keymaps_linear[layer][key_addr.toInt()].readFromProgmem();
 }
 
 namespace internal {

src/kaleidoscope/layers.cpp

@@ -43,8 +43,8 @@ uint8_t Layer_::active_layers_[Kaleidoscope.device().numKeys()];
 Key(*Layer_::getKey)(uint8_t layer, KeyAddr key_addr) = Layer.getKeyFromPROGMEM;
 
 void Layer_::handleKeymapKeyswitchEvent(Key keymapEntry, uint8_t keyState) {
-  if (keymapEntry.keyCode >= LAYER_SHIFT_OFFSET) {
+  if (keymapEntry.getKeyCode() >= LAYER_SHIFT_OFFSET) {
-    uint8_t target = keymapEntry.keyCode - LAYER_SHIFT_OFFSET;
+    uint8_t target = keymapEntry.getKeyCode() - LAYER_SHIFT_OFFSET;
 
     switch (target) {
     case KEYMAP_NEXT:
@@ -86,15 +86,15 @@ void Layer_::handleKeymapKeyswitchEvent(Key keymapEntry, uint8_t keyState) {
     }
   } else if (keyToggledOn(keyState)) {
     // switch keymap and stay there
-    if (Layer.isActive(keymapEntry.keyCode) && keymapEntry.keyCode)
+    if (Layer.isActive(keymapEntry.getKeyCode()) && keymapEntry.getKeyCode())
-      deactivate(keymapEntry.keyCode);
+      deactivate(keymapEntry.getKeyCode());
     else
-      activate(keymapEntry.keyCode);
+      activate(keymapEntry.getKeyCode());
   }
 }
 
 Key Layer_::eventHandler(Key mappedKey, KeyAddr key_addr, uint8_t keyState) {
-  if (mappedKey.flags != (SYNTHETIC | SWITCH_TO_KEYMAP))
+  if (mappedKey.getFlags() != (SYNTHETIC | SWITCH_TO_KEYMAP))
     return mappedKey;
 
   handleKeymapKeyswitchEvent(mappedKey, keyState);

src/kaleidoscope/plugin/Cycle.cpp

@@ -28,7 +28,7 @@ uint8_t Cycle::cycle_count_;
 
 // --- helpers ---
 
-#define isCycle(k) (k.raw == kaleidoscope::ranges::CYCLE)
+#define isCycle(k) (k.getRaw() == kaleidoscope::ranges::CYCLE)
 
 // --- api ---
 
@@ -46,10 +46,7 @@ void Cycle::replace(Key key) {
 
 void Cycle::replace(uint8_t cycle_size, const Key cycle_steps[]) {
   uint8_t idx = cycle_count_ % cycle_size;
-  Key key;
+  replace(cycle_steps[idx].readFromProgmem());
-
-  key.raw = pgm_read_word(&cycle_steps[idx].raw);
-  replace(key);
 }
 
 // --- hooks ---
@@ -67,13 +64,13 @@ EventHandlerResult Cycle::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, ui
 
   if (!isCycle(mapped_key)) {
     if (keyToggledOn(key_state)) {
-      current_modifier_flags_ |= toModFlag(mapped_key.keyCode);
+      current_modifier_flags_ |= toModFlag(mapped_key.getKeyCode());
-      last_non_cycle_key_.keyCode = mapped_key.keyCode;
+      last_non_cycle_key_.setKeyCode(mapped_key.getKeyCode());
-      last_non_cycle_key_.flags = current_modifier_flags_;
+      last_non_cycle_key_.setFlags(current_modifier_flags_);
       cycle_count_ = 0;
     }
     if (keyToggledOff(key_state)) {
-      current_modifier_flags_ &= ~toModFlag(mapped_key.keyCode);
+      current_modifier_flags_ &= ~toModFlag(mapped_key.getKeyCode());
     }
     return EventHandlerResult::OK;
   }
@@ -89,18 +86,18 @@ EventHandlerResult Cycle::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, ui
 
 uint8_t Cycle::toModFlag(uint8_t keyCode) {
   switch (keyCode) {
-  case Key_LeftShift.keyCode:
+  case Key_LeftShift.getKeyCode():
-  case Key_RightShift.keyCode:
+  case Key_RightShift.getKeyCode():
     return SHIFT_HELD;
-  case Key_LeftAlt.keyCode:
+  case Key_LeftAlt.getKeyCode():
     return LALT_HELD;
-  case Key_RightAlt.keyCode:
+  case Key_RightAlt.getKeyCode():
     return RALT_HELD;
-  case Key_LeftControl.keyCode:
+  case Key_LeftControl.getKeyCode():
-  case Key_RightControl.keyCode:
+  case Key_RightControl.getKeyCode():
     return CTRL_HELD;
-  case Key_LeftGui.keyCode:
+  case Key_LeftGui.getKeyCode():
-  case Key_RightGui.keyCode:
+  case Key_RightGui.getKeyCode():
     return GUI_HELD;
   default:
     return 0;

src/kaleidoscope/plugin/DynamicMacros.cpp

@@ -47,9 +47,8 @@ static void playKeyCode(Key key, uint8_t keyStates, bool explicit_report) {
 }
 
 static void readKeyCodeAndPlay(uint16_t pos, uint8_t flags, uint8_t keyStates, bool explicit_report) {
-  Key key;
+  Key key(Kaleidoscope.storage().read(pos++), // key_code
-  key.flags = flags;
+          flags);
-  key.keyCode = Kaleidoscope.storage().read(pos++);
 
   playKeyCode(key, keyStates, explicit_report);
 }
@@ -200,11 +199,11 @@ void DynamicMacros::play(uint8_t macro_id) {
 }
 
 EventHandlerResult DynamicMacros::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr, uint8_t keyState) {
-  if (mappedKey.raw < DYNAMIC_MACRO_FIRST || mappedKey.raw > DYNAMIC_MACRO_LAST)
+  if (mappedKey.getRaw() < DYNAMIC_MACRO_FIRST || mappedKey.getRaw() > DYNAMIC_MACRO_LAST)
     return EventHandlerResult::OK;
 
   if (keyToggledOn(keyState)) {
-    play(mappedKey.raw - DYNAMIC_MACRO_FIRST);
+    play(mappedKey.getRaw() - DYNAMIC_MACRO_FIRST);
   }
 
   return EventHandlerResult::EVENT_CONSUMED;

src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp

@@ -87,12 +87,12 @@ EventHandlerResult EEPROMKeymapProgrammer::onKeyswitchEvent(Key &mapped_key, Key
   }
 
   uint8_t n;
-  if (mapped_key.keyCode == Key_0.keyCode)
+  if (mapped_key.getKeyCode() == Key_0.getKeyCode())
     n = 0;
   else
-    n = mapped_key.keyCode - Key_1.keyCode + 1;
+    n = mapped_key.getKeyCode() - Key_1.getKeyCode() + 1;
 
-  new_key_.raw = new_key_.raw * 10 + n;
+  new_key_.setRaw(new_key_.getRaw() * 10 + n);
 
   return EventHandlerResult::EVENT_CONSUMED;
 }

src/kaleidoscope/plugin/EEPROM-Keymap.cpp

@@ -48,17 +48,13 @@ void EEPROMKeymap::max_layers(uint8_t max) {
 }
 
 Key EEPROMKeymap::getKey(uint8_t layer, KeyAddr key_addr) {
-  Key key;
-
   if (layer >= max_layers_)
     return Key_NoKey;
 
   uint16_t pos = ((layer * Kaleidoscope.device().numKeys()) + key_addr.toInt()) * 2;
 
-  key.flags = Kaleidoscope.storage().read(keymap_base_ + pos);
+  return Key(Kaleidoscope.storage().read(keymap_base_ + pos + 1), // key_code
-  key.keyCode = Kaleidoscope.storage().read(keymap_base_ + pos + 1);
+             Kaleidoscope.storage().read(keymap_base_ + pos));    // flags
-
-  return key;
 }
 
 Key EEPROMKeymap::getKeyExtended(uint8_t layer, KeyAddr key_addr) {
@@ -77,8 +73,8 @@ uint16_t EEPROMKeymap::keymap_base(void) {
 }
 
 void EEPROMKeymap::updateKey(uint16_t base_pos, Key key) {
-  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2, key.flags);
+  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2, key.getFlags());
-  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2 + 1, key.keyCode);
+  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2 + 1, key.getKeyCode());
 }
 
 void EEPROMKeymap::dumpKeymap(uint8_t layers, Key(*getkey)(uint8_t, KeyAddr)) {

src/kaleidoscope/plugin/Escape-OneShot.cpp

@@ -23,7 +23,7 @@ namespace kaleidoscope {
 namespace plugin {
 
 EventHandlerResult EscapeOneShot::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, uint8_t keyState) {
-  if (mapped_key.raw != Key_Escape.raw ||
+  if (mapped_key != Key_Escape ||
       (keyState & INJECTED) ||
       !keyToggledOn(keyState))
     return EventHandlerResult::OK;

src/kaleidoscope/plugin/FocusSerial.h

@@ -33,7 +33,7 @@ class FocusSerial : public kaleidoscope::Plugin {
     send(color.r, color.g, color.b);
   }
   void send(const Key key) {
-    send(key.raw);
+    send(key.getRaw());
   }
   void send(const bool b) {
     printBool(b);
@@ -62,7 +62,7 @@ class FocusSerial : public kaleidoscope::Plugin {
   }
 
   void read(Key &key) {
-    key.raw = Kaleidoscope.serialPort().parseInt();
+    key.setRaw(Kaleidoscope.serialPort().parseInt());
   }
   void read(cRGB &color) {
     color.r = Kaleidoscope.serialPort().parseInt();

src/kaleidoscope/plugin/GeminiPR.cpp

@@ -30,7 +30,7 @@ EventHandlerResult GeminiPR::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
     return EventHandlerResult::OK;
 
   if (keyToggledOn(keyState)) {
-    uint8_t key = mapped_key.raw - geminipr::START;
+    uint8_t key = mapped_key.getRaw() - geminipr::START;
     ++keys_held_;
 
     state_[key / 7] |= 1 << (6 - (key % 7));

src/kaleidoscope/plugin/LED-ActiveModColor.cpp

@@ -43,8 +43,8 @@ EventHandlerResult ActiveModColorEffect::onLayerChange() {
 
     if (::OneShot.isOneShotKey(k) ||
         (highlight_normal_modifiers_ && (
-           (k.raw >= Key_LeftControl.raw && k.raw <= Key_RightGui.raw) ||
+           (k >= Key_LeftControl && k <= Key_RightGui) ||
-           (k.flags == (SYNTHETIC | SWITCH_TO_KEYMAP))))) {
+           (k.getFlags() == (SYNTHETIC | SWITCH_TO_KEYMAP))))) {
       mod_keys_[mod_key_count_++] = key_addr;
     }
   }
@@ -69,13 +69,13 @@ EventHandlerResult ActiveModColorEffect::beforeReportingState() {
         ::LEDControl.setCrgbAt(key_addr, highlight_color);
       else
         ::LEDControl.refreshAt(key_addr);
-    } else if (k.raw >= Key_LeftControl.raw && k.raw <= Key_RightGui.raw) {
+    } else if (k >= Key_LeftControl && k <= Key_RightGui) {
       if (hid::isModifierKeyActive(k))
         ::LEDControl.setCrgbAt(key_addr, highlight_color);
       else
         ::LEDControl.refreshAt(key_addr);
-    } else if (k.flags == (SYNTHETIC | SWITCH_TO_KEYMAP)) {
+    } else if (k.getFlags() == (SYNTHETIC | SWITCH_TO_KEYMAP)) {
-      uint8_t layer = k.keyCode;
+      uint8_t layer = k.getKeyCode();
       if (layer >= LAYER_SHIFT_OFFSET)
         layer -= LAYER_SHIFT_OFFSET;
 

src/kaleidoscope/plugin/LED-AlphaSquare.cpp

@@ -70,7 +70,7 @@ void AlphaSquare::display(Key key, KeyAddr key_addr, cRGB key_color) {
   if (key < Key_A || key > Key_0)
     return;
 
-  uint8_t index = key.keyCode - Key_A.keyCode;
+  uint8_t index = key.getKeyCode() - Key_A.getKeyCode();
   uint16_t symbol = pgm_read_word(&alphabet[index]);
 
   display(symbol, key_addr, key_color);
@@ -112,7 +112,7 @@ bool AlphaSquare::isSymbolPart(Key key,
   if (key < Key_A || key > Key_0)
     return false;
 
-  uint8_t index = key.keyCode - Key_A.keyCode;
+  uint8_t index = key.getKeyCode() - Key_A.getKeyCode();
   uint16_t symbol = pgm_read_word(&alphabet[index]);
 
   return isSymbolPart(symbol, displayLedAddr, key_addr);

src/kaleidoscope/plugin/LEDControl.cpp

@@ -136,7 +136,7 @@ kaleidoscope::EventHandlerResult LEDControl::onSetup() {
 }
 
 kaleidoscope::EventHandlerResult LEDControl::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr, uint8_t keyState) {
-  if (mappedKey.flags != (SYNTHETIC | IS_INTERNAL | LED_TOGGLE))
+  if (mappedKey.getFlags() != (SYNTHETIC | IS_INTERNAL | LED_TOGGLE))
     return kaleidoscope::EventHandlerResult::OK;
 
   if (keyToggledOn(keyState)) {

src/kaleidoscope/plugin/LEDEffect-BootAnimation.cpp

@@ -26,17 +26,17 @@ uint16_t BootAnimationEffect::start_time_ = 0;
 uint16_t BootAnimationEffect::timeout = 1000;
 uint8_t BootAnimationEffect::current_index_ = 0;
 const uint8_t BootAnimationEffect::greeting_[11] PROGMEM = {
-  Key_K.keyCode,
+  Key_K.getKeyCode(),
-  Key_E.keyCode,
+  Key_E.getKeyCode(),
-  Key_Y.keyCode,
+  Key_Y.getKeyCode(),
-  Key_B.keyCode,
+  Key_B.getKeyCode(),
-  Key_O.keyCode,
+  Key_O.getKeyCode(),
-  Key_A.keyCode,
+  Key_A.getKeyCode(),
-  Key_R.keyCode,
+  Key_R.getKeyCode(),
-  Key_D.keyCode,
+  Key_D.getKeyCode(),
-  Key_Period.keyCode,
+  Key_Period.getKeyCode(),
-  Key_I.keyCode,
+  Key_I.getKeyCode(),
-  Key_O.keyCode
+  Key_O.getKeyCode()
 };
 
 EventHandlerResult BootAnimationEffect::onSetup() {
@@ -56,11 +56,10 @@ EventHandlerResult BootAnimationEffect::afterEachCycle() {
 
   for (auto key_addr : KeyAddr::all()) {
     Key k = Layer.lookupOnActiveLayer(key_addr);
-    Key g;
+    Key g(pgm_read_byte(&greeting_[current_index_]), // key_code
-    g.flags = 0;
+          0);                                        // flags
-    g.keyCode = pgm_read_byte(&greeting_[current_index_]);
 
-    if (k.raw == g.raw) {
+    if (k == g) {
       key_addr_found = key_addr;
       break;
     }

src/kaleidoscope/plugin/LEDEffect-BootGreeting.cpp

@@ -43,7 +43,7 @@ void BootGreetingEffect::findLed(void) {
   for (auto key_addr : KeyAddr::all()) {
     Key k = Layer.lookupOnActiveLayer(key_addr);
 
-    if (k.raw == search_key.raw) {
+    if (k == search_key) {
       key_addr_ = key_addr;
       return;
     }

src/kaleidoscope/plugin/Leader.cpp

@@ -32,8 +32,8 @@ const Leader::dictionary_t *Leader::dictionary;
 #define PARTIAL_MATCH -1
 #define NO_MATCH -2
 
-#define isLeader(k) (k.raw >= ranges::LEAD_FIRST && k.raw <= ranges::LEAD_LAST)
+#define isLeader(k) (k.getRaw() >= ranges::LEAD_FIRST && k.getRaw() <= ranges::LEAD_LAST)
-#define isActive() (sequence_[0].raw != Key_NoKey.raw)
+#define isActive() (sequence_[0] != Key_NoKey)
 
 // --- actions ---
 int8_t Leader::lookup(void) {
@@ -42,14 +42,14 @@ int8_t Leader::lookup(void) {
   for (uint8_t seq_index = 0; ; seq_index++) {
     match = true;
 
-    if (pgm_read_word(&(dictionary[seq_index].sequence[0].raw)) == Key_NoKey.raw)
+    if (dictionary[seq_index].sequence[0].readFromProgmem() == Key_NoKey)
       break;
 
     Key seq_key;
     for (uint8_t i = 0; i <= sequence_pos_; i++) {
-      seq_key.raw = pgm_read_word(&(dictionary[seq_index].sequence[i].raw));
+      seq_key = dictionary[seq_index].sequence[i].readFromProgmem();
 
-      if (sequence_[i].raw != seq_key.raw) {
+      if (sequence_[i] != seq_key) {
         match = false;
         break;
       }
@@ -58,8 +58,9 @@ int8_t Leader::lookup(void) {
     if (!match)
       continue;
 
-    seq_key.raw = pgm_read_word(&(dictionary[seq_index].sequence[sequence_pos_ + 1].raw));
+    seq_key
-    if (seq_key.raw == Key_NoKey.raw) {
+      = dictionary[seq_index].sequence[sequence_pos_ + 1].readFromProgmem();
+    if (seq_key == Key_NoKey) {
       return seq_index;
     } else {
       return PARTIAL_MATCH;
@@ -73,7 +74,7 @@ int8_t Leader::lookup(void) {
 
 void Leader::reset(void) {
   sequence_pos_ = 0;
-  sequence_[0].raw = Key_NoKey.raw;
+  sequence_[0] = Key_NoKey;
 }
 
 void Leader::inject(Key key, uint8_t key_state) {
@@ -95,7 +96,7 @@ EventHandlerResult Leader::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, u
       // not active, but a leader key = start the sequence on key release!
       start_time_ = Kaleidoscope.millisAtCycleStart();
       sequence_pos_ = 0;
-      sequence_[sequence_pos_].raw = mapped_key.raw;
+      sequence_[sequence_pos_] = mapped_key;
     }
 
     // If the sequence was not active yet, ignore the key.
@@ -113,7 +114,7 @@ EventHandlerResult Leader::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, u
     }
 
     start_time_ = Kaleidoscope.millisAtCycleStart();
-    sequence_[sequence_pos_].raw = mapped_key.raw;
+    sequence_[sequence_pos_] = mapped_key;
     action_index = lookup();
 
     if (action_index >= 0) {

src/kaleidoscope/plugin/Macros.cpp

@@ -49,9 +49,8 @@ static void playKeyCode(Key key, uint8_t keyStates, bool explicit_report) {
 }
 
 static void readKeyCodeAndPlay(const macro_t *macro_p, uint8_t flags, uint8_t keyStates, bool explicit_report) {
-  Key key;
+  Key key(pgm_read_byte(macro_p++), // key_code
-  key.flags = flags;
+          flags);
-  key.keyCode = pgm_read_byte(macro_p++);
 
   playKeyCode(key, keyStates, explicit_report);
 }
@@ -186,38 +185,38 @@ Key Macros_::lookupAsciiCode(uint8_t ascii_code) {
 
   switch (ascii_code) {
   case 0x08 ... 0x09:
-    key.keyCode = Key_Backspace.keyCode + ascii_code - 0x08;
+    key.setKeyCode(Key_Backspace.getKeyCode() + ascii_code - 0x08);
     break;
   case 0x0A:
-    key.keyCode = Key_Enter.keyCode;
+    key.setKeyCode(Key_Enter.getKeyCode());
     break;
   case 0x1B:
-    key.keyCode = Key_Escape.keyCode;
+    key.setKeyCode(Key_Escape.getKeyCode());
     break;
   case 0x20:
-    key.keyCode = Key_Spacebar.keyCode;
+    key.setKeyCode(Key_Spacebar.getKeyCode());
     break;
   case 0x21 ... 0x30:
-    key.raw = pgm_read_word(&ascii_to_key_map[ascii_code - 0x21].raw);
+    key = ascii_to_key_map[ascii_code - 0x21].readFromProgmem();
     break;
   case 0x31 ... 0x39:
-    key.keyCode = Key_1.keyCode + ascii_code - 0x31;
+    key.setKeyCode(Key_1.getKeyCode() + ascii_code - 0x31);
     break;
   case 0x3A ... 0x40:
-    key.raw = pgm_read_word(&ascii_to_key_map[ascii_code - 0x3A + 16].raw);
+    key = ascii_to_key_map[ascii_code - 0x3A + 16].readFromProgmem();
     break;
   case 0x41 ... 0x5A:
-    key.flags = SHIFT_HELD;
+    key.setFlags(SHIFT_HELD);
-    key.keyCode = Key_A.keyCode + ascii_code - 0x41;
+    key.setKeyCode(Key_A.getKeyCode() + ascii_code - 0x41);
     break;
   case 0x5B ... 0x60:
-    key.raw = pgm_read_word(&ascii_to_key_map[ascii_code - 0x5B + 23].raw);
+    key = ascii_to_key_map[ascii_code - 0x5B + 23].readFromProgmem();
     break;
   case 0x61 ... 0x7A:
-    key.keyCode = Key_A.keyCode + ascii_code - 0x61;
+    key.setKeyCode(Key_A.getKeyCode() + ascii_code - 0x61);
     break;
   case 0x7B ... 0x7E:
-    key.raw = pgm_read_word(&ascii_to_key_map[ascii_code - 0x7B + 29].raw);
+    key = ascii_to_key_map[ascii_code - 0x7B + 29].readFromProgmem();
     break;
   }
   return key;
@@ -232,7 +231,7 @@ const macro_t *Macros_::type(const char *string) {
     Key key = lookupAsciiCode(ascii_code);
 
 
-    if (key.raw == Key_NoKey.raw)
+    if (key == Key_NoKey)
       continue;
 
     playMacroKeyswitchEvent(key, IS_PRESSED, false);
@@ -244,10 +243,10 @@ const macro_t *Macros_::type(const char *string) {
 }
 
 EventHandlerResult Macros_::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr, uint8_t keyState) {
-  if (mappedKey.flags != (SYNTHETIC | IS_MACRO))
+  if (mappedKey.getFlags() != (SYNTHETIC | IS_MACRO))
     return EventHandlerResult::OK;
 
-  addActiveMacroKey(mappedKey.keyCode, key_addr.toInt(), keyState);
+  addActiveMacroKey(mappedKey.getKeyCode(), key_addr.toInt(), keyState);
 
   return EventHandlerResult::EVENT_CONSUMED;
 }

src/kaleidoscope/plugin/Macros/MacroSteps.h

@@ -47,8 +47,8 @@ typedef uint8_t macro_t;
 #define I(n)  MACRO_ACTION_STEP_INTERVAL, n
 #define W(n)  MACRO_ACTION_STEP_WAIT, n
 
-#define Kr(k) (k).flags, (k).keyCode
+#define Kr(k) (k).getFlags(), (k).getKeyCode()
-#define Kc(k) (Key_ ## k).keyCode
+#define Kc(k) (Key_ ## k).getKeyCode()
 #define K(k) Kr(Key_ ## k)
 
 #define Dr(k) MACRO_ACTION_STEP_KEYDOWN, Kr(k)

src/kaleidoscope/plugin/MouseKeys.cpp

@@ -105,11 +105,11 @@ EventHandlerResult MouseKeys_::beforeReportingState() {
 }
 
 EventHandlerResult MouseKeys_::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr, uint8_t keyState) {
-  if (mappedKey.flags != (SYNTHETIC | IS_MOUSE_KEY))
+  if (mappedKey.getFlags() != (SYNTHETIC | IS_MOUSE_KEY))
     return EventHandlerResult::OK;
 
-  if (mappedKey.keyCode & KEY_MOUSE_BUTTON && !(mappedKey.keyCode & KEY_MOUSE_WARP)) {
+  if (mappedKey.getKeyCode() & KEY_MOUSE_BUTTON && !(mappedKey.getKeyCode() & KEY_MOUSE_WARP)) {
-    uint8_t button = mappedKey.keyCode & ~KEY_MOUSE_BUTTON;
+    uint8_t button = mappedKey.getKeyCode() & ~KEY_MOUSE_BUTTON;
 
     if (keyIsPressed(keyState)) {
       // Reset warp state on initial mouse button key-down only so we can use
@@ -122,17 +122,17 @@ EventHandlerResult MouseKeys_::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr
     } else if (keyToggledOff(keyState)) {
       MouseWrapper.release_button(button);
     }
-  } else if (!(mappedKey.keyCode & KEY_MOUSE_WARP)) {
+  } else if (!(mappedKey.getKeyCode() & KEY_MOUSE_WARP)) {
     if (keyToggledOn(keyState)) {
       move_start_time_ = Kaleidoscope.millisAtCycleStart();
       accel_start_time_ = Kaleidoscope.millisAtCycleStart();
       wheel_start_time_ = Kaleidoscope.millisAtCycleStart() - wheelDelay;
     }
     if (keyIsPressed(keyState)) {
-      if (mappedKey.keyCode & KEY_MOUSE_WHEEL) {
+      if (mappedKey.getKeyCode() & KEY_MOUSE_WHEEL) {
-        scrollWheel(mappedKey.keyCode);
+        scrollWheel(mappedKey.getKeyCode());
       } else {
-        mouseMoveIntent |= mappedKey.keyCode;
+        mouseMoveIntent |= mappedKey.getKeyCode();
       }
     } else if (keyToggledOff(keyState)) {
       /* If a mouse key toggles off, we want to explicitly stop moving (or
@@ -142,19 +142,19 @@ EventHandlerResult MouseKeys_::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr
        * clear the whole report either, because we want any other mouse keys
        * to still have their desired effect. Therefore, we selectively stop
        * movement or scrolling. */
-      mouseMoveIntent &= ~mappedKey.keyCode;
+      mouseMoveIntent &= ~mappedKey.getKeyCode();
       bool x = false, y = false, vWheel = false, hWheel = false;
 
-      if (mappedKey.keyCode & KEY_MOUSE_UP ||
+      if (mappedKey.getKeyCode() & KEY_MOUSE_UP ||
-          mappedKey.keyCode & KEY_MOUSE_DOWN) {
+          mappedKey.getKeyCode() & KEY_MOUSE_DOWN) {
-        if (mappedKey.keyCode & KEY_MOUSE_WHEEL) {
+        if (mappedKey.getKeyCode() & KEY_MOUSE_WHEEL) {
           vWheel = true;
         } else {
           y = true;
         }
-      } else if (mappedKey.keyCode & KEY_MOUSE_LEFT ||
+      } else if (mappedKey.getKeyCode() & KEY_MOUSE_LEFT ||
-                 mappedKey.keyCode & KEY_MOUSE_RIGHT) {
+                 mappedKey.getKeyCode() & KEY_MOUSE_RIGHT) {
-        if (mappedKey.keyCode & KEY_MOUSE_WHEEL) {
+        if (mappedKey.getKeyCode() & KEY_MOUSE_WHEEL) {
           hWheel = true;
         } else {
           x = true;
@@ -164,12 +164,12 @@ EventHandlerResult MouseKeys_::onKeyswitchEvent(Key &mappedKey, KeyAddr key_addr
       kaleidoscope::hid::stopMouse(x, y, vWheel, hWheel);
     }
   } else if (keyToggledOn(keyState)) {
-    if (mappedKey.keyCode & KEY_MOUSE_WARP && mappedKey.flags & IS_MOUSE_KEY) {
+    if (mappedKey.getKeyCode() & KEY_MOUSE_WARP && mappedKey.getFlags() & IS_MOUSE_KEY) {
-      MouseWrapper.warp(((mappedKey.keyCode & KEY_MOUSE_WARP_END) ? WARP_END : 0x00) |
+      MouseWrapper.warp(((mappedKey.getKeyCode() & KEY_MOUSE_WARP_END) ? WARP_END : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_UP) ? WARP_UP : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_UP) ? WARP_UP : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_DOWN) ? WARP_DOWN : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_DOWN) ? WARP_DOWN : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_LEFT) ? WARP_LEFT : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_LEFT) ? WARP_LEFT : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_RIGHT) ? WARP_RIGHT : 0x00));
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_RIGHT) ? WARP_RIGHT : 0x00));
     }
   }
 

src/kaleidoscope/plugin/NumPad.cpp

@@ -43,7 +43,7 @@ void NumPad::setKeyboardLEDColors(void) {
       numpadLayerToggleKeyAddr = key_addr;
     }
 
-    if ((k != layer_key) || (k == Key_NoKey) || (k.flags != KEY_FLAGS)) {
+    if ((k != layer_key) || (k == Key_NoKey) || (k.getFlags() != KEY_FLAGS)) {
       ::LEDControl.refreshAt(KeyAddr(key_addr));
     } else {
       ::LEDControl.setCrgbAt(KeyAddr(key_addr), color);

src/kaleidoscope/plugin/OneShot.cpp

@@ -48,7 +48,7 @@ bool OneShot::isSticky() {
 }
 
 bool OneShot::isStickable(Key key) {
-  return state_[key.raw - ranges::OS_FIRST].stickable;
+  return state_[key.getRaw() - ranges::OS_FIRST].stickable;
 }
 
 // ---- OneShot stuff ----
@@ -56,11 +56,11 @@ void OneShot::injectNormalKey(uint8_t idx, uint8_t key_state) {
   Key key;
 
   if (idx < 8) {
-    key.flags = Key_LeftControl.flags;
+    key = Key(Key_LeftControl.getKeyCode() + idx,
-    key.keyCode = Key_LeftControl.keyCode + idx;
+              Key_LeftControl.getFlags());
   } else {
-    key.flags = KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP;
+    key = Key(LAYER_SHIFT_OFFSET + idx - 8,
-    key.keyCode = LAYER_SHIFT_OFFSET + idx - 8;
+              KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP);
   }
 
   handleKeyswitchEvent(key, UnknownKeyswitchLocation, key_state | INJECTED);
@@ -76,7 +76,7 @@ void OneShot::cancelOneShot(uint8_t idx) {
 }
 
 EventHandlerResult OneShot::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, uint8_t keyState) {
-  uint8_t idx = mapped_key.raw - ranges::OS_FIRST;
+  uint8_t idx = mapped_key.getRaw() - ranges::OS_FIRST;
 
   if (keyState & INJECTED)
     return EventHandlerResult::OK;
@@ -146,8 +146,8 @@ EventHandlerResult OneShot::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
 
   if (keyIsPressed(keyState)) {
     prev_key_ = mapped_key;
-    if (!(mapped_key.raw >= Key_LeftControl.raw && mapped_key.raw <= Key_RightGui.raw) &&
+    if (!(mapped_key >= Key_LeftControl && mapped_key <= Key_RightGui) &&
-        !(mapped_key.flags == (KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP))) {
+        !(mapped_key.getFlags() == (KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP))) {
       should_cancel_ = true;
     }
   }
@@ -219,7 +219,7 @@ bool OneShot::isActive(void) {
 }
 
 bool OneShot::isActive(Key key) {
-  uint8_t idx = key.raw - ranges::OS_FIRST;
+  uint8_t idx = key.getRaw() - ranges::OS_FIRST;
 
   return (state_[idx].active && !hasTimedOut()) ||
          state_[idx].pressed ||
@@ -227,16 +227,16 @@ bool OneShot::isActive(Key key) {
 }
 
 bool OneShot::isSticky(Key key) {
-  uint8_t idx = key.raw - ranges::OS_FIRST;
+  uint8_t idx = key.getRaw() - ranges::OS_FIRST;
 
   return state_[idx].sticky;
 }
 
 bool OneShot::isModifierActive(Key key) {
-  if (key.raw < Key_LeftControl.raw || key.raw > Key_RightGui.raw)
+  if (key < Key_LeftControl || key > Key_RightGui)
     return false;
 
-  uint8_t idx = key.keyCode - Key_LeftControl.keyCode;
+  uint8_t idx = key.getKeyCode() - Key_LeftControl.getKeyCode();
   return state_[idx].active;
 }
 
@@ -247,12 +247,12 @@ void OneShot::cancel(bool with_stickies) {
 
 void OneShot::enableStickability(Key key) {
   if (key >= ranges::OS_FIRST && key <= ranges::OS_LAST)
-    state_[key.raw - ranges::OS_FIRST].stickable = true;
+    state_[key.getRaw() - ranges::OS_FIRST].stickable = true;
 }
 
 void OneShot::disableStickability(Key key) {
   if (key >= ranges::OS_FIRST && key <= ranges::OS_LAST)
-    state_[key.raw - ranges::OS_FIRST].stickable = false;
+    state_[key.getRaw() - ranges::OS_FIRST].stickable = false;
 }
 
 void OneShot::enableStickabilityForModifiers() {

src/kaleidoscope/plugin/OneShot.h

@@ -20,7 +20,7 @@
 #include <Kaleidoscope.h>
 #include <Kaleidoscope-Ranges.h>
 
-#define OSM(kc) Key(kaleidoscope::ranges::OSM_FIRST + (Key_ ## kc).keyCode - Key_LeftControl.keyCode)
+#define OSM(kc) Key(kaleidoscope::ranges::OSM_FIRST + (Key_ ## kc).getKeyCode() - Key_LeftControl.getKeyCode())
 #define OSL(n) Key(kaleidoscope::ranges::OSL_FIRST + n)
 
 namespace kaleidoscope {
@@ -35,7 +35,7 @@ class OneShot : public kaleidoscope::Plugin {
   }
 
   static bool isOneShotKey(Key key) {
-    return (key.raw >= kaleidoscope::ranges::OS_FIRST && key.raw <= kaleidoscope::ranges::OS_LAST);
+    return (key.getRaw() >= kaleidoscope::ranges::OS_FIRST && key.getRaw() <= kaleidoscope::ranges::OS_LAST);
   }
   static bool isActive(void);
   static bool isActive(Key key);
@@ -100,7 +100,7 @@ class OneShot : public kaleidoscope::Plugin {
   static void cancelOneShot(uint8_t idx);
 
   static bool isOneShotKey_(Key key) {
-    return key.raw >= ranges::OS_FIRST && key.raw <= ranges::OS_LAST;
+    return key.getRaw() >= ranges::OS_FIRST && key.getRaw() <= ranges::OS_LAST;
   }
   static bool hasTimedOut() {
     return Kaleidoscope.hasTimeExpired(start_time_, time_out);

src/kaleidoscope/plugin/Qukeys.cpp

@@ -318,22 +318,22 @@ bool Qukeys::isQukey(KeyAddr k) {
 bool Qukeys::isDualUseKey(Key key) {
   // Test for DualUse modifiers:
   if (key >= ranges::DUM_FIRST && key <= ranges::DUM_LAST) {
-    key.raw -= ranges::DUM_FIRST;
+    key.setRaw(key.getRaw() - ranges::DUM_FIRST);
 
     queue_head_.primary_key = key;
-    queue_head_.primary_key.flags = 0;
+    queue_head_.primary_key.setFlags(0);
 
-    queue_head_.alternate_key.raw = key.flags + Key_LeftControl.keyCode;
+    queue_head_.alternate_key.setRaw(key.getFlags() + Key_LeftControl.getKeyCode());
     return true;
   }
   // Test for DualUse layer shifts:
   if (key >= ranges::DUL_FIRST && key <= ranges::DUL_LAST) {
-    key.raw -= ranges::DUL_FIRST;
+    key.setRaw(key.getRaw() - ranges::DUL_FIRST);
 
     queue_head_.primary_key = key;
-    queue_head_.primary_key.flags = 0;
+    queue_head_.primary_key.setFlags(0);
 
-    int8_t layer = key.flags;
+    int8_t layer = key.getFlags();
     queue_head_.alternate_key = ShiftToLayer(layer);
     return true;
   }
@@ -384,13 +384,13 @@ bool Qukeys::isKeyAddrInQueueBeforeIndex(KeyAddr k, uint8_t index) const {
 bool isModifierKey(Key key) {
   // If it's a plain keyboard key, return true if its base keycode is a
   // modifier, otherwise return false:
-  if ((key.flags & (SYNTHETIC | RESERVED)) == 0) {
+  if ((key.getFlags() & (SYNTHETIC | RESERVED)) == 0) {
-    return (key.keyCode >= HID_KEYBOARD_FIRST_MODIFIER &&
+    return (key.getKeyCode() >= HID_KEYBOARD_FIRST_MODIFIER &&
-            key.keyCode <= HID_KEYBOARD_LAST_MODIFIER);
+            key.getKeyCode() <= HID_KEYBOARD_LAST_MODIFIER);
   }
   // If it's a layer shift key, return true:
-  if (key.flags == (SYNTHETIC | SWITCH_TO_KEYMAP) &&
+  if (key.getFlags() == (SYNTHETIC | SWITCH_TO_KEYMAP) &&
-      key.keyCode >= LAYER_SHIFT_OFFSET) {
+      key.getKeyCode() >= LAYER_SHIFT_OFFSET) {
     return true;
   }
   // In all other cases, return false:

src/kaleidoscope/plugin/Qukeys.h

@@ -25,15 +25,15 @@
 // DualUse Key definitions for Qukeys in the keymap
 #define MT(mod, key) Key(                                               \
     kaleidoscope::ranges::DUM_FIRST +                                   \
-    (((Key_ ## mod).keyCode - Key_LeftControl.keyCode) << 8) +          \
+    (((Key_ ## mod).getKeyCode() - Key_LeftControl.getKeyCode()) << 8) +          \
-    (Key_ ## key).keyCode                                               \
+    (Key_ ## key).getKeyCode()                                               \
 )
 #define SFT_T(key) MT(LeftShift, key)
 #define CTL_T(key) MT(LeftControl, key)
 #define ALT_T(key) MT(LeftAlt, key)
 #define GUI_T(key) MT(LeftGui, key)
 
-#define LT(layer, key) Key(kaleidoscope::ranges::DUL_FIRST + (layer << 8) + (Key_ ## key).keyCode)
+#define LT(layer, key) Key(kaleidoscope::ranges::DUL_FIRST + (layer << 8) + (Key_ ## key).getKeyCode())
 
 #define _DEPRECATED_MESSAGE_QUKEY_ROW_COL_CONSTRUCTOR                        \
   "The `Qukey(layer, row, col, alternate_key)` constructor using separate\n" \

src/kaleidoscope/plugin/ShapeShifter.cpp

@@ -43,17 +43,17 @@ EventHandlerResult ShapeShifter::onKeyswitchEvent(Key &mapped_key, KeyAddr key_a
   // Try to find the current key in the dictionary
   uint8_t i = 0;
   do {
-    orig.raw = pgm_read_word(&(dictionary[i].original.raw));
+    orig = dictionary[i].original.readFromProgmem();
     i++;
-  } while (orig.raw != Key_NoKey.raw &&
+  } while (orig != Key_NoKey &&
-           orig.raw != mapped_key.raw);
+           orig != mapped_key);
   i--;
 
   // If not found, bail out.
-  if (orig.raw == Key_NoKey.raw)
+  if (orig == Key_NoKey)
     return EventHandlerResult::OK;
 
-  repl.raw = pgm_read_word(&(dictionary[i].replacement.raw));
+  repl = dictionary[i].replacement.readFromProgmem();
 
   // If found, handle the alternate key instead
   mapped_key = repl;

src/kaleidoscope/plugin/SpaceCadet.cpp

@@ -72,8 +72,8 @@ bool SpaceCadet::active() {
 
 EventHandlerResult SpaceCadet::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, uint8_t key_state) {
   //Handle our synthetic keys for enabling and disabling functionality
-  if (mapped_key.raw >= kaleidoscope::ranges::SC_FIRST &&
+  if (mapped_key.getRaw() >= kaleidoscope::ranges::SC_FIRST &&
-      mapped_key.raw <= kaleidoscope::ranges::SC_LAST) {
+      mapped_key.getRaw() <= kaleidoscope::ranges::SC_LAST) {
     //Only fire the activate / deactivate on the initial press (not held or release)
     if (keyToggledOn(key_state)) {
       if (mapped_key == Key_SpaceCadetEnable) {
@@ -109,14 +109,14 @@ EventHandlerResult SpaceCadet::onKeyswitchEvent(Key &mapped_key, KeyAddr key_add
     for (
       uint8_t i = 0 ;
       !(
-        map[i].input.raw == Key_NoKey.raw
+        map[i].input == Key_NoKey
-        && map[i].output.raw == Key_NoKey.raw
+        && map[i].output == Key_NoKey
         && map[i].timeout == 0
       ) ;
       ++i
     ) {
 
-      if (mapped_key.raw == map[i].input.raw) {
+      if (mapped_key == map[i].input) {
         //The keypress was valid and a match. Mark it as flagged and reset the counter
         map[i].flagged = true;
         map[i].start_time = Kaleidoscope.millisAtCycleStart();
@@ -166,8 +166,8 @@ EventHandlerResult SpaceCadet::onKeyswitchEvent(Key &mapped_key, KeyAddr key_add
   for (
     uint8_t i = 0 ;
     !(
-      map[i].input.raw == Key_NoKey.raw
+      map[i].input == Key_NoKey
-      && map[i].output.raw == Key_NoKey.raw
+      && map[i].output == Key_NoKey
       && map[i].timeout == 0
     );
     ++i
@@ -180,7 +180,7 @@ EventHandlerResult SpaceCadet::onKeyswitchEvent(Key &mapped_key, KeyAddr key_add
     }
 
     //the key we're looking at was valid (in the map)
-    if (map[i].input.raw == mapped_key.raw) {
+    if (map[i].input == mapped_key) {
       pressed_key_was_valid = true;
     }
   }

src/kaleidoscope/plugin/Syster.cpp

@@ -103,14 +103,14 @@ EventHandlerResult Syster::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr, u
 }
 
 __attribute__((weak)) const char keyToChar(Key key) {
-  if (key.flags != 0)
+  if (key.getFlags() != 0)
     return 0;
 
-  switch (key.keyCode) {
+  switch (key.getKeyCode()) {
-  case Key_A.keyCode ... Key_Z.keyCode:
+  case Key_A.getKeyCode() ... Key_Z.getKeyCode():
-    return 'a' + (key.keyCode - Key_A.keyCode);
+    return 'a' + (key.getKeyCode() - Key_A.getKeyCode());
-  case Key_1.keyCode ... Key_0.keyCode:
+  case Key_1.getKeyCode() ... Key_0.getKeyCode():
-    return '1' + (key.keyCode - Key_1.keyCode);
+    return '1' + (key.getKeyCode() - Key_1.getKeyCode());
   }
 
   return 0;

src/kaleidoscope/plugin/TapDance.cpp

@@ -31,7 +31,7 @@ KeyAddr TapDance::last_tap_dance_addr_;
 // --- actions ---
 
 void TapDance::interrupt(KeyAddr key_addr) {
-  uint8_t idx = last_tap_dance_key_.raw - ranges::TD_FIRST;
+  uint8_t idx = last_tap_dance_key_.getRaw() - ranges::TD_FIRST;
 
   tapDanceAction(idx, last_tap_dance_addr_, state_[idx].count, Interrupt);
   state_[idx].triggered = true;
@@ -49,7 +49,7 @@ void TapDance::interrupt(KeyAddr key_addr) {
 }
 
 void TapDance::timeout(void) {
-  uint8_t idx = last_tap_dance_key_.raw - ranges::TD_FIRST;
+  uint8_t idx = last_tap_dance_key_.getRaw() - ranges::TD_FIRST;
 
   tapDanceAction(idx, last_tap_dance_addr_, state_[idx].count, Timeout);
   state_[idx].triggered = true;
@@ -57,13 +57,13 @@ void TapDance::timeout(void) {
   if (state_[idx].pressed)
     return;
 
-  last_tap_dance_key_.raw = Key_NoKey.raw;
+  last_tap_dance_key_ = Key_NoKey;
 
   release(idx);
 }
 
 void TapDance::release(uint8_t tap_dance_index) {
-  last_tap_dance_key_.raw = Key_NoKey.raw;
+  last_tap_dance_key_ = Key_NoKey;
 
   state_[tap_dance_index].pressed = false;
   state_[tap_dance_index].triggered = false;
@@ -71,7 +71,7 @@ void TapDance::release(uint8_t tap_dance_index) {
 }
 
 void TapDance::tap(void) {
-  uint8_t idx = last_tap_dance_key_.raw - ranges::TD_FIRST;
+  uint8_t idx = last_tap_dance_key_.getRaw() - ranges::TD_FIRST;
 
   state_[idx].count++;
   start_time_ = Kaleidoscope.millisAtCycleStart();
@@ -85,8 +85,7 @@ void TapDance::actionKeys(uint8_t tap_count, ActionType tap_dance_action, uint8_
   if (tap_count > max_keys)
     tap_count = max_keys;
 
-  Key key;
+  Key key = tap_keys[tap_count - 1].readFromProgmem();
-  key.raw = pgm_read_word(&(tap_keys[tap_count - 1].raw));
 
   switch (tap_dance_action) {
   case Tap:
@@ -111,8 +110,8 @@ EventHandlerResult TapDance::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
   if (keyState & INJECTED)
     return EventHandlerResult::OK;
 
-  if (mapped_key.raw < ranges::TD_FIRST || mapped_key.raw > ranges::TD_LAST) {
+  if (mapped_key.getRaw() < ranges::TD_FIRST || mapped_key.getRaw() > ranges::TD_LAST) {
-    if (last_tap_dance_key_.raw == Key_NoKey.raw)
+    if (last_tap_dance_key_ == Key_NoKey)
       return EventHandlerResult::OK;
 
     if (keyToggledOn(keyState))
@@ -125,13 +124,13 @@ EventHandlerResult TapDance::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
     return EventHandlerResult::OK;
   }
 
-  uint8_t tap_dance_index = mapped_key.raw - ranges::TD_FIRST;
+  uint8_t tap_dance_index = mapped_key.getRaw() - ranges::TD_FIRST;
 
   if (keyToggledOff(keyState))
     state_[tap_dance_index].pressed = false;
 
-  if (last_tap_dance_key_.raw != mapped_key.raw) {
+  if (last_tap_dance_key_ != mapped_key) {
-    if (last_tap_dance_key_.raw == Key_NoKey.raw) {
+    if (last_tap_dance_key_ == Key_NoKey) {
       if (state_[tap_dance_index].triggered) {
         if (keyToggledOff(keyState)) {
           release(tap_dance_index);
@@ -140,7 +139,7 @@ EventHandlerResult TapDance::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
         return EventHandlerResult::EVENT_CONSUMED;
       }
 
-      last_tap_dance_key_.raw = mapped_key.raw;
+      last_tap_dance_key_ = mapped_key;
       last_tap_dance_addr_ = key_addr;
 
       tap();
@@ -166,7 +165,7 @@ EventHandlerResult TapDance::onKeyswitchEvent(Key &mapped_key, KeyAddr key_addr,
     return EventHandlerResult::EVENT_CONSUMED;
   }
 
-  last_tap_dance_key_.raw = mapped_key.raw;
+  last_tap_dance_key_ = mapped_key;
   last_tap_dance_addr_ = key_addr;
   state_[tap_dance_index].pressed = true;
 
@@ -191,7 +190,7 @@ EventHandlerResult TapDance::afterEachCycle() {
     state_[i].release_next = false;
   }
 
-  if (last_tap_dance_key_.raw == Key_NoKey.raw)
+  if (last_tap_dance_key_ == Key_NoKey)
     return EventHandlerResult::OK;
 
   if (Kaleidoscope.hasTimeExpired(start_time_, time_out))

src/kaleidoscope/plugin/TopsyTurvy.cpp

@@ -52,11 +52,11 @@ EventHandlerResult TopsyTurvy::onKeyswitchEvent(Key &mapped_key, KeyAddr key_add
     }
   }
 
-  mapped_key.raw = mapped_key.raw - ranges::TT_FIRST;
+  mapped_key.setRaw(mapped_key.getRaw() - ranges::TT_FIRST);
 
   // invert the shift state
   if (!is_shifted_) {
-    mapped_key.flags |= SHIFT_HELD;
+    mapped_key.setFlags(mapped_key.getFlags() | SHIFT_HELD);
     return EventHandlerResult::OK;
   }
 

src/kaleidoscope/plugin/TopsyTurvy.h

@@ -20,7 +20,7 @@
 #include <Kaleidoscope.h>
 #include <Kaleidoscope-Ranges.h>
 
-#define TOPSY(k) Key(kaleidoscope::ranges::TT_FIRST + (Key_ ## k).keyCode)
+#define TOPSY(k) Key(kaleidoscope::ranges::TT_FIRST + (Key_ ## k).getKeyCode())
 
 namespace kaleidoscope {
 namespace plugin {

src/kaleidoscope/plugin/TriColor.cpp

@@ -31,23 +31,23 @@ void TriColor::TransientLEDMode::update(void) {
     Key k = Layer.lookup(key_addr);
 
     // Special keys are always mod_color
-    if (k.flags != 0) {
+    if (k.getFlags() != 0) {
       ::LEDControl.setCrgbAt(KeyAddr(key_addr), parent_->mod_color_);
       continue;
     }
 
     cRGB color = parent_->mod_color_;
 
-    switch (k.keyCode) {
+    switch (k.getKeyCode()) {
-    case Key_A.keyCode ... Key_0.keyCode:
+    case Key_A.getKeyCode() ... Key_0.getKeyCode():
-    case Key_Spacebar.keyCode:
+    case Key_Spacebar.getKeyCode():
-    case Key_KeypadDivide.keyCode ... Key_KeypadSubtract.keyCode:
+    case Key_KeypadDivide.getKeyCode() ... Key_KeypadSubtract.getKeyCode():
-    case Key_Keypad1.keyCode ... Key_KeypadDot.keyCode:
+    case Key_Keypad1.getKeyCode() ... Key_KeypadDot.getKeyCode():
-    case Key_F1.keyCode ... Key_F4.keyCode:
+    case Key_F1.getKeyCode() ... Key_F4.getKeyCode():
-    case Key_F9.keyCode ... Key_F12.keyCode:
+    case Key_F9.getKeyCode() ... Key_F12.getKeyCode():
       color = parent_->base_color_;
       break;
-    case Key_Escape.keyCode:
+    case Key_Escape.getKeyCode():
       color = parent_->esc_color_;
       break;
     }

src/kaleidoscope/plugin/Turbo.h

@@ -19,7 +19,7 @@
 #include <Kaleidoscope.h>
 #include <Kaleidoscope-Ranges.h>
 
-#define Key_Turbo ((Key) { .raw = kaleidoscope::ranges::TURBO })
+#define Key_Turbo Key{kaleidoscope::ranges::TURBO }
 
 namespace kaleidoscope {
 namespace plugin {

src/kaleidoscope/plugin/Unicode.cpp

@@ -142,9 +142,9 @@ __attribute__((weak)) Key hexToKey(uint8_t hex) {
     return Key_0;
   }
   if (hex < 0xA) {
-    m = Key_1.keyCode + (hex - 0x1);
+    m = Key_1.getKeyCode() + (hex - 0x1);
   } else {
-    m = Key_A.keyCode + (hex - 0xA);
+    m = Key_A.getKeyCode() + (hex - 0xA);
   }
   return { m, KEY_FLAGS };
 }
@@ -155,29 +155,29 @@ __attribute__((weak)) Key hexToKeysWithNumpad(uint8_t hex) {
     return Key_Keypad0;
   }
   if (hex < 0xA) {
-    m = Key_Keypad1.keyCode + (hex - 0x1);
+    m = Key_Keypad1.getKeyCode() + (hex - 0x1);
   } else {
     switch (hex) {
     case 0xA:
-      m = Key_A.keyCode;
+      m = Key_A.getKeyCode();
       break;
     case 0xB:
-      m = Key_B.keyCode;
+      m = Key_B.getKeyCode();
       break;
     case 0xC:
-      m = Key_C.keyCode;
+      m = Key_C.getKeyCode();
       break;
     case 0xD:
-      m = Key_D.keyCode;
+      m = Key_D.getKeyCode();
       break;
     case 0xE:
-      m = Key_E.keyCode;
+      m = Key_E.getKeyCode();
       break;
     case 0xF:
-      m = Key_F.keyCode;
+      m = Key_F.getKeyCode();
       break;
     default:
-      m = Key_NoKey.keyCode;
+      m = Key_NoKey.getKeyCode();
       break;
     }
   }

src/kaleidoscope_internal/deprecations.h

@@ -51,5 +51,23 @@
   "`Kaleidoscope.device().led_count` instead."
 
 #define _DEPRECATED_MESSAGE_HARDWARE_BASE_CLASS                 \
-  "The `Hardware` base class is deprecated. Please use\n" __NL_ \
+  "The `Hardware` base class is deprecated. Please use\n" __NL__ \
   "the new APIs based on `kaleidoscope::device::Base`."
+
+#define _DEPRECATED_MESSAGE_DIRECT_KEY_MEMBER_ACCESS                           \
+  "Direct access to `Key` class' data members is deprecated.\n"                \
+  "Please use `Key::setKeyCode()`/`Key::getKeyCode()` or\n"                    \
+  "`Key::setFlags()`/`Key::getFlags()` instead.\n"                             \
+  "\n"                                                                         \
+  "For further information and examples on how to do that, \n"                 \
+  "please see UPGRADING.md."
+
+#define _DEPRECATED_MESSAGE_KEY_MEMBER_RAW_ACCESS                              \
+  "The member variable `raw` of class Key had to be removed. Please \n"        \
+  "use `Key::setRaw()`/`Key::getRaw()` to set and get raw data.\n"             \
+  "\n"                                                                         \
+  "Important: This is not a deprecation. Your code will compile but fail\n"    \
+  "           to link until all access to `Key::raw` has been replaced.\n"     \
+  "\n"                                                                         \
+  "For further information and examples on how to do that, \n"                 \
+  "please see UPGRADING.md."