Exposing ModifiersExt

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
 

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;

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;
 }