Introduce `keyboard::on_key_press` and `on_key_release`

Also rename `subscription::events*` to `event::listen*`.

14 files changed, 193 insertions, 138 deletions

diff --git a/examples/events/src/main.rs b/examples/events/src/main.rs
index 7f3a5e1d..32d0da2c 100644
--- a/examples/events/src/main.rs
+++ b/examples/events/src/main.rs
@@ -1,9 +1,8 @@
 use iced::alignment;
+use iced::event::{self, Event};
 use iced::executor;
-use iced::subscription;
 use iced::widget::{button, checkbox, container, text, Column};
 use iced::window;
-use iced::Event;
 use iced::{
     Alignment, Application, Command, Element, Length, Settings, Subscription,
     Theme,
@@ -71,7 +70,7 @@ impl Application for Events {
     }
 
     fn subscription(&self) -> Subscription<Message> {
-        subscription::events().map(Message::EventOccurred)
+        event::listen().map(Message::EventOccurred)
     }
 
     fn view(&self) -> Element<Message> {
diff --git a/examples/modal/src/main.rs b/examples/modal/src/main.rs
index 8a48f830..4aa70886 100644
--- a/examples/modal/src/main.rs
+++ b/examples/modal/src/main.rs
@@ -1,12 +1,14 @@
+use iced::event::{self, Event};
 use iced::executor;
 use iced::keyboard;
-use iced::subscription::{self, Subscription};
 use iced::theme;
 use iced::widget::{
     self, button, column, container, horizontal_space, pick_list, row, text,
     text_input,
 };
-use iced::{Alignment, Application, Command, Element, Event, Length, Settings};
+use iced::{
+    Alignment, Application, Command, Element, Length, Settings, Subscription,
+};
 
 use modal::Modal;
 use std::fmt;
@@ -49,7 +51,7 @@ impl Application for App {
     }
 
     fn subscription(&self) -> Subscription<Self::Message> {
-        subscription::events().map(Message::Event)
+        event::listen().map(Message::Event)
     }
 
     fn update(&mut self, message: Message) -> Command<Message> {
diff --git a/examples/pane_grid/src/main.rs b/examples/pane_grid/src/main.rs
index 04896e20..af87e2c0 100644
--- a/examples/pane_grid/src/main.rs
+++ b/examples/pane_grid/src/main.rs
@@ -1,8 +1,6 @@
 use iced::alignment::{self, Alignment};
-use iced::event::{self, Event};
 use iced::executor;
 use iced::keyboard;
-use iced::subscription;
 use iced::theme::{self, Theme};
 use iced::widget::pane_grid::{self, PaneGrid};
 use iced::widget::{
@@ -146,18 +144,12 @@ impl Application for Example {
     }
 
     fn subscription(&self) -> Subscription<Message> {
-        subscription::events_with(|event, status| {
-            if let event::Status::Captured = status {
+        keyboard::on_key_press(|key_code, modifiers| {
+            if !modifiers.command() {
                 return None;
             }
 
-            match event {
-                Event::Keyboard(keyboard::Event::KeyPressed {
-                    modifiers,
-                    key_code,
-                }) if modifiers.command() => handle_hotkey(key_code),
-                _ => None,
-            }
+            handle_hotkey(key_code)
         })
     }
 
diff --git a/examples/screenshot/src/main.rs b/examples/screenshot/src/main.rs
index 83824535..54446724 100644
--- a/examples/screenshot/src/main.rs
+++ b/examples/screenshot/src/main.rs
@@ -4,9 +4,8 @@ use iced::theme::{Button, Container};
 use iced::widget::{button, column, container, image, row, text, text_input};
 use iced::window::screenshot::{self, Screenshot};
 use iced::{
-    event, executor, keyboard, subscription, Alignment, Application, Command,
-    ContentFit, Element, Event, Length, Rectangle, Renderer, Subscription,
-    Theme,
+    event, executor, keyboard, Alignment, Application, Command, ContentFit,
+    Element, Event, Length, Rectangle, Renderer, Subscription, Theme,
 };
 
 use ::image as img;
@@ -254,7 +253,7 @@ impl Application for Example {
     }
 
     fn subscription(&self) -> Subscription<Self::Message> {
-        subscription::events_with(|event, status| {
+        event::listen_with(|event, status| {
             if let event::Status::Captured = status {
                 return None;
             }
diff --git a/examples/toast/src/main.rs b/examples/toast/src/main.rs
index 42f6c348..47b272a9 100644
--- a/examples/toast/src/main.rs
+++ b/examples/toast/src/main.rs
@@ -1,10 +1,12 @@
+use iced::event::{self, Event};
 use iced::executor;
 use iced::keyboard;
-use iced::subscription::{self, Subscription};
 use iced::widget::{
     self, button, column, container, pick_list, row, slider, text, text_input,
 };
-use iced::{Alignment, Application, Command, Element, Event, Length, Settings};
+use iced::{
+    Alignment, Application, Command, Element, Length, Settings, Subscription,
+};
 
 use toast::{Status, Toast};
 
@@ -57,7 +59,7 @@ impl Application for App {
     }
 
     fn subscription(&self) -> Subscription<Self::Message> {
-        subscription::events().map(Message::Event)
+        event::listen().map(Message::Event)
     }
 
     fn update(&mut self, message: Message) -> Command<Message> {
diff --git a/examples/todos/src/main.rs b/examples/todos/src/main.rs
index 6ad7b4fb..62c17926 100644
--- a/examples/todos/src/main.rs
+++ b/examples/todos/src/main.rs
@@ -1,8 +1,6 @@
 use iced::alignment::{self, Alignment};
-use iced::event::{self, Event};
 use iced::font::{self, Font};
-use iced::keyboard::{self, KeyCode, Modifiers};
-use iced::subscription;
+use iced::keyboard;
 use iced::theme::{self, Theme};
 use iced::widget::{
     self, button, checkbox, column, container, row, scrollable, text,
@@ -52,7 +50,7 @@ enum Message {
     FilterChanged(Filter),
     TaskMessage(usize, TaskMessage),
     TabPressed { shift: bool },
-    ToggleFullscreen(window::Mode),
+    ChangeWindowMode(window::Mode),
 }
 
 impl Application for Todos {
@@ -163,7 +161,7 @@ impl Application for Todos {
                             widget::focus_next()
                         }
                     }
-                    Message::ToggleFullscreen(mode) => {
+                    Message::ChangeWindowMode(mode) => {
                         window::change_mode(mode)
                     }
                     _ => Command::none(),
@@ -262,33 +260,19 @@ impl Application for Todos {
     }
 
     fn subscription(&self) -> Subscription<Message> {
-        subscription::events_with(|event, status| match (event, status) {
-            (
-                Event::Keyboard(keyboard::Event::KeyPressed {
-                    key_code: keyboard::KeyCode::Tab,
-                    modifiers,
-                    ..
+        keyboard::on_key_press(|key_code, modifiers| {
+            match (key_code, modifiers) {
+                (keyboard::KeyCode::Tab, _) => Some(Message::TabPressed {
+                    shift: modifiers.shift(),
                 }),
-                event::Status::Ignored,
-            ) => Some(Message::TabPressed {
-                shift: modifiers.shift(),
-            }),
-            (
-                Event::Keyboard(keyboard::Event::KeyPressed {
-                    key_code,
-                    modifiers: Modifiers::SHIFT,
-                }),
-                event::Status::Ignored,
-            ) => match key_code {
-                KeyCode::Up => {
-                    Some(Message::ToggleFullscreen(window::Mode::Fullscreen))
+                (keyboard::KeyCode::Up, keyboard::Modifiers::SHIFT) => {
+                    Some(Message::ChangeWindowMode(window::Mode::Fullscreen))
                 }
-                KeyCode::Down => {
-                    Some(Message::ToggleFullscreen(window::Mode::Windowed))
+                (keyboard::KeyCode::Down, keyboard::Modifiers::SHIFT) => {
+                    Some(Message::ChangeWindowMode(window::Mode::Windowed))
                 }
                 _ => None,
-            },
-            _ => None,
+            }
         })
     }
 }
diff --git a/examples/url_handler/src/main.rs b/examples/url_handler/src/main.rs
index f63fa06a..bf570123 100644
--- a/examples/url_handler/src/main.rs
+++ b/examples/url_handler/src/main.rs
@@ -1,6 +1,5 @@
-use iced::event::{Event, MacOS, PlatformSpecific};
+use iced::event::{self, Event};
 use iced::executor;
-use iced::subscription;
 use iced::widget::{container, text};
 use iced::{
     Application, Command, Element, Length, Settings, Subscription, Theme,
@@ -37,9 +36,11 @@ impl Application for App {
     fn update(&mut self, message: Message) -> Command<Message> {
         match message {
             Message::EventOccurred(event) => {
-                if let Event::PlatformSpecific(PlatformSpecific::MacOS(
-                    MacOS::ReceivedUrl(url),
-                )) = event
+                if let Event::PlatformSpecific(
+                    event::PlatformSpecific::MacOS(event::MacOS::ReceivedUrl(
+                        url,
+                    )),
+                ) = event
                 {
                     self.url = Some(url);
                 }
@@ -50,7 +51,7 @@ impl Application for App {
     }
 
     fn subscription(&self) -> Subscription<Message> {
-        subscription::events().map(Message::EventOccurred)
+        event::listen().map(Message::EventOccurred)
     }
 
     fn view(&self) -> Element<Message> {
diff --git a/examples/visible_bounds/src/main.rs b/examples/visible_bounds/src/main.rs
index 8b684514..42dfc24c 100644
--- a/examples/visible_bounds/src/main.rs
+++ b/examples/visible_bounds/src/main.rs
@@ -1,14 +1,14 @@
+use iced::event::{self, Event};
 use iced::executor;
 use iced::mouse;
-use iced::subscription::{self, Subscription};
 use iced::theme::{self, Theme};
 use iced::widget::{
     column, container, horizontal_space, row, scrollable, text, vertical_space,
 };
 use iced::window;
 use iced::{
-    Alignment, Application, Color, Command, Element, Event, Font, Length,
-    Point, Rectangle, Settings,
+    Alignment, Application, Color, Command, Element, Font, Length, Point,
+    Rectangle, Settings, Subscription,
 };
 
 pub fn main() -> iced::Result {
@@ -163,7 +163,7 @@ impl Application for Example {
     }
 
     fn subscription(&self) -> Subscription<Message> {
-        subscription::events_with(|event, _| match event {
+        event::listen_with(|event, _| match event {
             Event::Mouse(mouse::Event::CursorMoved { position }) => {
                 Some(Message::MouseMoved(position))
             }
diff --git a/futures/src/event.rs b/futures/src/event.rs
new file mode 100644
index 00000000..214d2d40
--- /dev/null
+++ b/futures/src/event.rs
@@ -0,0 +1,59 @@
+//! Listen to runtime events.
+use crate::core::event::{self, Event};
+use crate::core::window;
+use crate::subscription::{self, Subscription};
+use crate::MaybeSend;
+
+/// Returns a [`Subscription`] to all the ignored runtime events.
+///
+/// This subscription will notify your application of any [`Event`] that was
+/// not captured by any widget.
+pub fn listen() -> Subscription<Event> {
+    listen_with(|event, status| match status {
+        event::Status::Ignored => Some(event),
+        event::Status::Captured => None,
+    })
+}
+
+/// Creates a [`Subscription`] that listens and filters all the runtime events
+/// with the provided function, producing messages accordingly.
+///
+/// This subscription will call the provided function for every [`Event`]
+/// handled by the runtime. If the function:
+///
+/// - Returns `None`, the [`Event`] will be discarded.
+/// - Returns `Some` message, the `Message` will be produced.
+pub fn listen_with<Message>(
+    f: fn(Event, event::Status) -> Option<Message>,
+) -> Subscription<Message>
+where
+    Message: 'static + MaybeSend,
+{
+    #[derive(Hash)]
+    struct EventsWith;
+
+    subscription::filter_map(
+        (EventsWith, f),
+        move |event, status| match event {
+            Event::Window(window::Event::RedrawRequested(_)) => None,
+            _ => f(event, status),
+        },
+    )
+}
+
+/// Creates a [`Subscription`] that produces a message for every runtime event,
+/// including the redraw request events.
+///
+/// **Warning:** This [`Subscription`], if unfiltered, may produce messages in
+/// an infinite loop.
+pub fn listen_raw<Message>(
+    f: fn(Event, event::Status) -> Option<Message>,
+) -> Subscription<Message>
+where
+    Message: 'static + MaybeSend,
+{
+    #[derive(Hash)]
+    struct RawEvents;
+
+    subscription::filter_map((RawEvents, f), f)
+}
diff --git a/futures/src/keyboard.rs b/futures/src/keyboard.rs
new file mode 100644
index 00000000..1ddca0bb
--- /dev/null
+++ b/futures/src/keyboard.rs
@@ -0,0 +1,61 @@
+//! Listen to keyboard events.
+use crate::core;
+use crate::core::keyboard::{Event, KeyCode, Modifiers};
+use crate::subscription::{self, Subscription};
+use crate::MaybeSend;
+
+/// Listens to keyboard key presses and calls the given function
+/// map them into actual messages.
+///
+/// If the function returns `None`, the key press will be simply
+/// ignored.
+pub fn on_key_press<Message>(
+    f: fn(KeyCode, Modifiers) -> Option<Message>,
+) -> Subscription<Message>
+where
+    Message: MaybeSend + 'static,
+{
+    #[derive(Hash)]
+    struct OnKeyPress;
+
+    subscription::filter_map((OnKeyPress, f), move |event, status| {
+        match (event, status) {
+            (
+                core::Event::Keyboard(Event::KeyPressed {
+                    key_code,
+                    modifiers,
+                }),
+                core::event::Status::Ignored,
+            ) => f(key_code, modifiers),
+            _ => None,
+        }
+    })
+}
+
+/// Listens to keyboard key releases and calls the given function
+/// map them into actual messages.
+///
+/// If the function returns `None`, the key release will be simply
+/// ignored.
+pub fn on_key_release<Message>(
+    f: fn(KeyCode, Modifiers) -> Option<Message>,
+) -> Subscription<Message>
+where
+    Message: MaybeSend + 'static,
+{
+    #[derive(Hash)]
+    struct OnKeyPress;
+
+    subscription::filter_map((OnKeyPress, f), move |event, status| {
+        match (event, status) {
+            (
+                core::Event::Keyboard(Event::KeyReleased {
+                    key_code,
+                    modifiers,
+                }),
+                core::event::Status::Ignored,
+            ) => f(key_code, modifiers),
+            _ => None,
+        }
+    })
+}
diff --git a/futures/src/lib.rs b/futures/src/lib.rs
index 34d81e1e..8e75331f 100644
--- a/futures/src/lib.rs
+++ b/futures/src/lib.rs
@@ -24,7 +24,9 @@ mod maybe_send;
 mod runtime;
 
 pub mod backend;
+pub mod event;
 pub mod executor;
+pub mod keyboard;
 pub mod subscription;
 
 pub use executor::Executor;
diff --git a/futures/src/subscription.rs b/futures/src/subscription.rs
index 8f78ce3a..759dd223 100644
--- a/futures/src/subscription.rs
+++ b/futures/src/subscription.rs
@@ -4,7 +4,6 @@ mod tracker;
 pub use tracker::Tracker;
 
 use crate::core::event::{self, Event};
-use crate::core::window;
 use crate::core::Hasher;
 use crate::futures::{Future, Stream};
 use crate::{BoxStream, MaybeSend};
@@ -215,77 +214,6 @@ where
     }
 }
 
-/// Returns a [`Subscription`] to all the ignored runtime events.
-///
-/// This subscription will notify your application of any [`Event`] that was
-/// not captured by any widget.
-pub fn events() -> Subscription<Event> {
-    events_with(|event, status| match status {
-        event::Status::Ignored => Some(event),
-        event::Status::Captured => None,
-    })
-}
-
-/// Returns a [`Subscription`] that filters all the runtime events with the
-/// provided function, producing messages accordingly.
-///
-/// This subscription will call the provided function for every [`Event`]
-/// handled by the runtime. If the function:
-///
-/// - Returns `None`, the [`Event`] will be discarded.
-/// - Returns `Some` message, the `Message` will be produced.
-pub fn events_with<Message>(
-    f: fn(Event, event::Status) -> Option<Message>,
-) -> Subscription<Message>
-where
-    Message: 'static + MaybeSend,
-{
-    #[derive(Hash)]
-    struct EventsWith;
-
-    Subscription::from_recipe(Runner {
-        id: (EventsWith, f),
-        spawn: move |events| {
-            use futures::future;
-            use futures::stream::StreamExt;
-
-            events.filter_map(move |(event, status)| {
-                future::ready(match event {
-                    Event::Window(window::Event::RedrawRequested(_)) => None,
-                    _ => f(event, status),
-                })
-            })
-        },
-    })
-}
-
-/// Returns a [`Subscription`] that produces a message for every runtime event,
-/// including the redraw request events.
-///
-/// **Warning:** This [`Subscription`], if unfiltered, may produce messages in
-/// an infinite loop.
-pub fn raw_events<Message>(
-    f: fn(Event, event::Status) -> Option<Message>,
-) -> Subscription<Message>
-where
-    Message: 'static + MaybeSend,
-{
-    #[derive(Hash)]
-    struct RawEvents;
-
-    Subscription::from_recipe(Runner {
-        id: (RawEvents, f),
-        spawn: move |events| {
-            use futures::future;
-            use futures::stream::StreamExt;
-
-            events.filter_map(move |(event, status)| {
-                future::ready(f(event, status))
-            })
-        },
-    })
-}
-
 /// Returns a [`Subscription`] that will call the given function to create and
 /// asynchronously run the given [`Stream`].
 pub fn run<S, Message>(builder: fn() -> S) -> Subscription<Message>
@@ -338,6 +266,25 @@ where
     )
 }
 
+pub(crate) fn filter_map<I, F, Message>(id: I, f: F) -> Subscription<Message>
+where
+    I: Hash + 'static,
+    F: Fn(Event, event::Status) -> Option<Message> + MaybeSend + 'static,
+    Message: 'static + MaybeSend,
+{
+    Subscription::from_recipe(Runner {
+        id,
+        spawn: |events| {
+            use futures::future;
+            use futures::stream::StreamExt;
+
+            events.filter_map(move |(event, status)| {
+                future::ready(f(event, status))
+            })
+        },
+    })
+}
+
 /// Creates a [`Subscription`] that publishes the events sent from a [`Future`]
 /// to an [`mpsc::Sender`] with the given bounds.
 ///
diff --git a/runtime/src/window.rs b/runtime/src/window.rs
index 5219fbfd..41816967 100644
--- a/runtime/src/window.rs
+++ b/runtime/src/window.rs
@@ -10,7 +10,8 @@ use crate::command::{self, Command};
 use crate::core::time::Instant;
 use crate::core::window::{Event, Icon, Level, Mode, UserAttention};
 use crate::core::Size;
-use crate::futures::subscription::{self, Subscription};
+use crate::futures::event;
+use crate::futures::Subscription;
 
 /// Subscribes to the frames of the window of the running application.
 ///
@@ -21,7 +22,7 @@ use crate::futures::subscription::{self, Subscription};
 /// In any case, this [`Subscription`] is useful to smoothly draw application-driven
 /// animations without missing any frames.
 pub fn frames() -> Subscription<Instant> {
-    subscription::raw_events(|event, _status| match event {
+    event::listen_raw(|event, _status| match event {
         iced_core::Event::Window(Event::RedrawRequested(at)) => Some(at),
         _ => None,
     })
diff --git a/src/lib.rs b/src/lib.rs
index 36f48ba2..840802cc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -187,7 +187,6 @@ pub mod advanced;
 pub use style::theme;
 
 pub use crate::core::alignment;
-pub use crate::core::event;
 pub use crate::core::gradient;
 pub use crate::core::{
     color, Alignment, Background, BorderRadius, Color, ContentFit, Degrees,
@@ -223,9 +222,16 @@ pub mod font {
     pub use crate::runtime::font::*;
 }
 
+pub mod event {
+    //! Handle events of a user interface.
+    pub use crate::core::event::{Event, MacOS, PlatformSpecific, Status};
+    pub use iced_futures::event::{listen, listen_raw, listen_with};
+}
+
 pub mod keyboard {
     //! Listen and react to keyboard events.
     pub use crate::core::keyboard::{Event, KeyCode, Modifiers};
+    pub use iced_futures::keyboard::{on_key_press, on_key_release};
 }
 
 pub mod mouse {
@@ -238,7 +244,7 @@ pub mod mouse {
 pub mod subscription {
     //! Listen to external events in your application.
     pub use iced_futures::subscription::{
-        channel, events, events_with, run, run_with_id, unfold, Subscription,
+        channel, run, run_with_id, unfold, Subscription,
     };
 }