1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
use std::sync::Arc;
use super::{EditCommand, EventControl, NavigationCommand};
use crate::core::NodeId;
#[derive(Clone)]
pub struct KeyboardEvent {
pub key: String,
pub code: String,
pub shift: bool,
pub ctrl: bool,
pub alt: bool,
pub meta: bool,
pub target_id: NodeId,
/// Whether a text input holds keyboard focus when this event fires.
/// `on_key_down` handlers run before the focused input consumes the key,
/// so global shortcuts should check this and step aside while the user is
/// typing — the input's own editing takes the key otherwise. An app's own
/// undo, redo, copy and paste are no shortcuts to check for: they are
/// `on_undo`, `on_redo`, `on_copy` and `on_paste` handlers, which a focused
/// input's own editing goes before ([`edit_command`](Self::edit_command)).
pub text_input_focused: bool,
/// Whether this key belongs to an input method (IME) composition, like the
/// DOM's `isComposing`.
///
/// The keys the input method takes never arrive as presses: Windows
/// reports them as `Process` (the `Enter` that confirms a composition
/// included) and macOS not at all, so `on_key_down` handlers and lurq's own
/// key handling do not see them. A press that does arrive while a
/// composition is shown, a key the input method passed on, has this set,
/// and lurq handles it as usual, except an `Enter`: no lurq default (form
/// submit, button or select activation, newline, blur) acts on it. A
/// handler that sends on `Enter` can skip it the same way. Releases of the
/// input method's keys reach `on_key_up` handlers with this set. It is also
/// set on the event a committed composition passes to `on_input` handlers
/// (`TextInputEvent::keyboard`), whose `key` is the committed text.
pub composing: bool,
/// Whether the keyboard's focus is on the node whose handler is being
/// called, or on a node inside it. A key event reaches every node's
/// `on_key_down`, focused or not: a handler that acts only for what has the
/// focus (an item of a menu opening its submenu on Right) checks this.
pub focus_within: bool,
/// Whether what has the keyboard's focus does a thing of its own with Enter: a button (which it presses), a link
/// (which it follows), a select, or a text input of several lines (where it starts a line). A handler that gives
/// Enter a meaning of its own around them, as a dialog that confirms on it, steps aside where this is set. A
/// text input of one line is not one: Enter there submits a form at most.
pub focus_takes_enter: bool,
pub(crate) control: EventControl,
}
impl KeyboardEvent {
pub fn new(
key: impl Into<String>,
code: impl Into<String>,
shift: bool,
ctrl: bool,
alt: bool,
meta: bool,
target_id: NodeId,
) -> Self {
Self {
key: key.into(),
code: code.into(),
shift,
ctrl,
alt,
meta,
target_id,
text_input_focused: false,
composing: false,
focus_within: false,
focus_takes_enter: false,
control: EventControl::new(),
}
}
/// The command of editing the key is, if it is one, on the platform lurq is built for. Never with Alt held. With
/// the shortcut key (Ctrl, or Command on macOS and iOS): Z is [`EditCommand::Undo`] and Shift+Z
/// [`EditCommand::Redo`], as Y without Shift is except on Apple's platforms; X is [`EditCommand::Cut`], C
/// [`EditCommand::Copy`] and V [`EditCommand::Paste`], with Shift or without; A without Shift is
/// [`EditCommand::SelectAll`]. Ctrl+Insert is a copy, Shift+Insert a paste and Shift+Delete a cut. A letter is
/// read as the key says it where it is a Latin one, and by the key's place where it is another (in a Ukrainian
/// layout Z says "я" and C "с"), so the keys work in every layout.
///
/// This is the one place lurq knows these keys: lurq runs the command on what has the focus (`on_undo`,
/// `on_redo`, `on_select_all`, `on_copy`, `on_paste`), and a component never matches them itself.
pub fn edit_command(&self) -> Option<EditCommand> {
EditCommand::of_key(self)
}
/// Going back or forward, if the key is one, on the platform lurq is built for: Alt+← is
/// [`NavigationCommand::Back`] and Alt+→ [`NavigationCommand::Forward`], or Cmd+[ and Cmd+] on Apple's platforms,
/// where Option and an arrow move the caret by a word. A bracket is read as the key says it, and by the key's place
/// where it says a letter of another alphabet. A keyboard's own Back and Forward keys, and Android's back, are the
/// commands on every platform.
///
/// This is the one place lurq knows these keys: lurq runs the command on what has the focus (`on_history_back`,
/// `on_history_forward`, then the router), and a component never matches them itself. A text input does not take
/// Alt and an arrow on Windows and Linux (its word moves are Ctrl's), so they go back in it too, as in a browser.
pub fn navigation_command(&self) -> Option<NavigationCommand> {
NavigationCommand::of_key(self)
}
pub fn prevent_default(&self) {
self.control.prevent_default();
}
pub fn default_prevented(&self) -> bool {
self.control.default_prevented()
}
pub fn stop_propagation(&self) {
self.control.stop_propagation();
}
pub fn propagation_stopped(&self) -> bool {
self.control.propagation_stopped()
}
pub fn stop_immediate_propagation(&self) {
self.control.stop_immediate_propagation();
}
pub fn immediate_propagation_stopped(&self) -> bool {
self.control.immediate_propagation_stopped()
}
/// Moves the focus, once this key's handlers have run and what they changed is rendered, to the element of the
/// [focus group](crate::node::FocusGroup) around the focused element whose key (`.key(..)`) is `key`, as the
/// group's arrows move it: from the keyboard, so that it shows its ring, and into view. The key's default is
/// prevented, so the group does not move the focus as well. For a group whose elements are reached by what the app
/// knows of them and not by their order: a calendar's day a week on, which may be in the month the key shows next.
/// Nothing moves where the group is not there after the render, or has no element of that key that takes the
/// focus. The last request of a key's handlers wins.
///
/// ```
/// use lurq::{app::events::KeyboardEvent, components::{Button, Row}, node::FocusGroup};
///
/// // Each day says where the keys take the focus from it: Right to the next day, by its key.
/// let day = |n: u32| {
/// Button::new(&n.to_string()).tab_index(0).key(format!("day-{n}")).on_key_down(move |event: KeyboardEvent| {
/// if event.focus_within && event.key == "ArrowRight" {
/// event.focus_key(format!("day-{}", n + 1));
/// }
/// })
/// };
/// let week = Row::new().focus_group(FocusGroup::horizontal().one_stop(true)).child(day(1)).child(day(2));
/// ```
pub fn focus_key(&self, key: impl Into<Arc<str>>) {
self.control.prevent_default();
self.control.request_focus_key(key.into());
}
}