Add optional Serde implementations and missing derivable traits (#652)

* Add optional serde feature

* Document features in README

* Add changelog entry

* Implement some missing derivable traits

* Add changelog entry for std derives

* Remove extraneous space on serde doc comments

* Add period to end of serde line in readme

* Remove serde impls from WindowAttributes

* Add serde impls for TouchPhase

* Add serde test file

* Add feature lines to testing CIs

* Remove WindowAttributes from changelog

.travis.yml

@@ -65,8 +65,12 @@ install:
 
 script:
   - cargo build --target $TARGET --verbose
+  - cargo build --target $TARGET --features serde --verbose
+  - cargo build --target $TARGET --features icon_loading --verbose
   # Running iOS apps on OSX requires the simulator so we skip that for now
   - if [ "$TARGET" != "x86_64-apple-ios" ]; then cargo test --target $TARGET --verbose; fi
+  - if [ "$TARGET" != "x86_64-apple-ios" ]; then cargo test --target $TARGET --features serde --verbose; fi
+  - if [ "$TARGET" != "x86_64-apple-ios" ]; then cargo test --target $TARGET --features icon_loading --verbose; fi
 
 after_success:
   - |

CHANGELOG.md

@@ -21,6 +21,8 @@
 - On X11, now a `Resized` event will always be generated after a DPI change to ensure the window's logical size is consistent with the new DPI.
 - Added further clarifications to the DPI docs.
 - On Linux, if neither X11 nor Wayland manage to initialize, the corresponding panic now consists of a single line only.
+- Add optional `serde` feature with implementations of `Serialize`/`Deserialize` for DPI types and various event types.
+- Add `PartialEq`, `Eq`, and `Hash` implementations on public types that could have them but were missing them.
 
 # Version 0.17.2 (2018-08-19)
 

Cargo.toml

@@ -11,7 +11,7 @@ documentation = "https://docs.rs/winit"
 categories = ["gui"]
 
 [package.metadata.docs.rs]
-features = ["icon_loading"]
+features = ["icon_loading", "serde"]
 
 [features]
 icon_loading = ["image"]
@@ -21,6 +21,7 @@ lazy_static = "1"
 libc = "0.2"
 log = "0.4"
 image = { version = "0.20", optional = true }
+serde = { version = "1", optional = true, features = ["serde_derive"] }
 
 [target.'cfg(target_os = "android")'.dependencies.android_glue]
 version = "0.2"

README.md

@@ -41,6 +41,12 @@ fn main() {
 }
 ```
 
+### Cargo Features
+
+Winit provides the following features, which can be enabled in your `Cargo.toml` file:
+* `icon_loading`: Enables loading window icons directly from files. Depends on the [`image` crate](https://crates.io/crates/image).
+* `serde`: Enables serialization/deserialization of certain types with [Serde](https://crates.io/crates/serde).
+
 ### Platform-specific usage
 
 #### Emscripten and WebAssembly

appveyor.yml

@@ -22,3 +22,5 @@ build: false
 
 test_script:
   - cargo test --verbose
+  - cargo test --features serde --verbose
+  - cargo test --features icon_loading --verbose

src/dpi.rs

@@ -92,6 +92,7 @@ pub fn validate_hidpi_factor(dpi_factor: f64) -> bool {
 /// which can cause noticable issues. To help with that, an `Into<(i32, i32)>` implementation is provided which
 /// does the rounding for you.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct LogicalPosition {
     pub x: f64,
     pub y: f64,
@@ -152,6 +153,7 @@ impl Into<(i32, i32)> for LogicalPosition {
 /// which can cause noticable issues. To help with that, an `Into<(i32, i32)>` implementation is provided which
 /// does the rounding for you.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct PhysicalPosition {
     pub x: f64,
     pub y: f64,
@@ -212,6 +214,7 @@ impl Into<(i32, i32)> for PhysicalPosition {
 /// which can cause noticable issues. To help with that, an `Into<(u32, u32)>` implementation is provided which
 /// does the rounding for you.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct LogicalSize {
     pub width: f64,
     pub height: f64,
@@ -272,6 +275,7 @@ impl Into<(u32, u32)> for LogicalSize {
 /// which can cause noticable issues. To help with that, an `Into<(u32, u32)>` implementation is provided which
 /// does the rounding for you.
 #[derive(Debug, Copy, Clone, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct PhysicalSize {
     pub width: f64,
     pub height: f64,

src/events.rs

@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use {DeviceId, LogicalPosition, LogicalSize, WindowId};
 
 /// Describes a generic event.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq)]
 pub enum Event {
     WindowEvent {
         window_id: WindowId,
@@ -22,7 +22,7 @@ pub enum Event {
 }
 
 /// Describes an event from a `Window`.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq)]
 pub enum WindowEvent {
     /// The size of the window has changed. Contains the client area's new dimensions.
     Resized(LogicalSize),
@@ -116,7 +116,7 @@ pub enum WindowEvent {
 /// may not match.
 ///
 /// Note that these events are delivered regardless of input focus.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, PartialEq)]
 pub enum DeviceEvent {
     Added,
     Removed,
@@ -147,7 +147,8 @@ pub enum DeviceEvent {
 }
 
 /// Describes a keyboard input event.
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub struct KeyboardInput {
     /// Identifies the physical key pressed
     ///
@@ -173,6 +174,7 @@ pub struct KeyboardInput {
 
 /// Describes touch-screen input state.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum TouchPhase {
     Started,
     Moved,
@@ -195,7 +197,7 @@ pub enum TouchPhase {
 /// as previously received End event is a new finger and has nothing to do with an old one.
 ///
 /// Touch may be cancelled if for example window lost focus.
-#[derive(Debug, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Touch {
     pub device_id: DeviceId,
     pub phase: TouchPhase,
@@ -215,6 +217,7 @@ pub type ButtonId = u32;
 
 /// Describes the input state of a key.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum ElementState {
     Pressed,
     Released,
@@ -222,6 +225,7 @@ pub enum ElementState {
 
 /// Describes a button of a mouse controller.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum MouseButton {
     Left,
     Right,
@@ -231,6 +235,7 @@ pub enum MouseButton {
 
 /// Describes a difference in the mouse scroll wheel state.
 #[derive(Debug, Clone, Copy, PartialEq)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum MouseScrollDelta {
 	/// Amount in lines or rows to scroll in the horizontal
 	/// and vertical directions.
@@ -250,6 +255,7 @@ pub enum MouseScrollDelta {
 /// Symbolic name for a keyboard key.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, Copy)]
 #[repr(u32)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum VirtualKeyCode {
     /// The '1' key over the letters.
     Key1,
@@ -449,6 +455,8 @@ pub enum VirtualKeyCode {
 ///
 /// Each field of this struct represents a modifier and is `true` if this modifier is active.
 #[derive(Default, Debug, Hash, PartialEq, Eq, Clone, Copy)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+#[cfg_attr(feature = "serde", serde(default))]
 pub struct ModifiersState {
     /// The "shift" key
     pub shift: bool,

src/lib.rs

@@ -92,6 +92,9 @@ extern crate libc;
 extern crate log;
 #[cfg(feature = "icon_loading")]
 extern crate image;
+#[cfg(feature = "serde")]
+#[macro_use]
+extern crate serde;
 
 #[cfg(target_os = "windows")]
 extern crate winapi;
@@ -199,7 +202,8 @@ impl std::fmt::Debug for EventsLoop {
 /// Returned by the user callback given to the `EventsLoop::run_forever` method.
 ///
 /// Indicates whether the `run_forever` method should continue or complete.
-#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum ControlFlow {
     /// Continue looping and waiting for events.
     Continue,
@@ -357,7 +361,8 @@ impl std::error::Error for CreationError {
 }
 
 /// Describes the appearance of the mouse cursor.
-#[derive(Debug, Copy, Clone, PartialEq)]
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
 pub enum MouseCursor {
     /// The platform-dependent default cursor.
     Default,

tests/serde_objects.rs

@@ -0,0 +1,39 @@
+#![cfg(feature = "serde")]
+
+extern crate serde;
+extern crate winit;
+
+use winit::{ControlFlow, MouseCursor};
+use winit::{
+    KeyboardInput, TouchPhase, ElementState, MouseButton, MouseScrollDelta, VirtualKeyCode,
+    ModifiersState
+};
+use winit::dpi::{LogicalPosition, PhysicalPosition, LogicalSize, PhysicalSize};
+use serde::{Serialize, Deserialize};
+
+fn needs_serde<S: Serialize + Deserialize<'static>>() {}
+
+#[test]
+fn root_serde() {
+    needs_serde::<ControlFlow>();
+    needs_serde::<MouseCursor>();
+}
+
+#[test]
+fn events_serde() {
+    needs_serde::<KeyboardInput>();
+    needs_serde::<TouchPhase>();
+    needs_serde::<ElementState>();
+    needs_serde::<MouseButton>();
+    needs_serde::<MouseScrollDelta>();
+    needs_serde::<VirtualKeyCode>();
+    needs_serde::<ModifiersState>();
+}
+
+#[test]
+fn dpi_serde() {
+    needs_serde::<LogicalPosition>();
+    needs_serde::<PhysicalPosition>();
+    needs_serde::<LogicalSize>();
+    needs_serde::<PhysicalSize>();
+}