Add `KeyString`?

[madsmtm]

Should we add a type KeyString that could implement the restrictions in the spec?

This would allow Key::Character to be fully restricted in the set of values it can have, to avoid e.g. Key::Character("Shift") or Key::Character("\t").

[madsmtm]

Just noting it down as an idea, not sure I like it myself.

[pyfisch]

A key string is a string containing a 0 or 1 non-control characters ("base" characters) followed by 0 or more combining characters. The string MUST be in Normalized Form C (NFC) as described in [UAX15].

This basically requires the crate to depend on the Unicode database to check which classes characters belong to and to construct the NFC. I don't this is needed as the key string is usually provided by the operating system (or browser) and hopefully follows these rules.

[madsmtm]

So, the split between Key and NamedKey I introduced in #50 is kinda grating on me, the extra indirection is annoying when you actually want to match on it.

Winit's Key is defined as:

pub enum Key<Str = SmolStr> {
    Named(NamedKey),
    Character(Str),
    Unidentified(NativeKey),
    Dead(Option<char>),
}

The Key::Dead should probably be handled as composition events, so the only real issue is the key strings, and the extra data on unidentified keys (which is important for supporting unknown layouts etc.).

---

Even more annoying is that you can't pattern-match on String, Box<str>, SmolStr etc., which makes this harder to use for the thing that it's going to be used for quite often, which is inside Winit. This sentiment is also somewhat shared in #82, and has also been discussed at length in the issues linked from #50.

Winit tries to sidestep this by providing LogicalKey::as_str, which yields LogicalKey<&str>:

match key.as_str() {
    LogicalKey::Character(" ") => println!("space"),
    LogicalKey::Named(NamedKey::Backspace) => println!("backspace"),
    _ => {},
}

It doesn't really compose very well though, e.g. larger matches needs to use if guards just to check the key:

match event {
    KeyEvent { logical_key, state: KeyState::Down, .. } if matches!(logical_key.as_str(), LogicalKey::Character(" ")) => println!("pressed space"),
    // OR
    KeyEvent { logical_key: LogicalKey::Character(s), state: KeyState::Down, .. } if s == " " => println!("pressed space"),
    _ => {}
}

[madsmtm]

An idea to improve this could be to do something like:

enum Key<S, U = ()> {
    /// A single-character key string.
    ///
    /// Invariant: Must not be a non-control character.
    Character(char),
    /// A full key string.
    ///
    /// Invariants:
    /// - First character must be a non-control character.
    /// - Remaining characters must be combining characters.
    /// - Must be at least 2 unicode characters long.
    String(S),
    Alt,
    AltGraph,
    Backspace,
    CapsLock,
    // ...
    /// An unidentified key.
    ///
    /// May carry additional data about the key.
    Unidentified(U),
}

impl<S, U> Key<S, U> {
    pub fn string_as_str(&self) -> Key<&str, U>
    where
        S: AsRef<str>,
        U: Copy,
    {
        match self {
            Self::String(s) => Key::String(s.as_ref()),
            key => todo!(), // Might need to be implemented using a macro.
        }
    }

    pub fn without_unidentified_data(self) -> Key<S, ()> {
        match self {
            Self::Unidentified(_data) => Self::Unidentified(()),
            key => todo!(),
        }
    }

    // And similiar such helpers
}

This would allow:

• Making matching easy in the common case as a consumer of e.g. Winit, including easy handling of "Space" and simple characters like the ASCII "A", while still supporting more complex keys.

  match event {
      KeyEvent { state: KeyState::Down, logical_key: LogicalKey::Character(' '), .. } => println!("pressed space"),
      KeyEvent { state: KeyState::Down, logical_key: LogicalKey::Backspace, .. } => println!("pressed backspace"),
      KeyEvent { state: KeyState::Down, key_without_modifiers: LogicalKey::Character('a'), .. } => println!("pressed A key"),
      KeyEvent { state: KeyState::Down, logical_key: LogicalKey::String(s), .. } if s == "ḍ̇" => println!("pressed key with combining character"),
      _ => {}
  }

• Libraries like masonry or egui could be made to handle a key from an arbitrary source, while only depending on keyboard-types:

  fn update_textbox_value<S: AsRef<str>, U>(value: &mut String, key: Key<S, U>) {
      match key {
          Key::Character(c) => value.push(c),
          Key::String(s) => value.push_str(s.as_ref()),
          Key::Backspace => value.pop(),
          _ => todo!(),
      }
  }

• For the people that don't produce/consume full key strings, the memory footprint can be reduced to just 4 bytes by using Key<!>.

A drawback is that construction requires a bit more work, as you have to specify the first type parameter (seems to be so regardless of whether both type parameters have a default, that seems like a bug in the compiler though?):

let key: Key<String> = Key::Backspace;
// Doesn't work, needs the type to be specified.
// let key = Key::Backspace;

This issue can be alleviated with a type-alias in the consumer crate, e.g. Winit would probably have:

pub type LogicalKey = Key<Box<str>, NativeKey>;

I'm still a bit uncertain about the default type parameters. I'm leaning towards having () as the default for the Unidentified variant (because that's likely the most common), and having no default for the keystring (because there isn't really a default that is suitable).

Also unsure about impls like PartialEq, we could simply derive it, or we could go full-out with something like impl<S1: PartialEq<S2>, S2, U1: PartialEq<U2>, U2> PartialEq<Key<S1, U1>> for Key<S2, U2>. Paradoxically, the latter might actually be worse, since it means that comparisons like key == Key::Backspace wouldn't work, as you'd have to specify the type on the right hand side as Key::<S, U>::Backspace (whereas with only the simple derived impl, the type parameters can be inferred).

WDYT?

[madsmtm]

We discussed my proposal above in today's meeting, the conclusion was that yes, we do want this, primarily for the matching ergonomics.

I'll probably implement it in Winit first, and then we can move it here once we've verified that it works as intended.