Class KeyConvert

java.lang.Object
com.vaadin.swingbridge.surrogates.util.KeyConvert
public final class KeyConvert extends Object
Translation between Vaadin's Key / KeyModifier / KeyLocation world and AWT's VK_* keycodes, modifier masks, and key-location constants. Two directions with distinct purposes:
  • Inbound (Vaadin → AWT) — vaadinKeyToVK(Key), keyCharFrom(Key), keyModifiersToMask(Set), keyLocationToAwt(KeyLocation). Used by ComponentMixin.addKeyListener to bridge Vaadin's KeyDown/Press/Up events into SKeyEvent. Matches against event.key (letters as "a"/"A", named keys as "Enter"/"ArrowLeft") — the shift-resolved identifier KeyboardEvent.getKey() surfaces. This direction is surrogate-only; the emulator has no inbound counterpart.
  • Outbound (AWT → Vaadin) — vkToVaadinKey(int), toVaadinKeyBinding(KeyStroke), KeyConvert.VaadinKeyBinding. Used for accelerator/mnemonic install (registerKeyboardAction, menu accelerators, button mnemonics). Produces event.code-shaped Keys ("KeyA"/"Digit5") because Vaadin Shortcuts match physical keys. Shared by both modules — :emulators calls straight through here for its own registerKeyboardAction — a single shared copy in the SD_shelper_statics-allowed direction (:emulators → :surrogates), not a per-module twin.

See SD_shelper_statics (module direction) and SD_key_events (the intentional event.code/ event.key split on the inbound side, which is not deduplicated because the emulator has no inbound table).

  • Method Details

    • vaadinKeyToVK

      public static int vaadinKeyToVK(com.vaadin.flow.component.Key key)
      Vaadin Key (as received on KeyboardEvent.getKey()) → AWT VK_* keycode. Returns SKeyEvent.VK_UNDEFINED when the incoming key doesn't map to any known VK_*; per Swing's convention that's the right signal for "unknown key", not a failure.

      Matches against key.getKeys().get(0) — the first DOM-level identifier carried by the Key. For incoming events Vaadin populates this from the browser's event.key, so letters come through as "a"/"A" (the shift state is reflected in the modifier mask, not the keycode — VK_A is the same either way).

    • keyCharFrom

      public static char keyCharFrom(com.vaadin.flow.component.Key key)
      Return the effective keyChar for a Vaadin Key: the first character when the key's primary identifier is single-char (letters, digits, punctuation), or SKeyEvent.CHAR_UNDEFINED for named keys (Enter, Shift, F1, …). Browser keypress events only fire for character-producing keys, so KEY_TYPED dispatches will always see a defined char here; KEY_PRESSED / KEY_RELEASED see CHAR_UNDEFINED for action keys per AWT's convention.

    • keyModifiersToMask

      public static int keyModifiersToMask(Set<com.vaadin.flow.component.KeyModifier> modifiers)
      Vaadin KeyModifier set → AWT *_DOWN_MASK bitmask. Covers the five modifiers the browser exposes — Shift / Control / Alt / AltGraph / Meta. Any unknown modifier in the incoming set is ignored silently (Vaadin's enum is closed, so there's nothing to warn about).

    • keyLocationToAwt

      public static int keyLocationToAwt(com.vaadin.flow.component.KeyLocation location)
      Vaadin KeyLocation → AWT KEY_LOCATION_*. The two enums line up one-for-one on meaning but use different integer values — Vaadin's STANDARD=0 aligns with AWT's KEY_LOCATION_STANDARD=1, etc. A null input falls back to KEY_LOCATION_UNKNOWN so call sites constructing synthetic SKeyEvents without location info still get a sensible default.

    • vkToVaadinKey

      public static com.vaadin.flow.component.Key vkToVaadinKey(int vk)
      Inverse of vaadinKeyToVK(Key): map an AWT VK_* code to a Vaadin Key. Returns null when no stable mapping exists — callers treat null as "can't install this binding" rather than synthesising a bogus Key. Covers the letter / digit ranges (VK_A..VK_Z → "KeyA".."KeyZ", VK_0..VK_9 → "Digit0".."Digit9" — the codes browsers emit on event.code) plus the named-key switch used for accelerator install (Enter, Escape, arrows, F-keys, …). Intended for outbound wiring (mnemonic install, registerKeyboardAction); the inverse direction vaadinKeyToVK(Key) matches against event.key instead because that's what Vaadin's inbound KeyNotifier surfaces.

    • toVaadinKeyBinding

      public static KeyConvert.VaadinKeyBinding toVaadinKeyBinding(KeyStroke stroke)
      Translate KeyStroke → Vaadin Shortcuts-shaped pair. Returns null when the keystroke's keyCode isn't covered by vkToVaadinKey(int) — caller should onUnimplemented and skip browser-side install. Both modern (*_DOWN_MASK) and legacy (SHIFT_MASK, …) modifier bits accepted; AWT's KeyStroke factories produced either over the years and migrated code may mix them.