From ba79eef4b232144979c7c4a0cba450359898acb1 Mon Sep 17 00:00:00 2001
From: Florian Fleissner <florian.fleissner@inpartik.de>
Date: Mon, 11 Nov 2019 17:26:40 +0100
Subject: [PATCH] Key union converted to a proper class

Unions are a C-reminiscense that are better avoided in modern C++.
They cause specific problems due to their nature of representing
independent types. The way they are used in Kaleidoscope, they
can easily be replaced by a class.

This enables it to properly work with Key objects in constexpr context
where with the old union-based implementation the compiler reported
errors when one Key was constructed based on a key_code/flags pair and
another one through raw-data. In such a case, the compiler assumes that
both Key instances represent something entirely different. This is
because unions were never meant for type conversions and the C++
standard considers their use for that purpose as undefined behavior.

The new class provides accessor methods for raw-data access and for
key_code/flags-data access.

This is a breaking change as it is is not possible to replace direct
member access patterns like

key.raw = 0xFFFF;

based on the raw-accessors.

For the .keyCode and .flags members, proxy objects are used
to enable the generation of suitable deprecations warnings.

All direct access via .raw, .keyCode and .flags have been replaced
throughout Kaleidoscope.

Information on how to upgrade is provided in UPGRADING.md

Signed-off-by: Florian Fleissner <florian.fleissner@inpartik.de>
---
 NEWS.md                                       |  16 ++
 UPGRADING.md                                  |  44 ++++-
 doc/plugin/Cycle.md                           |   6 +-
 examples/Keystrokes/Cycle/Cycle.ino           |   8 +-
 .../LEDs/LED-AlphaSquare/LED-AlphaSquare.ino  |   2 +-
 src/kaleidoscope/hooks.h                      |   2 +-
 src/kaleidoscope/key_defs.h                   | 170 ++++++++++++++----
 src/kaleidoscope/key_events.cpp               |  20 +--
 src/kaleidoscope/keymaps.h                    |   2 +-
 src/kaleidoscope/layers.cpp                   |  12 +-
 src/kaleidoscope/plugin/Cycle.cpp             |  31 ++--
 src/kaleidoscope/plugin/DynamicMacros.cpp     |   9 +-
 .../plugin/EEPROM-Keymap-Programmer.cpp       |   6 +-
 src/kaleidoscope/plugin/EEPROM-Keymap.cpp     |  12 +-
 src/kaleidoscope/plugin/Escape-OneShot.cpp    |   2 +-
 src/kaleidoscope/plugin/FocusSerial.h         |   4 +-
 src/kaleidoscope/plugin/GeminiPR.cpp          |   2 +-
 .../plugin/LED-ActiveModColor.cpp             |  10 +-
 src/kaleidoscope/plugin/LED-AlphaSquare.cpp   |   4 +-
 src/kaleidoscope/plugin/LEDControl.cpp        |   2 +-
 .../plugin/LEDEffect-BootAnimation.cpp        |  29 ++-
 .../plugin/LEDEffect-BootGreeting.cpp         |   2 +-
 src/kaleidoscope/plugin/Leader.cpp            |  21 +--
 src/kaleidoscope/plugin/Macros.cpp            |  35 ++--
 src/kaleidoscope/plugin/Macros/MacroSteps.h   |   4 +-
 src/kaleidoscope/plugin/MouseKeys.cpp         |  40 ++---
 src/kaleidoscope/plugin/NumPad.cpp            |   2 +-
 src/kaleidoscope/plugin/OneShot.cpp           |  28 +--
 src/kaleidoscope/plugin/OneShot.h             |   6 +-
 src/kaleidoscope/plugin/Qukeys.cpp            |  22 +--
 src/kaleidoscope/plugin/Qukeys.h              |   6 +-
 src/kaleidoscope/plugin/ShapeShifter.cpp      |  10 +-
 src/kaleidoscope/plugin/SpaceCadet.cpp        |  16 +-
 src/kaleidoscope/plugin/Syster.cpp            |  12 +-
 src/kaleidoscope/plugin/TapDance.cpp          |  29 ++-
 src/kaleidoscope/plugin/TopsyTurvy.cpp        |   4 +-
 src/kaleidoscope/plugin/TopsyTurvy.h          |   2 +-
 src/kaleidoscope/plugin/TriColor.cpp          |  18 +-
 src/kaleidoscope/plugin/Turbo.h               |   2 +-
 src/kaleidoscope/plugin/Unicode.cpp           |  20 +--
 src/kaleidoscope_internal/deprecations.h      |  20 ++-
 41 files changed, 430 insertions(+), 262 deletions(-)

diff --git a/NEWS.md b/NEWS.md
index 74c6aafb..1e4abe33 100644
--- a/NEWS.md
+++ b/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.
diff --git a/UPGRADING.md b/UPGRADING.md
index 7acfda77..c62f2940 100644
--- a/UPGRADING.md
+++ b/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
diff --git a/doc/plugin/Cycle.md b/doc/plugin/Cycle.md
index 57550441..7e31dadc 100644
--- a/doc/plugin/Cycle.md
+++ b/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;
-  if (previous_key.keyCode == Key_A.keyCode && is_shifted)
+  bool is_shifted = previous_key.getFlags() & SHIFT_HELD;
+  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);
 }
 
diff --git a/examples/Keystrokes/Cycle/Cycle.ino b/examples/Keystrokes/Cycle/Cycle.ino
index 4b28b4f2..b8b33dd0 100644
--- a/examples/Keystrokes/Cycle/Cycle.ino
+++ b/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;
-  if (previous_key.keyCode == Key_A.keyCode && is_shifted)
+  bool is_shifted = previous_key.getFlags() & SHIFT_HELD;
+  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);
 }
 
diff --git a/examples/LEDs/LED-AlphaSquare/LED-AlphaSquare.ino b/examples/LEDs/LED-AlphaSquare/LED-AlphaSquare.ino
index 7346fd9c..0f8e6615 100644
--- a/examples/LEDs/LED-AlphaSquare/LED-AlphaSquare.ino
+++ b/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);
diff --git a/src/kaleidoscope/hooks.h b/src/kaleidoscope/hooks.h
index 43646f12..4e154f49 100644
--- a/src/kaleidoscope/hooks.h
+++ b/src/kaleidoscope/hooks.h
@@ -19,7 +19,7 @@
 #include <Arduino.h>
 
 namespace kaleidoscope {
-union Key;
+class Key;
 }
 
 #include "kaleidoscope/KeyAddr.h"
diff --git a/src/kaleidoscope/key_defs.h b/src/kaleidoscope/key_defs.h
index 964aae71..3330a257 100644
--- a/src/kaleidoscope/key_defs.h
+++ b/src/kaleidoscope/key_defs.h
@@ -30,63 +30,163 @@
 
 namespace kaleidoscope {
 
-union Key {
+class Key {
 
-  struct {
-    uint8_t keyCode;
-    uint8_t flags;
-  };
-  uint16_t raw;
+ public:
+
+  typedef uint16_t StorageType;
 
   Key() = default;
 
-  constexpr Key(uint8_t __keyCode, uint8_t __flags)
-    : keyCode(__keyCode), flags(__flags) {
+  constexpr Key(uint16_t raw)
+    : 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)
-    : raw(__raw) {
+  void setRaw(uint16_t 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 {
-    return this->raw == rhs;
+  constexpr bool operator==(const StorageType rhs) const {
+    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) {
-    this->raw = raw;
+  Key& operator=(const StorageType raw) {
+    this->setRaw(raw);
     return *this;
   }
   constexpr bool operator!=(const Key& rhs) const {
     return !(*this == rhs);
   }
-  constexpr bool operator>=(const uint16_t raw) const {
-    return this->raw >= raw;
+  constexpr bool operator>=(const StorageType raw) const {
+    return this->getRaw() >= raw;
   }
-  constexpr bool operator<=(const uint16_t raw) const {
-    return this->raw <= raw;
+  constexpr bool operator<=(const StorageType raw) const {
+    return this->getRaw() <= raw;
   }
-  constexpr bool operator>(const uint16_t raw) const {
-    return this->raw > raw;
+  constexpr bool operator>(const StorageType raw) const {
+    return this->getRaw() > raw;
   }
-  constexpr bool operator<(const uint16_t raw) const {
-    return this->raw < raw;
+  constexpr bool operator<(const StorageType raw) const {
+    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 LALT(k)   Key(k.keyCode, k.flags | LALT_HELD)
-#define RALT(k)   Key(k.keyCode, k.flags | RALT_HELD)
-#define LSHIFT(k) Key(k.keyCode, k.flags | SHIFT_HELD)
-#define LGUI(k)   Key(k.keyCode, k.flags | GUI_HELD)
+#define LCTRL(k)  Key(k.getKeyCode(), k.getFlags() | CTRL_HELD)
+#define LALT(k)   Key(k.getKeyCode(), k.getFlags() | LALT_HELD)
+#define RALT(k)   Key(k.getKeyCode(), k.getFlags() | RALT_HELD)
+#define LSHIFT(k) Key(k.getKeyCode(), k.getFlags() | SHIFT_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};
+}
diff --git a/src/kaleidoscope/key_events.cpp b/src/kaleidoscope/key_events.cpp
index d57c6bc8..94feafca 100644
--- a/src/kaleidoscope/key_events.cpp
+++ b/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);
 }
diff --git a/src/kaleidoscope/keymaps.h b/src/kaleidoscope/keymaps.h
index 638a779e..3bc2f772 100644
--- a/src/kaleidoscope/keymaps.h
+++ b/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 {
diff --git a/src/kaleidoscope/layers.cpp b/src/kaleidoscope/layers.cpp
index 7cc06ad0..ac59b49b 100644
--- a/src/kaleidoscope/layers.cpp
+++ b/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) {
-    uint8_t target = keymapEntry.keyCode - LAYER_SHIFT_OFFSET;
+  if (keymapEntry.getKeyCode() >= 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)
-      deactivate(keymapEntry.keyCode);
+    if (Layer.isActive(keymapEntry.getKeyCode()) && keymapEntry.getKeyCode())
+      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);
diff --git a/src/kaleidoscope/plugin/Cycle.cpp b/src/kaleidoscope/plugin/Cycle.cpp
index c14dd9fd..ff4189e4 100644
--- a/src/kaleidoscope/plugin/Cycle.cpp
+++ b/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;
-
-  key.raw = pgm_read_word(&cycle_steps[idx].raw);
-  replace(key);
+  replace(cycle_steps[idx].readFromProgmem());
 }
 
 // --- 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);
-      last_non_cycle_key_.keyCode = mapped_key.keyCode;
-      last_non_cycle_key_.flags = current_modifier_flags_;
+      current_modifier_flags_ |= toModFlag(mapped_key.getKeyCode());
+      last_non_cycle_key_.setKeyCode(mapped_key.getKeyCode());
+      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_RightShift.keyCode:
+  case Key_LeftShift.getKeyCode():
+  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_RightControl.keyCode:
+  case Key_LeftControl.getKeyCode():
+  case Key_RightControl.getKeyCode():
     return CTRL_HELD;
-  case Key_LeftGui.keyCode:
-  case Key_RightGui.keyCode:
+  case Key_LeftGui.getKeyCode():
+  case Key_RightGui.getKeyCode():
     return GUI_HELD;
   default:
     return 0;
diff --git a/src/kaleidoscope/plugin/DynamicMacros.cpp b/src/kaleidoscope/plugin/DynamicMacros.cpp
index ff07cdef..424145aa 100644
--- a/src/kaleidoscope/plugin/DynamicMacros.cpp
+++ b/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.flags = flags;
-  key.keyCode = Kaleidoscope.storage().read(pos++);
+  Key key(Kaleidoscope.storage().read(pos++), // key_code
+          flags);
 
   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;
diff --git a/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp b/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp
index b1cdb0f2..32a9c2d1 100644
--- a/src/kaleidoscope/plugin/EEPROM-Keymap-Programmer.cpp
+++ b/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;
 }
diff --git a/src/kaleidoscope/plugin/EEPROM-Keymap.cpp b/src/kaleidoscope/plugin/EEPROM-Keymap.cpp
index aa7cf0cd..0deaaf45 100644
--- a/src/kaleidoscope/plugin/EEPROM-Keymap.cpp
+++ b/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);
-  key.keyCode = Kaleidoscope.storage().read(keymap_base_ + pos + 1);
-
-  return key;
+  return Key(Kaleidoscope.storage().read(keymap_base_ + pos + 1), // key_code
+             Kaleidoscope.storage().read(keymap_base_ + pos));    // flags
 }
 
 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 + 1, key.keyCode);
+  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2, key.getFlags());
+  Kaleidoscope.storage().update(keymap_base_ + base_pos * 2 + 1, key.getKeyCode());
 }
 
 void EEPROMKeymap::dumpKeymap(uint8_t layers, Key(*getkey)(uint8_t, KeyAddr)) {
diff --git a/src/kaleidoscope/plugin/Escape-OneShot.cpp b/src/kaleidoscope/plugin/Escape-OneShot.cpp
index 34c1ecf1..7dd8451a 100644
--- a/src/kaleidoscope/plugin/Escape-OneShot.cpp
+++ b/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;
diff --git a/src/kaleidoscope/plugin/FocusSerial.h b/src/kaleidoscope/plugin/FocusSerial.h
index 2c2235e6..0b7051f7 100644
--- a/src/kaleidoscope/plugin/FocusSerial.h
+++ b/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();
diff --git a/src/kaleidoscope/plugin/GeminiPR.cpp b/src/kaleidoscope/plugin/GeminiPR.cpp
index 4225a5bc..e3ae17fd 100644
--- a/src/kaleidoscope/plugin/GeminiPR.cpp
+++ b/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));
diff --git a/src/kaleidoscope/plugin/LED-ActiveModColor.cpp b/src/kaleidoscope/plugin/LED-ActiveModColor.cpp
index 6636b6fa..96269f6f 100644
--- a/src/kaleidoscope/plugin/LED-ActiveModColor.cpp
+++ b/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.flags == (SYNTHETIC | SWITCH_TO_KEYMAP))))) {
+           (k >= Key_LeftControl && k <= Key_RightGui) ||
+           (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)) {
-      uint8_t layer = k.keyCode;
+    } else if (k.getFlags() == (SYNTHETIC | SWITCH_TO_KEYMAP)) {
+      uint8_t layer = k.getKeyCode();
       if (layer >= LAYER_SHIFT_OFFSET)
         layer -= LAYER_SHIFT_OFFSET;
 
diff --git a/src/kaleidoscope/plugin/LED-AlphaSquare.cpp b/src/kaleidoscope/plugin/LED-AlphaSquare.cpp
index 459acd93..bef9d494 100644
--- a/src/kaleidoscope/plugin/LED-AlphaSquare.cpp
+++ b/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);
diff --git a/src/kaleidoscope/plugin/LEDControl.cpp b/src/kaleidoscope/plugin/LEDControl.cpp
index 96306104..9dc3b931 100644
--- a/src/kaleidoscope/plugin/LEDControl.cpp
+++ b/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)) {
diff --git a/src/kaleidoscope/plugin/LEDEffect-BootAnimation.cpp b/src/kaleidoscope/plugin/LEDEffect-BootAnimation.cpp
index ac52d933..eda7dd59 100644
--- a/src/kaleidoscope/plugin/LEDEffect-BootAnimation.cpp
+++ b/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_E.keyCode,
-  Key_Y.keyCode,
-  Key_B.keyCode,
-  Key_O.keyCode,
-  Key_A.keyCode,
-  Key_R.keyCode,
-  Key_D.keyCode,
-  Key_Period.keyCode,
-  Key_I.keyCode,
-  Key_O.keyCode
+  Key_K.getKeyCode(),
+  Key_E.getKeyCode(),
+  Key_Y.getKeyCode(),
+  Key_B.getKeyCode(),
+  Key_O.getKeyCode(),
+  Key_A.getKeyCode(),
+  Key_R.getKeyCode(),
+  Key_D.getKeyCode(),
+  Key_Period.getKeyCode(),
+  Key_I.getKeyCode(),
+  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;
-    g.flags = 0;
-    g.keyCode = pgm_read_byte(&greeting_[current_index_]);
+    Key g(pgm_read_byte(&greeting_[current_index_]), // key_code
+          0);                                        // flags
 
-    if (k.raw == g.raw) {
+    if (k == g) {
       key_addr_found = key_addr;
       break;
     }
diff --git a/src/kaleidoscope/plugin/LEDEffect-BootGreeting.cpp b/src/kaleidoscope/plugin/LEDEffect-BootGreeting.cpp
index 36f598d5..070a03b3 100644
--- a/src/kaleidoscope/plugin/LEDEffect-BootGreeting.cpp
+++ b/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;
     }
diff --git a/src/kaleidoscope/plugin/Leader.cpp b/src/kaleidoscope/plugin/Leader.cpp
index bdfeb25d..ca5f2fd1 100644
--- a/src/kaleidoscope/plugin/Leader.cpp
+++ b/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 isActive() (sequence_[0].raw != Key_NoKey.raw)
+#define isLeader(k) (k.getRaw() >= ranges::LEAD_FIRST && k.getRaw() <= ranges::LEAD_LAST)
+#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));
-    if (seq_key.raw == Key_NoKey.raw) {
+    seq_key
+      = 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) {
diff --git a/src/kaleidoscope/plugin/Macros.cpp b/src/kaleidoscope/plugin/Macros.cpp
index 23e5db69..cc89ce30 100644
--- a/src/kaleidoscope/plugin/Macros.cpp
+++ b/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.flags = flags;
-  key.keyCode = pgm_read_byte(macro_p++);
+  Key key(pgm_read_byte(macro_p++), // key_code
+          flags);
 
   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.keyCode = Key_A.keyCode + ascii_code - 0x41;
+    key.setFlags(SHIFT_HELD);
+    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;
 }
diff --git a/src/kaleidoscope/plugin/Macros/MacroSteps.h b/src/kaleidoscope/plugin/Macros/MacroSteps.h
index 49f988fb..68b74720 100644
--- a/src/kaleidoscope/plugin/Macros/MacroSteps.h
+++ b/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 Kc(k) (Key_ ## k).keyCode
+#define Kr(k) (k).getFlags(), (k).getKeyCode()
+#define Kc(k) (Key_ ## k).getKeyCode()
 #define K(k) Kr(Key_ ## k)
 
 #define Dr(k) MACRO_ACTION_STEP_KEYDOWN, Kr(k)
diff --git a/src/kaleidoscope/plugin/MouseKeys.cpp b/src/kaleidoscope/plugin/MouseKeys.cpp
index 24e79879..cf80c9ce 100644
--- a/src/kaleidoscope/plugin/MouseKeys.cpp
+++ b/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)) {
-    uint8_t button = mappedKey.keyCode & ~KEY_MOUSE_BUTTON;
+  if (mappedKey.getKeyCode() & KEY_MOUSE_BUTTON && !(mappedKey.getKeyCode() & KEY_MOUSE_WARP)) {
+    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) {
-        scrollWheel(mappedKey.keyCode);
+      if (mappedKey.getKeyCode() & KEY_MOUSE_WHEEL) {
+        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 ||
-          mappedKey.keyCode & KEY_MOUSE_DOWN) {
-        if (mappedKey.keyCode & KEY_MOUSE_WHEEL) {
+      if (mappedKey.getKeyCode() & KEY_MOUSE_UP ||
+          mappedKey.getKeyCode() & KEY_MOUSE_DOWN) {
+        if (mappedKey.getKeyCode() & KEY_MOUSE_WHEEL) {
           vWheel = true;
         } else {
           y = true;
         }
-      } else if (mappedKey.keyCode & KEY_MOUSE_LEFT ||
-                 mappedKey.keyCode & KEY_MOUSE_RIGHT) {
-        if (mappedKey.keyCode & KEY_MOUSE_WHEEL) {
+      } else if (mappedKey.getKeyCode() & KEY_MOUSE_LEFT ||
+                 mappedKey.getKeyCode() & KEY_MOUSE_RIGHT) {
+        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) {
-      MouseWrapper.warp(((mappedKey.keyCode & KEY_MOUSE_WARP_END) ? WARP_END : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_UP) ? WARP_UP : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_DOWN) ? WARP_DOWN : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_LEFT) ? WARP_LEFT : 0x00) |
-                        ((mappedKey.keyCode & KEY_MOUSE_RIGHT) ? WARP_RIGHT : 0x00));
+    if (mappedKey.getKeyCode() & KEY_MOUSE_WARP && mappedKey.getFlags() & IS_MOUSE_KEY) {
+      MouseWrapper.warp(((mappedKey.getKeyCode() & KEY_MOUSE_WARP_END) ? WARP_END : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_UP) ? WARP_UP : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_DOWN) ? WARP_DOWN : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_LEFT) ? WARP_LEFT : 0x00) |
+                        ((mappedKey.getKeyCode() & KEY_MOUSE_RIGHT) ? WARP_RIGHT : 0x00));
     }
   }
 
diff --git a/src/kaleidoscope/plugin/NumPad.cpp b/src/kaleidoscope/plugin/NumPad.cpp
index 105576ab..4a2629fe 100644
--- a/src/kaleidoscope/plugin/NumPad.cpp
+++ b/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);
diff --git a/src/kaleidoscope/plugin/OneShot.cpp b/src/kaleidoscope/plugin/OneShot.cpp
index 6b05765c..7cebc507 100644
--- a/src/kaleidoscope/plugin/OneShot.cpp
+++ b/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.keyCode = Key_LeftControl.keyCode + idx;
+    key = Key(Key_LeftControl.getKeyCode() + idx,
+              Key_LeftControl.getFlags());
   } else {
-    key.flags = KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP;
-    key.keyCode = LAYER_SHIFT_OFFSET + idx - 8;
+    key = Key(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) &&
-        !(mapped_key.flags == (KEY_FLAGS | SYNTHETIC | SWITCH_TO_KEYMAP))) {
+    if (!(mapped_key >= Key_LeftControl && mapped_key <= Key_RightGui) &&
+        !(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() {
diff --git a/src/kaleidoscope/plugin/OneShot.h b/src/kaleidoscope/plugin/OneShot.h
index 3142eb29..b59a639e 100644
--- a/src/kaleidoscope/plugin/OneShot.h
+++ b/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);
diff --git a/src/kaleidoscope/plugin/Qukeys.cpp b/src/kaleidoscope/plugin/Qukeys.cpp
index 5b8ec111..09661c18 100644
--- a/src/kaleidoscope/plugin/Qukeys.cpp
+++ b/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) {
-    return (key.keyCode >= HID_KEYBOARD_FIRST_MODIFIER &&
-            key.keyCode <= HID_KEYBOARD_LAST_MODIFIER);
+  if ((key.getFlags() & (SYNTHETIC | RESERVED)) == 0) {
+    return (key.getKeyCode() >= HID_KEYBOARD_FIRST_MODIFIER &&
+            key.getKeyCode() <= HID_KEYBOARD_LAST_MODIFIER);
   }
   // If it's a layer shift key, return true:
-  if (key.flags == (SYNTHETIC | SWITCH_TO_KEYMAP) &&
-      key.keyCode >= LAYER_SHIFT_OFFSET) {
+  if (key.getFlags() == (SYNTHETIC | SWITCH_TO_KEYMAP) &&
+      key.getKeyCode() >= LAYER_SHIFT_OFFSET) {
     return true;
   }
   // In all other cases, return false:
diff --git a/src/kaleidoscope/plugin/Qukeys.h b/src/kaleidoscope/plugin/Qukeys.h
index cdd51359..949134fb 100644
--- a/src/kaleidoscope/plugin/Qukeys.h
+++ b/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_ ## key).keyCode                                               \
+    (((Key_ ## mod).getKeyCode() - Key_LeftControl.getKeyCode()) << 8) +          \
+    (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" \
diff --git a/src/kaleidoscope/plugin/ShapeShifter.cpp b/src/kaleidoscope/plugin/ShapeShifter.cpp
index f81541ae..ec86bac3 100644
--- a/src/kaleidoscope/plugin/ShapeShifter.cpp
+++ b/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 &&
-           orig.raw != mapped_key.raw);
+  } while (orig != Key_NoKey &&
+           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;
diff --git a/src/kaleidoscope/plugin/SpaceCadet.cpp b/src/kaleidoscope/plugin/SpaceCadet.cpp
index 8e544649..7db08f4f 100644
--- a/src/kaleidoscope/plugin/SpaceCadet.cpp
+++ b/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 &&
-      mapped_key.raw <= kaleidoscope::ranges::SC_LAST) {
+  if (mapped_key.getRaw() >= kaleidoscope::ranges::SC_FIRST &&
+      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].output.raw == Key_NoKey.raw
+        map[i].input == Key_NoKey
+        && 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].output.raw == Key_NoKey.raw
+      map[i].input == Key_NoKey
+      && 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;
     }
   }
diff --git a/src/kaleidoscope/plugin/Syster.cpp b/src/kaleidoscope/plugin/Syster.cpp
index b2247176..d8dee378 100644
--- a/src/kaleidoscope/plugin/Syster.cpp
+++ b/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) {
-  case Key_A.keyCode ... Key_Z.keyCode:
-    return 'a' + (key.keyCode - Key_A.keyCode);
-  case Key_1.keyCode ... Key_0.keyCode:
-    return '1' + (key.keyCode - Key_1.keyCode);
+  switch (key.getKeyCode()) {
+  case Key_A.getKeyCode() ... Key_Z.getKeyCode():
+    return 'a' + (key.getKeyCode() - Key_A.getKeyCode());
+  case Key_1.getKeyCode() ... Key_0.getKeyCode():
+    return '1' + (key.getKeyCode() - Key_1.getKeyCode());
   }
 
   return 0;
diff --git a/src/kaleidoscope/plugin/TapDance.cpp b/src/kaleidoscope/plugin/TapDance.cpp
index ad5c2c4e..7a8da000 100644
--- a/src/kaleidoscope/plugin/TapDance.cpp
+++ b/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.raw = pgm_read_word(&(tap_keys[tap_count - 1].raw));
+  Key key = tap_keys[tap_count - 1].readFromProgmem();
 
   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 (last_tap_dance_key_.raw == Key_NoKey.raw)
+  if (mapped_key.getRaw() < ranges::TD_FIRST || mapped_key.getRaw() > ranges::TD_LAST) {
+    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_.raw == Key_NoKey.raw) {
+  if (last_tap_dance_key_ != mapped_key) {
+    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))
diff --git a/src/kaleidoscope/plugin/TopsyTurvy.cpp b/src/kaleidoscope/plugin/TopsyTurvy.cpp
index c0df461a..65417a1e 100644
--- a/src/kaleidoscope/plugin/TopsyTurvy.cpp
+++ b/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;
   }
 
diff --git a/src/kaleidoscope/plugin/TopsyTurvy.h b/src/kaleidoscope/plugin/TopsyTurvy.h
index 2462357b..b90b86e7 100644
--- a/src/kaleidoscope/plugin/TopsyTurvy.h
+++ b/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 {
diff --git a/src/kaleidoscope/plugin/TriColor.cpp b/src/kaleidoscope/plugin/TriColor.cpp
index 965e6adc..8f6b7ef5 100644
--- a/src/kaleidoscope/plugin/TriColor.cpp
+++ b/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) {
-    case Key_A.keyCode ... Key_0.keyCode:
-    case Key_Spacebar.keyCode:
-    case Key_KeypadDivide.keyCode ... Key_KeypadSubtract.keyCode:
-    case Key_Keypad1.keyCode ... Key_KeypadDot.keyCode:
-    case Key_F1.keyCode ... Key_F4.keyCode:
-    case Key_F9.keyCode ... Key_F12.keyCode:
+    switch (k.getKeyCode()) {
+    case Key_A.getKeyCode() ... Key_0.getKeyCode():
+    case Key_Spacebar.getKeyCode():
+    case Key_KeypadDivide.getKeyCode() ... Key_KeypadSubtract.getKeyCode():
+    case Key_Keypad1.getKeyCode() ... Key_KeypadDot.getKeyCode():
+    case Key_F1.getKeyCode() ... Key_F4.getKeyCode():
+    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;
     }
diff --git a/src/kaleidoscope/plugin/Turbo.h b/src/kaleidoscope/plugin/Turbo.h
index a6d2202d..4e1ad7b7 100644
--- a/src/kaleidoscope/plugin/Turbo.h
+++ b/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 {
diff --git a/src/kaleidoscope/plugin/Unicode.cpp b/src/kaleidoscope/plugin/Unicode.cpp
index 8581eb7b..cf05c9ac 100644
--- a/src/kaleidoscope/plugin/Unicode.cpp
+++ b/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;
     }
   }
diff --git a/src/kaleidoscope_internal/deprecations.h b/src/kaleidoscope_internal/deprecations.h
index d92e9fd5..cc2c2851 100644
--- a/src/kaleidoscope_internal/deprecations.h
+++ b/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."