Seregon/StratoSDK

StratoSDK is a framework with a declarative approach similar to Flutter/React, written and designed entirely for Rust.

Rust/27.3 KB/No license
crates/strato-ui-core/src/platform/keyboard.rs
raw
StratoSDK / crates / strato-ui-core / src / platform / keyboard.rs
1//! This module defines types used in the context of keyboard events across platforms. The types
2//! are based on winit types, however, we include them in this module to avoid needing to include
3//! the entirety of winit as a dependency for MacOS.
4 
5use serde::{Deserialize, Serialize};
6 
7// The following types and functions are taken from winit's implementation.
8// We redefine them here to avoid needing to include the entirety of winit as a dependency for MacOS.
9// --------------------------------------------------------------------------------------------------------
10 
11/// Contains the platform-native physical key identifier
12///
13/// The exact values vary from platform to platform (which is part of why this is a per-platform
14/// enum), but the values are primarily tied to the key's physical location on the keyboard.
15///
16/// This enum is primarily used to store raw keycodes when Winit doesn't map a given native
17/// physical key identifier to a meaningful [`KeyCode`] variant. In the presence of identifiers we
18/// haven't mapped for you yet, this lets you use use [`KeyCode`] to:
19///
20/// - Correctly match key press and release events.
21/// - On non-Web platforms, support assigning keybinds to virtually any key through a UI.
22#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
23pub enum NativeKeyCode {
24 Unidentified,
25 /// A macOS "scancode".
26 MacOS(u16),
27 /// A Windows "scancode".
28 Windows(u16),
29 /// An XKB "keycode".
30 Xkb(u32),
31}
32 
33impl std::fmt::Debug for NativeKeyCode {
34 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
35 use NativeKeyCode::{MacOS, Unidentified, Windows, Xkb};
36 let mut debug_tuple;
37 match self {
38 Unidentified => {
39 debug_tuple = f.debug_tuple("Unidentified");
40 }
41 MacOS(code) => {
42 debug_tuple = f.debug_tuple("MacOS");
43 debug_tuple.field(&format_args!("0x{code:04X}"));
44 }
45 Windows(code) => {
46 debug_tuple = f.debug_tuple("Windows");
47 debug_tuple.field(&format_args!("0x{code:04X}"));
48 }
49 Xkb(code) => {
50 debug_tuple = f.debug_tuple("Xkb");
51 debug_tuple.field(&format_args!("0x{code:04X}"));
52 }
53 }
54 debug_tuple.finish()
55 }
56}
57 
58/// Represents the location of a physical key.
59///
60/// This type is a superset of [`KeyCode`], including an [`Unidentified`][Self::Unidentified]
61/// variant.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
63pub enum PhysicalKey {
64 /// A known key code
65 Code(KeyCode),
66 /// This variant is used when the key cannot be translated to a [`KeyCode`]
67 ///
68 /// The native keycode is provided (if available) so you're able to more reliably match
69 /// key-press and key-release events by hashing the [`PhysicalKey`]. It is also possible to use
70 /// this for keybinds for non-standard keys, but such keybinds are tied to a given platform.
71 Unidentified(NativeKeyCode),
72}
73 
74/// Code representing the location of a physical key
75///
76/// This mostly conforms to the UI Events Specification's [`KeyboardEvent.code`] with a few
77/// exceptions:
78/// - The keys that the specification calls "MetaLeft" and "MetaRight" are named "SuperLeft" and
79/// "SuperRight" here.
80/// - The key that the specification calls "Super" is reported as `Unidentified` here.
81///
82/// [`KeyboardEvent.code`]: https://w3c.github.io/uievents-code/#code-value-tables
83#[non_exhaustive]
84#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
85pub enum KeyCode {
86 /// <kbd>`</kbd> on a US keyboard. This is also called a backtick or grave.
87 /// This is the <kbd>半角</kbd>/<kbd>全角</kbd>/<kbd>漢字</kbd>
88 /// (hankaku/zenkaku/kanji) key on Japanese keyboards
89 Backquote,
90 /// Used for both the US <kbd>\\</kbd> (on the 101-key layout) and also for the key
91 /// located between the <kbd>"</kbd> and <kbd>Enter</kbd> keys on row C of the 102-,
92 /// 104- and 106-key layouts.
93 /// Labeled <kbd>#</kbd> on a UK (102) keyboard.
94 Backslash,
95 /// <kbd>[</kbd> on a US keyboard.
96 BracketLeft,
97 /// <kbd>]</kbd> on a US keyboard.
98 BracketRight,
99 /// <kbd>,</kbd> on a US keyboard.
100 Comma,
101 /// <kbd>0</kbd> on a US keyboard.
102 Digit0,
103 /// <kbd>1</kbd> on a US keyboard.
104 Digit1,
105 /// <kbd>2</kbd> on a US keyboard.
106 Digit2,
107 /// <kbd>3</kbd> on a US keyboard.
108 Digit3,
109 /// <kbd>4</kbd> on a US keyboard.
110 Digit4,
111 /// <kbd>5</kbd> on a US keyboard.
112 Digit5,
113 /// <kbd>6</kbd> on a US keyboard.
114 Digit6,
115 /// <kbd>7</kbd> on a US keyboard.
116 Digit7,
117 /// <kbd>8</kbd> on a US keyboard.
118 Digit8,
119 /// <kbd>9</kbd> on a US keyboard.
120 Digit9,
121 /// <kbd>=</kbd> on a US keyboard.
122 Equal,
123 /// Located between the left <kbd>Shift</kbd> and <kbd>Z</kbd> keys.
124 /// Labeled <kbd>\\</kbd> on a UK keyboard.
125 IntlBackslash,
126 /// Located between the <kbd>/</kbd> and right <kbd>Shift</kbd> keys.
127 /// Labeled <kbd>\\</kbd> (ro) on a Japanese keyboard.
128 IntlRo,
129 /// Located between the <kbd>=</kbd> and <kbd>Backspace</kbd> keys.
130 /// Labeled <kbd>¥</kbd> (yen) on a Japanese keyboard. <kbd>\\</kbd> on a
131 /// Russian keyboard.
132 IntlYen,
133 /// <kbd>a</kbd> on a US keyboard.
134 /// Labeled <kbd>q</kbd> on an AZERTY (e.g., French) keyboard.
135 KeyA,
136 /// <kbd>b</kbd> on a US keyboard.
137 KeyB,
138 /// <kbd>c</kbd> on a US keyboard.
139 KeyC,
140 /// <kbd>d</kbd> on a US keyboard.
141 KeyD,
142 /// <kbd>e</kbd> on a US keyboard.
143 KeyE,
144 /// <kbd>f</kbd> on a US keyboard.
145 KeyF,
146 /// <kbd>g</kbd> on a US keyboard.
147 KeyG,
148 /// <kbd>h</kbd> on a US keyboard.
149 KeyH,
150 /// <kbd>i</kbd> on a US keyboard.
151 KeyI,
152 /// <kbd>j</kbd> on a US keyboard.
153 KeyJ,
154 /// <kbd>k</kbd> on a US keyboard.
155 KeyK,
156 /// <kbd>l</kbd> on a US keyboard.
157 KeyL,
158 /// <kbd>m</kbd> on a US keyboard.
159 KeyM,
160 /// <kbd>n</kbd> on a US keyboard.
161 KeyN,
162 /// <kbd>o</kbd> on a US keyboard.
163 KeyO,
164 /// <kbd>p</kbd> on a US keyboard.
165 KeyP,
166 /// <kbd>q</kbd> on a US keyboard.
167 /// Labeled <kbd>a</kbd> on an AZERTY (e.g., French) keyboard.
168 KeyQ,
169 /// <kbd>r</kbd> on a US keyboard.
170 KeyR,
171 /// <kbd>s</kbd> on a US keyboard.
172 KeyS,
173 /// <kbd>t</kbd> on a US keyboard.
174 KeyT,
175 /// <kbd>u</kbd> on a US keyboard.
176 KeyU,
177 /// <kbd>v</kbd> on a US keyboard.
178 KeyV,
179 /// <kbd>w</kbd> on a US keyboard.
180 /// Labeled <kbd>z</kbd> on an AZERTY (e.g., French) keyboard.
181 KeyW,
182 /// <kbd>x</kbd> on a US keyboard.
183 KeyX,
184 /// <kbd>y</kbd> on a US keyboard.
185 /// Labeled <kbd>z</kbd> on a QWERTZ (e.g., German) keyboard.
186 KeyY,
187 /// <kbd>z</kbd> on a US keyboard.
188 /// Labeled <kbd>w</kbd> on an AZERTY (e.g., French) keyboard, and <kbd>y</kbd> on a
189 /// QWERTZ (e.g., German) keyboard.
190 KeyZ,
191 /// <kbd>-</kbd> on a US keyboard.
192 Minus,
193 /// <kbd>.</kbd> on a US keyboard.
194 Period,
195 /// <kbd>'</kbd> on a US keyboard.
196 Quote,
197 /// <kbd>;</kbd> on a US keyboard.
198 Semicolon,
199 /// <kbd>/</kbd> on a US keyboard.
200 Slash,
201 /// <kbd>Alt</kbd>, <kbd>Option</kbd>, or <kbd>⌥</kbd>.
202 AltLeft,
203 /// <kbd>Alt</kbd>, <kbd>Option</kbd>, or <kbd>⌥</kbd>.
204 /// This is labeled <kbd>AltGr</kbd> on many keyboard layouts.
205 AltRight,
206 /// <kbd>Backspace</kbd> or <kbd>⌫</kbd>.
207 /// Labeled <kbd>Delete</kbd> on Apple keyboards.
208 Backspace,
209 /// <kbd>CapsLock</kbd> or <kbd>⇪</kbd>
210 CapsLock,
211 /// The application context menu key, which is typically found between the right
212 /// <kbd>Super</kbd> key and the right <kbd>Control</kbd> key.
213 ContextMenu,
214 /// <kbd>Control</kbd> or <kbd>⌃</kbd>
215 ControlLeft,
216 /// <kbd>Control</kbd> or <kbd>⌃</kbd>
217 ControlRight,
218 /// <kbd>Enter</kbd> or <kbd>↵</kbd>. Labeled <kbd>Return</kbd> on Apple keyboards.
219 Enter,
220 /// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd>, or other OS symbol key.
221 SuperLeft,
222 /// The Windows, <kbd>⌘</kbd>, <kbd>Command</kbd>, or other OS symbol key.
223 SuperRight,
224 /// <kbd>Shift</kbd> or <kbd>⇧</kbd>
225 ShiftLeft,
226 /// <kbd>Shift</kbd> or <kbd>⇧</kbd>
227 ShiftRight,
228 /// <kbd> </kbd> (space)
229 Space,
230 /// <kbd>Tab</kbd> or <kbd>⇥</kbd>
231 Tab,
232 /// Japanese: <kbd>変</kbd> (henkan)
233 Convert,
234 /// Japanese: <kbd>カタカナ</kbd>/<kbd>ひらがな</kbd>/<kbd>ローマ字</kbd>
235 /// (katakana/hiragana/romaji)
236 KanaMode,
237 /// Korean: HangulMode <kbd>한/영</kbd> (han/yeong)
238 ///
239 /// Japanese (Mac keyboard): <kbd>か</kbd> (kana)
240 Lang1,
241 /// Korean: Hanja <kbd>한</kbd> (hanja)
242 ///
243 /// Japanese (Mac keyboard): <kbd>英</kbd> (eisu)
244 Lang2,
245 /// Japanese (word-processing keyboard): Katakana
246 Lang3,
247 /// Japanese (word-processing keyboard): Hiragana
248 Lang4,
249 /// Japanese (word-processing keyboard): Zenkaku/Hankaku
250 Lang5,
251 /// Japanese: <kbd>無変換</kbd> (muhenkan)
252 NonConvert,
253 /// <kbd>⌦</kbd>. The forward delete key.
254 /// Note that on Apple keyboards, the key labelled <kbd>Delete</kbd> on the main part of
255 /// the keyboard is encoded as [`Backspace`].
256 ///
257 /// [`Backspace`]: Self::Backspace
258 Delete,
259 /// <kbd>Page Down</kbd>, <kbd>End</kbd>, or <kbd>↘</kbd>
260 End,
261 /// <kbd>Help</kbd>. Not present on standard PC keyboards.
262 Help,
263 /// <kbd>Home</kbd> or <kbd>↖</kbd>
264 Home,
265 /// <kbd>Insert</kbd> or <kbd>Ins</kbd>. Not present on Apple keyboards.
266 Insert,
267 /// <kbd>Page Down</kbd>, <kbd>PgDn</kbd>, or <kbd>⇟</kbd>
268 PageDown,
269 /// <kbd>Page Up</kbd>, <kbd>PgUp</kbd>, or <kbd>⇞</kbd>
270 PageUp,
271 /// <kbd>↓</kbd>
272 ArrowDown,
273 /// <kbd>←</kbd>
274 ArrowLeft,
275 /// <kbd>→</kbd>
276 ArrowRight,
277 /// <kbd>↑</kbd>
278 ArrowUp,
279 /// On the Mac, this is used for the numpad <kbd>Clear</kbd> key.
280 NumLock,
281 /// <kbd>0 Ins</kbd> on a keyboard. <kbd>0</kbd> on a phone or remote control
282 Numpad0,
283 /// <kbd>1 End</kbd> on a keyboard. <kbd>1</kbd> or <kbd>1 QZ</kbd> on a phone or remote
284 /// control
285 Numpad1,
286 /// <kbd>2 ↓</kbd> on a keyboard. <kbd>2 ABC</kbd> on a phone or remote control
287 Numpad2,
288 /// <kbd>3 PgDn</kbd> on a keyboard. <kbd>3 DEF</kbd> on a phone or remote control
289 Numpad3,
290 /// <kbd>4 ←</kbd> on a keyboard. <kbd>4 GHI</kbd> on a phone or remote control
291 Numpad4,
292 /// <kbd>5</kbd> on a keyboard. <kbd>5 JKL</kbd> on a phone or remote control
293 Numpad5,
294 /// <kbd>6 →</kbd> on a keyboard. <kbd>6 MNO</kbd> on a phone or remote control
295 Numpad6,
296 /// <kbd>7 Home</kbd> on a keyboard. <kbd>7 PQRS</kbd> or <kbd>7 PRS</kbd> on a phone
297 /// or remote control
298 Numpad7,
299 /// <kbd>8 ↑</kbd> on a keyboard. <kbd>8 TUV</kbd> on a phone or remote control
300 Numpad8,
301 /// <kbd>9 PgUp</kbd> on a keyboard. <kbd>9 WXYZ</kbd> or <kbd>9 WXY</kbd> on a phone
302 /// or remote control
303 Numpad9,
304 /// <kbd>+</kbd>
305 NumpadAdd,
306 /// Found on the Microsoft Natural Keyboard.
307 NumpadBackspace,
308 /// <kbd>C</kbd> or <kbd>A</kbd> (All Clear). Also for use with numpads that have a
309 /// <kbd>Clear</kbd> key that is separate from the <kbd>NumLock</kbd> key. On the Mac, the
310 /// numpad <kbd>Clear</kbd> key is encoded as [`NumLock`].
311 ///
312 /// [`NumLock`]: Self::NumLock
313 NumpadClear,
314 /// <kbd>C</kbd> (Clear Entry)
315 NumpadClearEntry,
316 /// <kbd>,</kbd> (thousands separator). For locales where the thousands separator
317 /// is a "." (e.g., Brazil), this key may generate a <kbd>.</kbd>.
318 NumpadComma,
319 /// <kbd>. Del</kbd>. For locales where the decimal separator is "," (e.g.,
320 /// Brazil), this key may generate a <kbd>,</kbd>.
321 NumpadDecimal,
322 /// <kbd>/</kbd>
323 NumpadDivide,
324 NumpadEnter,
325 /// <kbd>=</kbd>
326 NumpadEqual,
327 /// <kbd>#</kbd> on a phone or remote control device. This key is typically found
328 /// below the <kbd>9</kbd> key and to the right of the <kbd>0</kbd> key.
329 NumpadHash,
330 /// <kbd>M</kbd> Add current entry to the value stored in memory.
331 NumpadMemoryAdd,
332 /// <kbd>M</kbd> Clear the value stored in memory.
333 NumpadMemoryClear,
334 /// <kbd>M</kbd> Replace the current entry with the value stored in memory.
335 NumpadMemoryRecall,
336 /// <kbd>M</kbd> Replace the value stored in memory with the current entry.
337 NumpadMemoryStore,
338 /// <kbd>M</kbd> Subtract current entry from the value stored in memory.
339 NumpadMemorySubtract,
340 /// <kbd>*</kbd> on a keyboard. For use with numpads that provide mathematical
341 /// operations (<kbd>+</kbd>, <kbd>-</kbd> <kbd>*</kbd> and <kbd>/</kbd>).
342 ///
343 /// Use `NumpadStar` for the <kbd>*</kbd> key on phones and remote controls.
344 NumpadMultiply,
345 /// <kbd>(</kbd> Found on the Microsoft Natural Keyboard.
346 NumpadParenLeft,
347 /// <kbd>)</kbd> Found on the Microsoft Natural Keyboard.
348 NumpadParenRight,
349 /// <kbd>*</kbd> on a phone or remote control device.
350 ///
351 /// This key is typically found below the <kbd>7</kbd> key and to the left of
352 /// the <kbd>0</kbd> key.
353 ///
354 /// Use <kbd>"NumpadMultiply"</kbd> for the <kbd>*</kbd> key on
355 /// numeric keypads.
356 NumpadStar,
357 /// <kbd>-</kbd>
358 NumpadSubtract,
359 /// <kbd>Esc</kbd> or <kbd>⎋</kbd>
360 Escape,
361 /// <kbd>Fn</kbd> This is typically a hardware key that does not generate a separate code.
362 Fn,
363 /// <kbd>FLock</kbd> or <kbd>FnLock</kbd>. Function Lock key. Found on the Microsoft
364 /// Natural Keyboard.
365 FnLock,
366 /// <kbd>PrtScr SysRq</kbd> or <kbd>Print Screen</kbd>
367 PrintScreen,
368 /// <kbd>Scroll Lock</kbd>
369 ScrollLock,
370 /// <kbd>Pause Break</kbd>
371 Pause,
372 /// Some laptops place this key to the left of the <kbd>↑</kbd> key.
373 ///
374 /// This also the "back" button (triangle) on Android.
375 BrowserBack,
376 BrowserFavorites,
377 /// Some laptops place this key to the right of the <kbd>↑</kbd> key.
378 BrowserForward,
379 /// The "home" button on Android.
380 BrowserHome,
381 BrowserRefresh,
382 BrowserSearch,
383 BrowserStop,
384 /// <kbd>Eject</kbd> or <kbd>⏏</kbd>. This key is placed in the function section on some Apple
385 /// keyboards.
386 Eject,
387 /// Sometimes labelled <kbd>My Computer</kbd> on the keyboard
388 LaunchApp1,
389 /// Sometimes labelled <kbd>Calculator</kbd> on the keyboard
390 LaunchApp2,
391 LaunchMail,
392 MediaPlayPause,
393 MediaSelect,
394 MediaStop,
395 MediaTrackNext,
396 MediaTrackPrevious,
397 /// This key is placed in the function section on some Apple keyboards, replacing the
398 /// <kbd>Eject</kbd> key.
399 Power,
400 Sleep,
401 AudioVolumeDown,
402 AudioVolumeMute,
403 AudioVolumeUp,
404 WakeUp,
405 // Legacy modifier key. Also called "Super" in certain places.
406 Meta,
407 // Legacy modifier key.
408 Hyper,
409 Turbo,
410 Abort,
411 Resume,
412 Suspend,
413 /// Found on Sun’s USB keyboard.
414 Again,
415 /// Found on Sun’s USB keyboard.
416 Copy,
417 /// Found on Sun’s USB keyboard.
418 Cut,
419 /// Found on Sun’s USB keyboard.
420 Find,
421 /// Found on Sun’s USB keyboard.
422 Open,
423 /// Found on Sun’s USB keyboard.
424 Paste,
425 /// Found on Sun’s USB keyboard.
426 Props,
427 /// Found on Sun’s USB keyboard.
428 Select,
429 /// Found on Sun’s USB keyboard.
430 Undo,
431 /// Use for dedicated <kbd>ひらがな</kbd> key found on some Japanese word processing keyboards.
432 Hiragana,
433 /// Use for dedicated <kbd>カタカナ</kbd> key found on some Japanese word processing keyboards.
434 Katakana,
435 /// General-purpose function key.
436 /// Usually found at the top of the keyboard.
437 F1,
438 /// General-purpose function key.
439 /// Usually found at the top of the keyboard.
440 F2,
441 /// General-purpose function key.
442 /// Usually found at the top of the keyboard.
443 F3,
444 /// General-purpose function key.
445 /// Usually found at the top of the keyboard.
446 F4,
447 /// General-purpose function key.
448 /// Usually found at the top of the keyboard.
449 F5,
450 /// General-purpose function key.
451 /// Usually found at the top of the keyboard.
452 F6,
453 /// General-purpose function key.
454 /// Usually found at the top of the keyboard.
455 F7,
456 /// General-purpose function key.
457 /// Usually found at the top of the keyboard.
458 F8,
459 /// General-purpose function key.
460 /// Usually found at the top of the keyboard.
461 F9,
462 /// General-purpose function key.
463 /// Usually found at the top of the keyboard.
464 F10,
465 /// General-purpose function key.
466 /// Usually found at the top of the keyboard.
467 F11,
468 /// General-purpose function key.
469 /// Usually found at the top of the keyboard.
470 F12,
471 /// General-purpose function key.
472 /// Usually found at the top of the keyboard.
473 F13,
474 /// General-purpose function key.
475 /// Usually found at the top of the keyboard.
476 F14,
477 /// General-purpose function key.
478 /// Usually found at the top of the keyboard.
479 F15,
480 /// General-purpose function key.
481 /// Usually found at the top of the keyboard.
482 F16,
483 /// General-purpose function key.
484 /// Usually found at the top of the keyboard.
485 F17,
486 /// General-purpose function key.
487 /// Usually found at the top of the keyboard.
488 F18,
489 /// General-purpose function key.
490 /// Usually found at the top of the keyboard.
491 F19,
492 /// General-purpose function key.
493 /// Usually found at the top of the keyboard.
494 F20,
495 /// General-purpose function key.
496 /// Usually found at the top of the keyboard.
497 F21,
498 /// General-purpose function key.
499 /// Usually found at the top of the keyboard.
500 F22,
501 /// General-purpose function key.
502 /// Usually found at the top of the keyboard.
503 F23,
504 /// General-purpose function key.
505 /// Usually found at the top of the keyboard.
506 F24,
507 /// General-purpose function key.
508 F25,
509 /// General-purpose function key.
510 F26,
511 /// General-purpose function key.
512 F27,
513 /// General-purpose function key.
514 F28,
515 /// General-purpose function key.
516 F29,
517 /// General-purpose function key.
518 F30,
519 /// General-purpose function key.
520 F31,
521 /// General-purpose function key.
522 F32,
523 /// General-purpose function key.
524 F33,
525 /// General-purpose function key.
526 F34,
527 /// General-purpose function key.
528 F35,
529}
530