From a63af0f9dee8fd5d75c55ff17535ea217aaf0288 Mon Sep 17 00:00:00 2001
From: Jonathan Johnson <jon@khonsulabs.com>
Date: Tue, 19 Mar 2024 10:17:28 -0700
Subject: [PATCH] Exposing ModifiersExt

---
 CHANGELOG.md |  3 +++
 src/lib.rs   |  2 +-
 src/utils.rs | 20 ++++++++++++++++++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 80cd79e..d61fda0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -234,6 +234,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Graphics::font_system()` returns a reference to the underlying Cosmic Text
   `FontSystem`.
 - `Window::vsync` is a new setting that allows disabling VSync for that window.
+- `ModifiersExt` is an extension trait for winit's `Modifiers` and
+  `ModifiersState` types. This trait adds helpers for dealing with
+  platform-specific meanings for keyboard modifiers.
 
 [plotters]: https://github.com/plotters-rs/plotters
 
diff --git a/src/lib.rs b/src/lib.rs
index 91ee6b7..7914631 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -30,7 +30,7 @@ use figures::units::UPx;
 use figures::{Fraction, ScreenUnit, Size, Zero};
 use kludgine::app::winit::error::EventLoopError;
 pub use names::Name;
-pub use utils::{Lazy, WithClone};
+pub use utils::{Lazy, ModifiersExt, WithClone};
 pub use {figures, kludgine};
 
 pub use self::graphics::Graphics;
diff --git a/src/utils.rs b/src/utils.rs
index 9fd9075..f531e59 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -70,10 +70,30 @@ where
 
 impl_all_tuples!(impl_with_clone);
 
+/// Helper functions for [`Modifiers`] and [`ModifiersState`].
 pub trait ModifiersExt {
+    /// Returns true if the current state includes the platform's primary
+    /// shortcut key.
+    ///
+    /// For Apple based platforms, this returns true if a "super" modifier is
+    /// pressed. This corresponds to the Apple/Command key.
+    ///
+    /// For all other platforms, this returns true if a control key is pressed.
     fn primary(&self) -> bool;
+
+    /// Returns true if the platform-specific modifier for word-selection is
+    /// pressed.
+    ///
+    /// For Apple-based platforms, this returns true if an "alt" key is pressed.
+    /// This corresponds to the Option key.
+    ///
+    /// For all other platforms, this returns true if a control key is pressed.
     fn word_select(&self) -> bool;
 
+    /// Returns true if the current modifier state might be a shortcut key.
+    ///
+    /// This returns true if either the control key, alt key, or super key are
+    /// pressed.
     fn possible_shortcut(&self) -> bool;
 }