zng_wgt_input/
keyboard.rs

Help
1//! Keyboard events, [`on_key_down`](fn@on_key_down), [`on_key_up`](fn@on_key_up) and more.
2//!
3//! These events are low level and directly tied to a keyboard device.
4//! Before using them review the [`gesture`](super::gesture) properties, in particular
5//! the [`click_shortcut`](fn@super::gesture::click_shortcut) property.
6
7use zng_ext_input::keyboard::{KEY_INPUT_EVENT, KeyInputArgs, KeyState};
8use zng_wgt::prelude::*;
9
10event_property! {
11    /// Event fired when a keyboard key is pressed or released and the widget is enabled.
12    ///
13    /// # Route
14    ///
15    /// The event is raised in the [keyboard focused](crate::properties::is_focused)
16    /// widget and then each parent up to the root. If propagation stop
17    /// is requested the event is not notified further. If the widget is disabled or blocked the event is not notified.
18    ///
19    /// This route is also called *bubbling*.
20    ///
21    /// # Keys
22    ///
23    /// Any key press/release generates a key input event, including keys codes that don't map
24    /// to any virtual key, see [`KeyInputArgs`] for more details.
25    ///
26    /// For key combinations consider using a [`click_shortcut`] with a click handler.
27    ///
28    /// [`click_shortcut`]: fn@crate::gesture::click_shortcut
29    ///
30    /// # Underlying Event
31    ///
32    /// This event property uses the [`KEY_INPUT_EVENT`] that is included in the default app.
33    ///
34    /// [`KeyInputArgs`]: zng_ext_input::keyboard::KeyInputArgs
35    /// [`KEY_INPUT_EVENT`]: zng_ext_input::keyboard::KEY_INPUT_EVENT
36    pub fn key_input {
37        event: KEY_INPUT_EVENT,
38        args: KeyInputArgs,
39        filter: |args| args.is_enabled(WIDGET.id()),
40    }
41
42    /// Event fired when a keyboard key is pressed or released and the widget is disabled.
43    ///
44    /// # Route
45    ///
46    /// The event is raised in the [keyboard focused](crate::properties::is_focused)
47    /// widget and then each parent up to the root. If propagation stop
48    /// is requested the event is not notified further. If the widget is enabled or blocked the event is not notified.
49    ///
50    /// This route is also called *bubbling*.
51    ///
52    /// # Keys
53    ///
54    /// Any key press/release generates a key input event, including keys that don't map
55    /// to any virtual key, see [`KeyInputArgs`] for more details.
56    ///
57    /// For key combinations consider using a [`click_shortcut`] with a click handler.
58    ///
59    /// [`click_shortcut`]: fn@crate::gesture::click_shortcut
60    ///
61    /// # Underlying Event
62    ///
63    /// This event property uses the [`KEY_INPUT_EVENT`] that is included in the default app.
64    ///
65    /// [`KeyInputArgs`]: zng_ext_input::keyboard::KeyInputArgs
66    /// [`KEY_INPUT_EVENT`]: zng_ext_input::keyboard::KEY_INPUT_EVENT
67    pub fn disabled_key_input {
68        event: KEY_INPUT_EVENT,
69        args: KeyInputArgs,
70        filter: |args| args.is_disabled(WIDGET.id()),
71    }
72
73    /// Event fired when a keyboard key is pressed and the widget is enabled.
74    ///
75    /// # Route
76    ///
77    /// The event is raised in the [keyboard focused](crate::properties::is_focused)
78    /// widget and then each parent up to the root. If propagation stop
79    /// is requested the event is not notified further. If the widget is disabled or blocked the event is not notified.
80    ///
81    /// This route is also called *bubbling*.
82    ///
83    /// # Keys
84    ///
85    /// Any key press generates a key down event, including keys that don't map to any virtual key, see [`KeyInputArgs`]
86    /// for more details.
87    ///
88    /// For key combinations consider using a [`click_shortcut`] with a click handler.
89    ///
90    /// [`click_shortcut`]: fn@crate::gesture::click_shortcut
91    ///
92    /// # Underlying Event
93    ///
94    /// This event property uses the [`KEY_INPUT_EVENT`] that is included in the default app.
95    ///
96    /// [`KeyInputArgs`]: zng_ext_input::keyboard::KeyInputArgs
97    /// [`KEY_INPUT_EVENT`]: zng_ext_input::keyboard::KEY_INPUT_EVENT
98    pub fn key_down {
99        event: KEY_INPUT_EVENT,
100        args: KeyInputArgs,
101        filter: |args| args.state == KeyState::Pressed && args.is_enabled(WIDGET.id()),
102    }
103
104    /// Event fired when a keyboard key is released and the widget is enabled.
105    ///
106    /// # Route
107    ///
108    /// The event is raised in the [keyboard focused](crate::properties::is_focused)
109    /// widget and then each parent up to the root. If propagation stop
110    /// is requested the event is not notified further. If the widget is disabled or blocked the event is not notified.
111    ///
112    /// This route is also called *bubbling*.
113    ///
114    /// # Keys
115    ///
116    /// Any key release generates a key up event, including keys that don't map to any virtual key, see [`KeyInputArgs`]
117    /// for more details.
118    /// For key combinations consider using a [`click_shortcut`] with a click handler.
119    ///
120    /// [`click_shortcut`]: fn@crate::gesture::click_shortcut
121    ///
122    /// # Underlying Event
123    ///
124    /// This event property uses the [`KEY_INPUT_EVENT`] that is included in the default app.
125    ///
126    /// [`KeyInputArgs`]: zng_ext_input::keyboard::KeyInputArgs
127    /// [`KEY_INPUT_EVENT`]: zng_ext_input::keyboard::KEY_INPUT_EVENT
128    pub fn key_up {
129        event: KEY_INPUT_EVENT,
130        args: KeyInputArgs,
131        filter: |args| args.state == KeyState::Released && args.is_enabled(WIDGET.id()),
132    }
133}
zng_wgt_input/keyboard.rs

zng_wgt_input/
keyboard.rs
