keyboard_types/
webdriver.rs

1//! Keyboard related WebDriver functionality.
2//!
3//! The low-level [`KeyInputState::dispatch_keydown`] and
4//! [`KeyInputState::dispatch_keyup`] API creates keyboard events
5//! from WebDriver codes. It is used in the *Perform Actions* API.
6//!
7//! ```rust
8//! # extern crate keyboard_types;
9//! # use keyboard_types::*;
10//! # use keyboard_types::webdriver::*;
11//! let mut state = KeyInputState::new();
12//! let mut keyboard_event = state.dispatch_keydown('a');
13//! assert_eq!(keyboard_event.state, KeyState::Down);
14//! assert_eq!(keyboard_event.key, Key::Character("a".to_owned()));
15//! assert_eq!(keyboard_event.code, Code::KeyA);
16//!
17//! // The `\u{E029}` code is the WebDriver id for the Numpad divide key.
18//! keyboard_event = state.dispatch_keydown('\u{E050}');
19//! assert_eq!(keyboard_event.key, Key::Named(NamedKey::Shift));
20//! assert_eq!(keyboard_event.code, Code::ShiftRight);
21//! assert_eq!(keyboard_event.location, Location::Right);
22//!
23//! keyboard_event = state.dispatch_keyup('\u{E050}').expect("key is released");
24//! keyboard_event = state.dispatch_keyup('a').expect("key is released");
25//! ```
26//!
27//! The higher level [`send_keys`] function is used for the *Element Send Keys*
28//! WebDriver API. It accepts a string and returns a sequence of [`KeyboardEvent`]
29//! and [`CompositionEvent`] values.
30//!
31//! ```rust
32//! # extern crate keyboard_types;
33//! # use keyboard_types::*;
34//! # use keyboard_types::webdriver::*;
35//! let events = send_keys("Hello world!\u{E006}");
36//! println!("{:#?}", events);
37//!
38//! let events = send_keys("A\u{0308}");
39//! println!("{:#?}", events);
40//! ```
41//!
42//! Specification: <https://w3c.github.io/webdriver/>
43
44use alloc::borrow::ToOwned;
45use alloc::string::{String, ToString};
46use alloc::vec::Vec;
47use std::collections::HashSet;
48
49use unicode_segmentation::UnicodeSegmentation;
50
51use crate::{first_char, NamedKey};
52use crate::{Code, Key, KeyState, KeyboardEvent, Location, Modifiers};
53use crate::{CompositionEvent, CompositionState};
54
55// Spec: <https://w3c.github.io/webdriver/#keyboard-actions>
56// normalised (sic) as in british spelling
57fn normalised_key_value(raw_key: char) -> Key {
58    match raw_key {
59        '\u{E000}' => Key::Named(NamedKey::Unidentified),
60        '\u{E001}' => Key::Named(NamedKey::Cancel),
61        '\u{E002}' => Key::Named(NamedKey::Help),
62        '\u{E003}' => Key::Named(NamedKey::Backspace),
63        '\u{E004}' => Key::Named(NamedKey::Tab),
64        '\u{E005}' => Key::Named(NamedKey::Clear),
65        // FIXME: spec says "Return"
66        '\u{E006}' => Key::Named(NamedKey::Enter),
67        '\u{E007}' => Key::Named(NamedKey::Enter),
68        '\u{E008}' => Key::Named(NamedKey::Shift),
69        '\u{E009}' => Key::Named(NamedKey::Control),
70        '\u{E00A}' => Key::Named(NamedKey::Alt),
71        '\u{E00B}' => Key::Named(NamedKey::Pause),
72        '\u{E00C}' => Key::Named(NamedKey::Escape),
73        '\u{E00D}' => Key::Character(" ".to_string()),
74        '\u{E00E}' => Key::Named(NamedKey::PageUp),
75        '\u{E00F}' => Key::Named(NamedKey::PageDown),
76        '\u{E010}' => Key::Named(NamedKey::End),
77        '\u{E011}' => Key::Named(NamedKey::Home),
78        '\u{E012}' => Key::Named(NamedKey::ArrowLeft),
79        '\u{E013}' => Key::Named(NamedKey::ArrowUp),
80        '\u{E014}' => Key::Named(NamedKey::ArrowRight),
81        '\u{E015}' => Key::Named(NamedKey::ArrowDown),
82        '\u{E016}' => Key::Named(NamedKey::Insert),
83        '\u{E017}' => Key::Named(NamedKey::Delete),
84        '\u{E018}' => Key::Character(";".to_string()),
85        '\u{E019}' => Key::Character("=".to_string()),
86        '\u{E01A}' => Key::Character("0".to_string()),
87        '\u{E01B}' => Key::Character("1".to_string()),
88        '\u{E01C}' => Key::Character("2".to_string()),
89        '\u{E01D}' => Key::Character("3".to_string()),
90        '\u{E01E}' => Key::Character("4".to_string()),
91        '\u{E01F}' => Key::Character("5".to_string()),
92        '\u{E020}' => Key::Character("6".to_string()),
93        '\u{E021}' => Key::Character("7".to_string()),
94        '\u{E022}' => Key::Character("8".to_string()),
95        '\u{E023}' => Key::Character("9".to_string()),
96        '\u{E024}' => Key::Character("*".to_string()),
97        '\u{E025}' => Key::Character("+".to_string()),
98        '\u{E026}' => Key::Character(",".to_string()),
99        '\u{E027}' => Key::Character("-".to_string()),
100        '\u{E028}' => Key::Character(".".to_string()),
101        '\u{E029}' => Key::Character("/".to_string()),
102        '\u{E031}' => Key::Named(NamedKey::F1),
103        '\u{E032}' => Key::Named(NamedKey::F2),
104        '\u{E033}' => Key::Named(NamedKey::F3),
105        '\u{E034}' => Key::Named(NamedKey::F4),
106        '\u{E035}' => Key::Named(NamedKey::F5),
107        '\u{E036}' => Key::Named(NamedKey::F6),
108        '\u{E037}' => Key::Named(NamedKey::F7),
109        '\u{E038}' => Key::Named(NamedKey::F8),
110        '\u{E039}' => Key::Named(NamedKey::F9),
111        '\u{E03A}' => Key::Named(NamedKey::F10),
112        '\u{E03B}' => Key::Named(NamedKey::F11),
113        '\u{E03C}' => Key::Named(NamedKey::F12),
114        '\u{E03D}' => Key::Named(NamedKey::Meta),
115        '\u{E040}' => Key::Named(NamedKey::ZenkakuHankaku),
116        '\u{E050}' => Key::Named(NamedKey::Shift),
117        '\u{E051}' => Key::Named(NamedKey::Control),
118        '\u{E052}' => Key::Named(NamedKey::Alt),
119        '\u{E053}' => Key::Named(NamedKey::Meta),
120        '\u{E054}' => Key::Named(NamedKey::PageUp),
121        '\u{E055}' => Key::Named(NamedKey::PageDown),
122        '\u{E056}' => Key::Named(NamedKey::End),
123        '\u{E057}' => Key::Named(NamedKey::Home),
124        '\u{E058}' => Key::Named(NamedKey::ArrowLeft),
125        '\u{E059}' => Key::Named(NamedKey::ArrowUp),
126        '\u{E05A}' => Key::Named(NamedKey::ArrowRight),
127        '\u{E05B}' => Key::Named(NamedKey::ArrowDown),
128        '\u{E05C}' => Key::Named(NamedKey::Insert),
129        '\u{E05D}' => Key::Named(NamedKey::Delete),
130        _ => Key::Character(raw_key.to_string()),
131    }
132}
133
134/// Spec: <https://w3c.github.io/webdriver/#dfn-code>
135fn code(raw_key: char) -> Code {
136    match raw_key {
137        '`' | '~' => Code::Backquote,
138        '\\' | '|' => Code::Backslash,
139        '\u{E003}' => Code::Backspace,
140        '[' | '{' => Code::BracketLeft,
141        ']' | '}' => Code::BracketRight,
142        ',' | '<' => Code::Comma,
143        '0' | ')' => Code::Digit0,
144        '1' | '!' => Code::Digit1,
145        '2' | '@' => Code::Digit2,
146        '3' | '#' => Code::Digit3,
147        '4' | '$' => Code::Digit4,
148        '5' | '%' => Code::Digit5,
149        '6' | '^' => Code::Digit6,
150        '7' | '&' => Code::Digit7,
151        '8' | '*' => Code::Digit8,
152        '9' | '(' => Code::Digit9,
153        '=' | '+' => Code::Equal,
154        // FIXME: spec has '<' | '>' => Code::IntlBackslash,
155        'a' | 'A' => Code::KeyA,
156        'b' | 'B' => Code::KeyB,
157        'c' | 'C' => Code::KeyC,
158        'd' | 'D' => Code::KeyD,
159        'e' | 'E' => Code::KeyE,
160        'f' | 'F' => Code::KeyF,
161        'g' | 'G' => Code::KeyG,
162        'h' | 'H' => Code::KeyH,
163        'i' | 'I' => Code::KeyI,
164        'j' | 'J' => Code::KeyJ,
165        'k' | 'K' => Code::KeyK,
166        'l' | 'L' => Code::KeyL,
167        'm' | 'M' => Code::KeyM,
168        'n' | 'N' => Code::KeyN,
169        'o' | 'O' => Code::KeyO,
170        'p' | 'P' => Code::KeyP,
171        'q' | 'Q' => Code::KeyQ,
172        'r' | 'R' => Code::KeyR,
173        's' | 'S' => Code::KeyS,
174        't' | 'T' => Code::KeyT,
175        'u' | 'U' => Code::KeyU,
176        'v' | 'V' => Code::KeyV,
177        'w' | 'W' => Code::KeyW,
178        'x' | 'X' => Code::KeyX,
179        'y' | 'Y' => Code::KeyY,
180        'z' | 'Z' => Code::KeyZ,
181        '-' | '_' => Code::Minus,
182        '.' | '>' => Code::Period,
183        '\'' | '"' => Code::Quote,
184        ';' | ':' => Code::Semicolon,
185        '/' | '?' => Code::Slash,
186        '\u{E00A}' => Code::AltLeft,
187        '\u{E052}' => Code::AltRight,
188        '\u{E009}' => Code::ControlLeft,
189        '\u{E051}' => Code::ControlRight,
190        '\u{E006}' => Code::Enter,
191        // FIXME: spec says "OSLeft"
192        '\u{E03D}' => Code::MetaLeft,
193        // FIXME: spec says "OSRight"
194        '\u{E053}' => Code::MetaRight,
195        '\u{E008}' => Code::ShiftLeft,
196        '\u{E050}' => Code::ShiftRight,
197        ' ' | '\u{E00D}' => Code::Space,
198        '\u{E004}' => Code::Tab,
199        '\u{E017}' => Code::Delete,
200        '\u{E010}' => Code::End,
201        '\u{E002}' => Code::Help,
202        '\u{E011}' => Code::Home,
203        '\u{E016}' => Code::Insert,
204        // FIXME: spec says '\u{E01E}' => Code::PageDown, which is Numpad 4
205        '\u{E00F}' => Code::PageDown,
206        // FIXME: spec says '\u{E01F}' => Code::PageUp, which is Numpad 5
207        '\u{E00E}' => Code::PageUp,
208        '\u{E015}' => Code::ArrowDown,
209        '\u{E012}' => Code::ArrowLeft,
210        '\u{E014}' => Code::ArrowRight,
211        '\u{E013}' => Code::ArrowUp,
212        '\u{E00C}' => Code::Escape,
213        '\u{E031}' => Code::F1,
214        '\u{E032}' => Code::F2,
215        '\u{E033}' => Code::F3,
216        '\u{E034}' => Code::F4,
217        '\u{E035}' => Code::F5,
218        '\u{E036}' => Code::F6,
219        '\u{E037}' => Code::F7,
220        '\u{E038}' => Code::F8,
221        '\u{E039}' => Code::F9,
222        '\u{E03A}' => Code::F10,
223        '\u{E03B}' => Code::F11,
224        '\u{E03C}' => Code::F12,
225        '\u{E01A}' | '\u{E05C}' => Code::Numpad0,
226        '\u{E01B}' | '\u{E056}' => Code::Numpad1,
227        '\u{E01C}' | '\u{E05B}' => Code::Numpad2,
228        '\u{E01D}' | '\u{E055}' => Code::Numpad3,
229        '\u{E01E}' | '\u{E058}' => Code::Numpad4,
230        '\u{E01F}' => Code::Numpad5,
231        '\u{E020}' | '\u{E05A}' => Code::Numpad6,
232        '\u{E021}' | '\u{E057}' => Code::Numpad7,
233        '\u{E022}' | '\u{E059}' => Code::Numpad8,
234        '\u{E023}' | '\u{E054}' => Code::Numpad9,
235        // FIXME: spec says uE024
236        '\u{E025}' => Code::NumpadAdd,
237        '\u{E026}' => Code::NumpadComma,
238        '\u{E028}' | '\u{E05D}' => Code::NumpadDecimal,
239        '\u{E029}' => Code::NumpadDivide,
240        '\u{E007}' => Code::NumpadEnter,
241        '\u{E024}' => Code::NumpadMultiply,
242        // FIXME: spec says uE026
243        '\u{E027}' => Code::NumpadSubtract,
244        _ => Code::Unidentified,
245    }
246}
247
248fn is_shifted_character(raw_key: char) -> bool {
249    matches!(
250        raw_key,
251        '~' | '|'
252            | '{'
253            | '}'
254            | '<'
255            | ')'
256            | '!'
257            | '@'
258            | '#'
259            | '$'
260            | '%'
261            | '^'
262            | '&'
263            | '*'
264            | '('
265            | '+'
266            | '>'
267            | '_'
268            | '\"'
269            | ':'
270            | '?'
271            | '\u{E00D}'
272            | '\u{E05C}'
273            | '\u{E056}'
274            | '\u{E05B}'
275            | '\u{E055}'
276            | '\u{E058}'
277            | '\u{E05A}'
278            | '\u{E057}'
279            | '\u{E059}'
280            | '\u{E054}'
281            | '\u{E05D}'
282            | 'A'..='Z'
283    )
284}
285
286fn key_location(raw_key: char) -> Location {
287    match raw_key {
288        '\u{E007}'..='\u{E00A}' => Location::Left,
289        '\u{E01A}'..='\u{E029}' => Location::Numpad,
290        '\u{E03D}' => Location::Left,
291        '\u{E050}'..='\u{E053}' => Location::Right,
292        '\u{E054}'..='\u{E05D}' => Location::Numpad,
293        _ => Location::Standard,
294    }
295}
296
297fn get_modifier(key: &Key) -> Modifiers {
298    match key {
299        Key::Named(NamedKey::Alt) => Modifiers::ALT,
300        Key::Named(NamedKey::Shift) => Modifiers::SHIFT,
301        Key::Named(NamedKey::Control) => Modifiers::CONTROL,
302        Key::Named(NamedKey::Meta) => Modifiers::META,
303        _ => Modifiers::empty(),
304    }
305}
306
307/// Store pressed keys and modifiers.
308///
309/// Spec: <https://w3c.github.io/webdriver/#dfn-key-input-state>
310#[derive(Clone, Debug, Default)]
311#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
312pub struct KeyInputState {
313    pressed: HashSet<Key>,
314    modifiers: Modifiers,
315}
316
317impl KeyInputState {
318    /// New state without any keys or modifiers pressed.
319    ///
320    /// Same as the default value.
321    pub fn new() -> KeyInputState {
322        KeyInputState::default()
323    }
324
325    /// Get a keyboard-keydown event from a WebDriver key value.
326    ///
327    /// Stores that the key is pressed in the state object.
328    ///
329    /// The input cancel list is not implemented here but can be emulated
330    /// by adding the `raw_key` value with a `keyUp` action to a list
331    /// before executing this function.
332    ///
333    /// Specification: <https://w3c.github.io/webdriver/#dfn-dispatch-a-keydown-action>
334    pub fn dispatch_keydown(&mut self, raw_key: char) -> KeyboardEvent {
335        let key = normalised_key_value(raw_key);
336        let repeat = self.pressed.contains(&key);
337        let code = code(raw_key);
338        let location = key_location(raw_key);
339        self.modifiers.insert(get_modifier(&key));
340        self.pressed.insert(key.clone());
341        KeyboardEvent {
342            state: KeyState::Down,
343            key,
344            code,
345            location,
346            modifiers: self.modifiers,
347            repeat,
348            is_composing: false,
349        }
350    }
351
352    /// Get a keyboard-keyup event from a WebDriver key value.
353    ///
354    /// Updates state. Returns `None` if the key is not listed as pressed.
355    ///
356    /// Specification: <https://w3c.github.io/webdriver/#dfn-dispatch-a-keyup-action>
357    pub fn dispatch_keyup(&mut self, raw_key: char) -> Option<KeyboardEvent> {
358        let key = normalised_key_value(raw_key);
359        if !self.pressed.contains(&key) {
360            return None;
361        }
362        let code = code(raw_key);
363        let location = key_location(raw_key);
364        self.modifiers.remove(get_modifier(&key));
365        self.pressed.remove(&key);
366        Some(KeyboardEvent {
367            state: KeyState::Up,
368            key,
369            code,
370            location,
371            modifiers: self.modifiers,
372            repeat: false,
373            is_composing: false,
374        })
375    }
376
377    fn clear(&mut self, undo_actions: &mut HashSet<char>, result: &mut Vec<Event>) {
378        let mut actions: Vec<_> = undo_actions.drain().collect();
379        actions.sort_unstable();
380        for action in actions {
381            result.push(self.dispatch_keyup(action).unwrap().into());
382        }
383        assert!(undo_actions.is_empty());
384    }
385
386    fn dispatch_typeable(&mut self, text: &mut String, result: &mut Vec<Event>) {
387        for character in text.chars() {
388            let shifted = self.modifiers.contains(Modifiers::SHIFT);
389            if is_shifted_character(character) && !shifted {
390                // dispatch left shift down
391                result.push(self.dispatch_keydown('\u{E008}').into());
392            }
393            if !is_shifted_character(character) && shifted {
394                // dispatch left shift up
395                result.push(self.dispatch_keyup('\u{E008}').unwrap().into());
396            }
397            result.push(self.dispatch_keydown(character).into());
398            result.push(self.dispatch_keyup(character).unwrap().into());
399        }
400        text.clear();
401    }
402}
403
404/// Either a [`KeyboardEvent`] or a [`CompositionEvent`].
405///
406/// Returned by the [`send_keys`] function.
407#[derive(Clone, Eq, PartialEq, Hash, Debug, PartialOrd, Ord)]
408#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
409pub enum Event {
410    Keyboard(KeyboardEvent),
411    Composition(CompositionEvent),
412}
413
414impl From<KeyboardEvent> for Event {
415    fn from(v: KeyboardEvent) -> Event {
416        Event::Keyboard(v)
417    }
418}
419
420impl From<CompositionEvent> for Event {
421    fn from(v: CompositionEvent) -> Event {
422        Event::Composition(v)
423    }
424}
425
426/// Compute the events resulting from a WebDriver *Element Send Keys* command.
427///
428/// Spec: <https://w3c.github.io/webdriver/#element-send-keys>
429pub fn send_keys(text: &str) -> Vec<Event> {
430    #[allow(deprecated)]
431    fn is_modifier(text: &str) -> bool {
432        if text.chars().count() != 1 {
433            return false;
434        }
435        // values from <https://www.w3.org/TR/uievents-key/#keys-modifier>
436        matches!(
437            normalised_key_value(first_char(text)),
438            Key::Named(
439                NamedKey::Alt
440                    | NamedKey::AltGraph
441                    | NamedKey::CapsLock
442                    | NamedKey::Control
443                    | NamedKey::Fn
444                    | NamedKey::FnLock
445                    | NamedKey::Meta
446                    | NamedKey::NumLock
447                    | NamedKey::ScrollLock
448                    | NamedKey::Shift
449                    | NamedKey::Symbol
450                    | NamedKey::SymbolLock
451                    | NamedKey::Hyper
452                    | NamedKey::Super
453            )
454        )
455    }
456
457    /// Spec: <https://w3c.github.io/webdriver/#dfn-typeable>
458    fn is_typeable(text: &str) -> bool {
459        text.chars().count() == 1
460    }
461
462    let mut result = Vec::new();
463    let mut typeable_text = String::new();
464    let mut state = KeyInputState::new();
465    let mut undo_actions = HashSet::new();
466    for cluster in UnicodeSegmentation::graphemes(text, true) {
467        match cluster {
468            "\u{E000}" => {
469                state.dispatch_typeable(&mut typeable_text, &mut result);
470                state.clear(&mut undo_actions, &mut result);
471            }
472            s if is_modifier(s) => {
473                state.dispatch_typeable(&mut typeable_text, &mut result);
474                let raw_modifier = first_char(s);
475                result.push(state.dispatch_keydown(raw_modifier).into());
476                undo_actions.insert(raw_modifier);
477            }
478            s if is_typeable(s) => typeable_text.push_str(s),
479            s => {
480                state.dispatch_typeable(&mut typeable_text, &mut result);
481                // FIXME: Spec says undefined instead of empty string
482                result.push(
483                    CompositionEvent {
484                        state: CompositionState::Start,
485                        data: String::new(),
486                    }
487                    .into(),
488                );
489                result.push(
490                    CompositionEvent {
491                        state: CompositionState::Update,
492                        data: s.to_owned(),
493                    }
494                    .into(),
495                );
496                result.push(
497                    CompositionEvent {
498                        state: CompositionState::End,
499                        data: s.to_owned(),
500                    }
501                    .into(),
502                );
503            }
504        }
505    }
506    state.dispatch_typeable(&mut typeable_text, &mut result);
507    state.clear(&mut undo_actions, &mut result);
508    result
509}
keyboard_types/webdriver.rs

keyboard_types/
webdriver.rs
