logicalKey property

LogicalKeyboardKey logicalKey
override

Returns an object representing the logical key that was pressed.

This method takes into account the key map and modifier keys (like SHIFT) to determine which logical key to return.

If you are looking for the character produced by a key event, use RawKeyEvent.character instead.

If you are collecting text strings, use the TextField or CupertinoTextField widgets, since those automatically handle many of the complexities of managing keyboard input, like showing a soft keyboard or interacting with an input method editor (IME).

See also:

Implementation

@override
LogicalKeyboardKey get logicalKey {
  // Look to see if the keyCode is a printable number pad key, so that a
  // difference between regular keys (e.g. "=") and the number pad version
  // (e.g. the "=" on the number pad) can be determined.
  final LogicalKeyboardKey numPadKey = kMacOsNumPadMap[keyCode];
  if (numPadKey != null) {
    return numPadKey;
  }
  // If this key is printable, generate the LogicalKeyboardKey from its Unicode value.
  // Control keys such as ESC, CRTL, and SHIFT are not printable. HOME, DEL, arrow keys, and function
  // keys are considered modifier function keys, which generate invalid Unicode scalar values.
  if (keyLabel != null &&
      !LogicalKeyboardKey.isControlCharacter(keyLabel) &&
      !_isUnprintableKey(keyLabel)) {
    // Given that charactersIgnoringModifiers can contain a String of arbitrary length,
    // limit to a maximum of two Unicode scalar values. It is unlikely that a keyboard would produce a code point
    // bigger than 32 bits, but it is still worth defending against this case.
    assert(charactersIgnoringModifiers.length <= 2);
    int codeUnit = charactersIgnoringModifiers.codeUnitAt(0);
    if (charactersIgnoringModifiers.length == 2) {
      final int secondCode = charactersIgnoringModifiers.codeUnitAt(1);
      codeUnit = (codeUnit << 16) | secondCode;
    }

    final int keyId = LogicalKeyboardKey.unicodePlane | (codeUnit & LogicalKeyboardKey.valueMask);
    return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
      keyId,
      keyLabel: keyLabel,
      debugName: kReleaseMode ? null : 'Key ${keyLabel.toUpperCase()}',
    );
  }

  // Control keys like "backspace" and movement keys like arrow keys don't have a printable representation,
  // but are present on the physical keyboard. Since there is no logical keycode map for macOS
  // (macOS uses the keycode to reference physical keys), a LogicalKeyboardKey is created with
  // the physical key's HID usage and debugName. This avoids duplicating the physical
  // key map.
  if (physicalKey != PhysicalKeyboardKey.none) {
    final int keyId = physicalKey.usbHidUsage | LogicalKeyboardKey.hidPlane;
    return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
      keyId,
      keyLabel: physicalKey.debugName,
      debugName: physicalKey.debugName,
    );
  }

  // This is a non-printable key that is unrecognized, so a new code is minted
  // with the autogenerated bit set.
  const int macOsKeyIdPlane = 0x00500000000;

  return LogicalKeyboardKey(
    macOsKeyIdPlane | keyCode | LogicalKeyboardKey.autogeneratedMask,
    debugName: kReleaseMode ? null : 'Unknown macOS key code $keyCode',
  );
}