keyboard_key.tmpl 9.56 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
// Copyright 2019 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// DO NOT EDIT -- DO NOT EDIT -- DO NOT EDIT
// This file is generated by dev/tools/gen_keycodes/bin/gen_keycodes.dart and
// should not be edited directly.
//
// Edit the template dev/tools/gen_keycodes/data/keyboard_key.tmpl instead.
// See dev/tools/gen_keycodes/README.md for more information.

import 'package:flutter/foundation.dart';

/// A class with static values that describe the keys that are returned from
/// [RawKeyEvent.logicalKey].
///
/// These represent *logical* keys, which are keys which are interpreted in the
/// context of any modifiers, modes, or keyboard layouts which may be in effect.
///
/// This is contrast to [PhysicalKeyboardKey], which represents a physical key
/// in a particular location on the keyboard, without regard for the modifier
/// state, mode, or keyboard layout.
///
/// See also:
///
///  * [RawKeyEvent], the keyboard event object received by widgets that listen
///    to keyboard events.
///  * [RawKeyboardListener], a widget used to listen to and supply handlers for
///    keyboard events.
class LogicalKeyboardKey extends Diagnosticable {
  /// Defines a KeyboardKey value and optional debug name.
  ///
  /// To save executable size, it is recommended that the [debugName] be null in
  /// release mode. You can do this using the [kReleaseMode] constant:
  ///
  /// {@tool sample}
  /// const LogicalKeyboardKey mySpecialKey = LogicalKeyboardKey(
  ///   0x0010000000a,
  ///   debugName: kReleaseMode ? null : 'Special Key',
  /// );
  /// {@end-tool}
  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel});

  /// A unique code representing this key.
  ///
  /// This is an opaque identifier, and should not be unpacked to derive
  /// information from it, as the representation of the code could change at any
  /// time.
  final int keyId;

  /// The debug string to print for this keyboard key, which will be null in
  /// release mode.
  final String debugName;

  /// The Unicode string representing the character produced by a [RawKeyEvent].
  ///
  /// This value is useful for describing or matching mnemonic keyboard
  /// shortcuts.
  ///
  /// On most platforms this is a single code point, but it could contain any
  /// Unicode string. The `keyLabel` differs from [RawKeyEvent.character]
  /// because `keyLabel` only takes into account the key being pressed, not any
  /// combining keys pressed before it, so, for example, an “o” that follows a
  /// combining dieresis (“¨”, COMBINING DIAERESIS (U+0308)) would just return
  /// “o” for [keyLabel], but would return “ö” for [RawKeyEvent.character].
  ///
  /// {@macro flutter.services.RawKeyEventData.keyLabel}
  final String keyLabel;

  @override
  int get hashCode => keyId.hashCode;

  @override
  bool operator ==(dynamic other) {
    if (other.runtimeType != runtimeType) {
      return false;
    }
    final LogicalKeyboardKey typedOther = other;
    return keyId == typedOther.keyId;
  }

  /// Finds the [LogicalKeyboardKey] that matches the given ID.
  static LogicalKeyboardKey findKeyByKeyId(int keyId) => _knownLogicalKeys[keyId];

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(StringProperty('keyId', '0x${keyId.toRadixString(16).padLeft(8, '0')}', showName: true));
    properties.add(StringProperty('keyLabel', keyLabel, showName: true));
    properties.add(StringProperty('debugName', debugName, showName: true, defaultValue: null));
  }

  /// Returns true if the given label represents a Unicode control character.
  ///
  /// Examples of control characters are characters like "U+000A LINE FEED (LF)"
  /// or "U+001B ESCAPE (ESC)".
  ///
  /// See <https://en.wikipedia.org/wiki/Unicode_control_characters> for more
  /// information.
  ///
  /// Used by [RawKeyEvent] subclasses to help construct IDs.
  static bool isControlCharacter(String label) {
    if (label.length > 1) {
      return false;
    }
    final int codeUnit = label.codeUnitAt(0);
    return (codeUnit <= 0x1f && codeUnit >= 0x00) || (codeUnit >= 0x7f && codeUnit <= 0x9f);
  }

  /// Returns true if the [keyId] of this object is one that is autogenerated by
  /// Flutter.
  ///
  /// Autogenerated key IDs are generated in response to platform key codes
  /// which Flutter doesn't recognize, and their IDs shouldn't be used in a
  /// persistent way.
  ///
  /// Autogenerated IDs should be a rare occurrence: Flutter supports most keys.
  ///
  /// Keys that generate Unicode characters (even if unknown to Flutter) will
  /// not return true for `isAutogenerated`, since they will be assigned a
  /// Unicode-based code that will remain stable.
  ///
  /// If Flutter adds support for a previously unsupported key code, the ID it
  /// reports will change, but the ID will remain stable on the platform it is
  /// produced on until Flutter adds support for recognizing it.
  ///
  /// So, hypothetically, if Android added a new key code of 0xffff,
  /// representing a new "do what I mean" key, then the autogenerated code would
  /// be 0x1020000ffff, but once Flutter added the "doWhatIMean" key to the
  /// definitions below, the new code would be 0x0020000ffff for all platforms
  /// that had a "do what I mean" key from then on.
  bool get isAutogenerated => (keyId & autogeneratedMask) != 0;

  /// Mask for the 32-bit value portion of the key code. This is used by
  /// platform-specific code to generate Flutter key codes.
  static const int valueMask = 0x000FFFFFFFF;

  /// Mask for the platform prefix portion of the key code. This is used by
  /// platform-specific code to generate Flutter key codes.
  static const int platformMask = 0x0FF00000000;

  /// Mask for the autogenerated bit portion of the key code. This is used by
  /// platform-specific code to generate new Flutter key codes for keys which
  /// are not recognized.
  static const int autogeneratedMask = 0x10000000000;

  /// The code prefix for keys which have a Unicode representation. This is used
  /// by platform-specific code to generate Flutter key codes.
  static const int unicodePlane = 0x00000000000;

  /// The code prefix for keys which do not have a Unicode representation. This
  /// is used by platform-specific code to generate Flutter key codes using HID
  /// Usage codes.
  static const int hidPlane = 0x00100000000;
@@@LOGICAL_KEY_DEFINITIONS@@@
  // A list of all predefined constant LogicalKeyboardKeys so they can be
  // searched..
  static const Map<int, LogicalKeyboardKey> _knownLogicalKeys = <int, LogicalKeyboardKey>{
@@@LOGICAL_KEY_MAP@@@
  };
}

/// A class with static values that describe the keys that are returned from
/// [RawKeyEvent.physicalKey].
///
/// These represent *physical* keys, which are keys which represent a
/// particular key location on the keyboard. It ignores any modifiers, modes,
/// or keyboard layouts which may be in effect. This is contrast to
/// [LogicalKeyboardKey], which represents a logical key interpreted in the
/// context of modifiers, modes, and/or keyboard layouts.
///
/// See also:
///
///  * [RawKeyEvent], the keyboard event object received by widgets that listen
///    to keyboard events.
///  * [RawKeyboardListener], a widget used to listen to and supply handlers for
///    keyboard events.
class PhysicalKeyboardKey extends Diagnosticable {
  /// Defines a KeyboardKey value and optional debug name. The debug name must
  /// be null in release mode.
  ///
  /// To save executable size, it is recommended that the [debugName] be null in
  /// release mode. You can do this using the [kReleaseMode] constant:
  ///
  /// {@tool sample}
  /// const PhysicalKeyboardKey mySpecialPhysicalKey = PhysicalKeyboardKey(
  ///   0x0010000000a,
  ///   debugName: kReleaseMode ? null : 'Special Key',
  /// );
  /// {@end-tool}
  const PhysicalKeyboardKey(this.usbHidUsage, {this.debugName});

  /// The unique USB HID usage ID of this physical key on the keyboard.
  ///
  /// Due to the variations in platform APIs, this may not be the actual HID
  /// usage code from the hardware, but a value derived from available
  /// information on the platform.
  ///
  /// See <https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf>
  /// for the HID usage values and their meanings.
  final int usbHidUsage;

  /// The debug string to print for this keyboard key, which will be null in
  /// release mode.
  final String debugName;

  /// Finds a known [PhysicalKeyboardKey] that matches the given USB HID usage
  /// code.
  static PhysicalKeyboardKey findKeyByCode(int usageCode) => _knownPhysicalKeys[usageCode];

  @override
  int get hashCode => usbHidUsage.hashCode;

  @override
  bool operator ==(dynamic other) {
    if (other.runtimeType != runtimeType) {
      return false;
    }
    final PhysicalKeyboardKey typedOther = other;
    return usbHidUsage == typedOther.usbHidUsage;
  }

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(StringProperty('usbHidUsage', '0x${usbHidUsage.toRadixString(16).padLeft(8, '0')}', showName: true));
    properties.add(StringProperty('debugName', debugName, showName: true, defaultValue: null));
  }

  // Key constants for all keyboard keys in the USB HID specification at the
  // time Flutter was built.
@@@PHYSICAL_KEY_DEFINITIONS@@@
  // A list of all the predefined constant PhysicalKeyboardKeys so that they
  // can be searched.
  static const Map<int, PhysicalKeyboardKey> _knownPhysicalKeys = <int, PhysicalKeyboardKey>{
@@@PHYSICAL_KEY_MAP@@@
  };
}