[Feature] Implement `mod_t` packed struct (#25168)

2 files changed, 61 insertions, 7 deletions

diff --git a/quantum/action_util.c b/quantum/action_util.c
index e821e113ef..0996ff908e 100644
--- a/quantum/action_util.c
+++ b/quantum/action_util.c
@@ -46,9 +46,20 @@ extern inline void clear_keys(void);
 #ifndef NO_ACTION_ONESHOT
 static uint8_t oneshot_mods        = 0;
 static uint8_t oneshot_locked_mods = 0;
-uint8_t        get_oneshot_locked_mods(void) {
+/**
+ * @brief Retrieve current state of locked oneshot modifiers.
+ *
+ * @return Current state of the locked oneshot modifier keys as a bitmask.
+ */
+uint8_t get_oneshot_locked_mods(void) {
     return oneshot_locked_mods;
 }
+/**
+ * Same as \ref get_oneshot_locked_mods but returns \ref mod_t for convenience.
+ */
+mod_t get_oneshot_locked_mod_state(void) {
+    return (mod_t)get_oneshot_locked_mods();
+}
 void add_oneshot_locked_mods(uint8_t mods) {
     if ((oneshot_locked_mods & mods) != mods) {
         oneshot_locked_mods |= mods;
@@ -326,13 +337,20 @@ void send_keyboard_report(void) {
     send_6kro_report();
 }
 
-/** \brief Get mods
+/**
+ * @brief Retrieve current state of modifiers.
  *
- * FIXME: needs doc
+ * @return Current state of the modifier keys as a bitmask.
  */
 uint8_t get_mods(void) {
     return real_mods;
 }
+/**
+ * Same as \ref get_mods but returns \ref mod_t for convenience.
+ */
+mod_t get_mod_state(void) {
+    return (mod_t)get_mods();
+}
 /** \brief add mods
  *
  * FIXME: needs doc
@@ -362,13 +380,20 @@ void clear_mods(void) {
     real_mods = 0;
 }
 
-/** \brief get weak mods
+/**
+ * @brief Retrieve current state of weak modifiers.
  *
- * FIXME: needs doc
+ * @return Current state of the weak modifier keys as a bitmask.
  */
 uint8_t get_weak_mods(void) {
     return weak_mods;
 }
+/**
+ * Same as \ref get_weak_mods but returns \ref mod_t for convenience.
+ */
+mod_t get_weak_mod_state(void) {
+    return (mod_t)get_weak_mods();
+}
 /** \brief add weak mods
  *
  * FIXME: needs doc
@@ -423,14 +448,22 @@ void clear_suppressed_override_mods(void) {
 #endif
 
 #ifndef NO_ACTION_ONESHOT
-/** \brief get oneshot mods
+/**
+ * @brief Retrieve current state of oneshot modifiers.
  *
- * FIXME: needs doc
+ * @return Current state of the oneshot modifier keys as a bitmask.
  */
 uint8_t get_oneshot_mods(void) {
     return oneshot_mods;
 }
 
+/**
+ * Same as \ref get_oneshot_mods but returns \ref mod_t for convenience.
+ */
+mod_t get_oneshot_mod_state(void) {
+    return (mod_t)get_oneshot_mods();
+}
+
 void add_oneshot_mods(uint8_t mods) {
     if ((oneshot_mods & mods) != mods) {
 #    if (defined(ONESHOT_TIMEOUT) && (ONESHOT_TIMEOUT > 0))
diff --git a/quantum/action_util.h b/quantum/action_util.h
index d2ecb145be..8b1974cd32 100644
--- a/quantum/action_util.h
+++ b/quantum/action_util.h
@@ -18,6 +18,8 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #pragma once
 
 #include <stdint.h>
+
+#include "compiler_support.h"
 #include "report.h"
 #include "modifiers.h"
 
@@ -25,6 +27,21 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 extern "C" {
 #endif
 
+typedef union {
+    uint8_t raw;
+    struct {
+        bool left_ctrl : 1;
+        bool left_shift : 1;
+        bool left_alt : 1;
+        bool left_gui : 1;
+        bool right_ctrl : 1;
+        bool right_shift : 1;
+        bool right_alt : 1;
+        bool right_gui : 1;
+    };
+} PACKED mod_t;
+STATIC_ASSERT(sizeof(mod_t) == sizeof(uint8_t), "Invalid size for 'mod_t'");
+
 extern report_keyboard_t *keyboard_report;
 #ifdef NKRO_ENABLE
 extern report_nkro_t *nkro_report;
@@ -47,6 +64,7 @@ inline void clear_keys(void) {
 
 /* modifier */
 uint8_t get_mods(void);
+mod_t   get_mod_state(void);
 void    add_mods(uint8_t mods);
 void    del_mods(uint8_t mods);
 void    set_mods(uint8_t mods);
@@ -54,6 +72,7 @@ void    clear_mods(void);
 
 /* weak modifier */
 uint8_t get_weak_mods(void);
+mod_t   get_weak_mod_state(void);
 void    add_weak_mods(uint8_t mods);
 void    del_weak_mods(uint8_t mods);
 void    set_weak_mods(uint8_t mods);
@@ -61,6 +80,7 @@ void    clear_weak_mods(void);
 
 /* oneshot modifier */
 uint8_t get_oneshot_mods(void);
+mod_t   get_oneshot_mod_state(void);
 void    add_oneshot_mods(uint8_t mods);
 void    del_oneshot_mods(uint8_t mods);
 void    set_oneshot_mods(uint8_t mods);
@@ -68,6 +88,7 @@ void    clear_oneshot_mods(void);
 bool    has_oneshot_mods_timed_out(void);
 
 uint8_t get_oneshot_locked_mods(void);
+mod_t   get_oneshot_locked_mod_state(void);
 void    add_oneshot_locked_mods(uint8_t mods);
 void    set_oneshot_locked_mods(uint8_t mods);
 void    clear_oneshot_locked_mods(void);