Standardize the nullability of arguments to raw key data constructors. (#63523)

This standardizes the handling of nullability for the LogicalKeyboardKey.keyLabel and RawKeyEventData.keyLabel accessors so that they are non-nullable, but can be empty.

Before this change, the keyLabel could be either null or an empty string to indicate that there wasn't a label, which makes it harder to test for, since both need to be checked for. Since an empty string is sufficient, there is no need for it to be nullable.

Also, in raw_keyboard.dart, the web and Windows implementations wouldn't accept null values for parameters in the Map coming from the message, but tests were supplying null for some of them. This makes web and Windows creation of events match the other platforms, and makes the migration of tests to non-nullability easier.

dev/tools/gen_keycodes/data/keyboard_key.tmpl

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-// @dart = 2.8
+import 'package:flutter/foundation.dart';
 
 // DO NOT EDIT -- DO NOT EDIT -- DO NOT EDIT
 // This file is generated by dev/tools/gen_keycodes/bin/gen_keycodes.dart and
@@ -11,8 +11,6 @@
 // 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 base class for all keyboard key types.
 ///
 /// See also:
@@ -138,7 +136,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// const LogicalKeyboardKey(0x0010000000a, debugName: kReleaseMode ? null : 'Special Key')
   /// ```
   /// {@end-tool}
-  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel})
+  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel = ''})
       : assert(keyId != null);
 
   /// A unique code representing this key.
@@ -156,7 +154,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// This value is useful for describing or matching mnemonic keyboard
   /// shortcuts.
   ///
-  /// This value can be null if there's no key label data for a key.
+  /// This value is an empty string if there's no key label data for a key.
   ///
   /// On most platforms this is a single code point, but it could contain any
   /// Unicode string. The `keyLabel` differs from [RawKeyEvent.character]
@@ -166,7 +164,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// “o” for [keyLabel], but would return “ö” for [RawKeyEvent.character].
   ///
   /// {@macro flutter.services.RawKeyEventData.keyLabel}
-  final String? keyLabel;
+  final String keyLabel;
 
   @override
   int get hashCode => keyId.hashCode;
@@ -194,7 +192,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   ///
   /// Used by [RawKeyEvent] subclasses to help construct IDs.
   static bool isControlCharacter(String label) {
-    if (label.length > 1) {
+    if (label.length != 1) {
       return false;
     }
     final int codeUnit = label.codeUnitAt(0);

packages/flutter/lib/src/services/keyboard_key.dart

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'package:flutter/foundation.dart';
 
 // DO NOT EDIT -- DO NOT EDIT -- DO NOT EDIT
 // This file is generated by dev/tools/gen_keycodes/bin/gen_keycodes.dart and
@@ -10,8 +11,6 @@
 // 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 base class for all keyboard key types.
 ///
 /// See also:
@@ -137,7 +136,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// const LogicalKeyboardKey(0x0010000000a, debugName: kReleaseMode ? null : 'Special Key')
   /// ```
   /// {@end-tool}
-  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel})
+  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel = ''})
       : assert(keyId != null);
 
   /// A unique code representing this key.
@@ -155,7 +154,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// This value is useful for describing or matching mnemonic keyboard
   /// shortcuts.
   ///
-  /// This value can be null if there's no key label data for a key.
+  /// This value is an empty string if there's no key label data for a key.
   ///
   /// On most platforms this is a single code point, but it could contain any
   /// Unicode string. The `keyLabel` differs from [RawKeyEvent.character]
@@ -165,7 +164,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   /// “o” for [keyLabel], but would return “ö” for [RawKeyEvent.character].
   ///
   /// {@macro flutter.services.RawKeyEventData.keyLabel}
-  final String? keyLabel;
+  final String keyLabel;
 
   @override
   int get hashCode => keyId.hashCode;
@@ -193,7 +192,7 @@ class LogicalKeyboardKey extends KeyboardKey {
   ///
   /// Used by [RawKeyEvent] subclasses to help construct IDs.
   static bool isControlCharacter(String label) {
-    if (label.length > 1) {
+    if (label.length != 1) {
       return false;
     }
     final int codeUnit = label.codeUnitAt(0);

packages/flutter/lib/src/services/raw_keyboard.dart

@@ -213,6 +213,8 @@ abstract class RawKeyEventData {
 
   /// Returns the Unicode string representing the label on this key.
   ///
+  /// This value is an empty string if there's no key label data for a key.
+  ///
   /// {@template flutter.services.RawKeyEventData.keyLabel}
   /// Do not use the [keyLabel] to compose a text string: it will be missing
   /// special processing for Unicode strings for combining characters and other
@@ -226,7 +228,7 @@ abstract class RawKeyEventData {
   /// complexities of managing keyboard input, like showing a soft keyboard or
   /// interacting with an input method editor (IME).
   /// {@endtemplate}
-  String? get keyLabel;
+  String get keyLabel;
 }
 
 /// Defines the interface for raw key events.
@@ -308,17 +310,17 @@ abstract class RawKeyEvent with Diagnosticable {
         break;
       case 'web':
         data = RawKeyEventDataWeb(
-          code: message['code'] as String,
-          key: message['key'] as String,
-          metaState: message['metaState'] as int,
+          code: message['code'] as String? ?? '',
+          key: message['key'] as String? ?? '',
+          metaState: message['metaState'] as int? ?? 0,
         );
         break;
       case 'windows':
         data = RawKeyEventDataWindows(
-          keyCode: message['keyCode'] as int,
-          scanCode: message['scanCode'] as int,
-          characterCodePoint: message['characterCodePoint'] as int,
-          modifiers: message['modifiers'] as int,
+          keyCode: message['keyCode'] as int? ?? 0,
+          scanCode: message['scanCode'] as int? ?? 0,
+          characterCodePoint: message['characterCodePoint'] as int? ?? 0,
+          modifiers: message['modifiers'] as int? ?? 0,
         );
         break;
       default:

packages/flutter/lib/src/services/raw_keyboard_android.dart

@@ -147,7 +147,7 @@ class RawKeyEventDataAndroid extends RawKeyEventData {
 
   // Android only reports a single code point for the key label.
   @override
-  String? get keyLabel => plainCodePoint == 0 ? null : String.fromCharCode(plainCodePoint & _kCombiningCharacterMask);
+  String get keyLabel => plainCodePoint == 0 ? '' : String.fromCharCode(plainCodePoint & _kCombiningCharacterMask);
 
   @override
   PhysicalKeyboardKey get physicalKey {
@@ -191,13 +191,13 @@ class RawKeyEventDataAndroid extends RawKeyEventData {
     // constant, or construct a new Unicode-based key from it. Don't mark it as
     // autogenerated, since the label uniquely identifies an ID from the Unicode
     // plane.
-    if (keyLabel != null && keyLabel!.isNotEmpty && !LogicalKeyboardKey.isControlCharacter(keyLabel!)) {
+    if (keyLabel.isNotEmpty && !LogicalKeyboardKey.isControlCharacter(keyLabel)) {
       final int combinedCodePoint = plainCodePoint & _kCombiningCharacterMask;
       final int keyId = LogicalKeyboardKey.unicodePlane | (combinedCodePoint & LogicalKeyboardKey.valueMask);
       return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
         keyId,
         keyLabel: keyLabel,
-        debugName: kReleaseMode ? null : 'Key ${keyLabel!.toUpperCase()}',
+        debugName: kReleaseMode ? null : 'Key ${keyLabel.toUpperCase()}',
       );
     }
 

packages/flutter/lib/src/services/raw_keyboard_fuchsia.dart

@@ -61,7 +61,7 @@ class RawKeyEventDataFuchsia extends RawKeyEventData {
 
   // Fuchsia only reports a single code point for the key label.
   @override
-  String? get keyLabel => codePoint == 0 ? null : String.fromCharCode(codePoint);
+  String get keyLabel => codePoint == 0 ? '' : String.fromCharCode(codePoint);
 
   @override
   LogicalKeyboardKey get logicalKey {

packages/flutter/lib/src/services/raw_keyboard_linux.dart

@@ -70,7 +70,7 @@ class RawKeyEventDataLinux extends RawKeyEventData {
   final bool isDown;
 
   @override
-  String? get keyLabel => unicodeScalarValues == 0 ? null : String.fromCharCode(unicodeScalarValues);
+  String get keyLabel => unicodeScalarValues == 0 ? '' : String.fromCharCode(unicodeScalarValues);
 
   @override
   PhysicalKeyboardKey get physicalKey => kLinuxToPhysicalKey[scanCode] ?? PhysicalKeyboardKey.none;
@@ -89,13 +89,13 @@ class RawKeyEventDataLinux extends RawKeyEventData {
     // constant, or construct a new Unicode-based key from it. Don't mark it as
     // autogenerated, since the label uniquely identifies an ID from the Unicode
     // plane.
-    if (keyLabel != null &&
-        !LogicalKeyboardKey.isControlCharacter(keyLabel!)) {
+    if (keyLabel.isNotEmpty &&
+        !LogicalKeyboardKey.isControlCharacter(keyLabel)) {
       final int keyId = LogicalKeyboardKey.unicodePlane | (unicodeScalarValues & LogicalKeyboardKey.valueMask);
       return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
         keyId,
         keyLabel: keyLabel,
-        debugName: kReleaseMode ? null : 'Key ${keyLabel!.toUpperCase()}',
+        debugName: kReleaseMode ? null : 'Key ${keyLabel.toUpperCase()}',
       );
     }
 

packages/flutter/lib/src/services/raw_keyboard_macos.dart

@@ -62,7 +62,7 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
   final int modifiers;
 
   @override
-  String? get keyLabel => charactersIgnoringModifiers.isEmpty ? null : charactersIgnoringModifiers;
+  String get keyLabel => charactersIgnoringModifiers;
 
   @override
   PhysicalKeyboardKey get physicalKey => kMacOsToPhysicalKey[keyCode] ?? PhysicalKeyboardKey.none;
@@ -76,15 +76,17 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
     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.
+    // 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.isNotEmpty &&
+        !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) {
@@ -96,20 +98,21 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
       return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
         keyId,
         keyLabel: keyLabel,
-        debugName: kReleaseMode ? null : 'Key ${keyLabel!.toUpperCase()}',
+        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.
+    // 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,
+        keyLabel: physicalKey.debugName ?? '',
         debugName: physicalKey.debugName,
       );
     }
@@ -129,10 +132,9 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
       return false;
     }
     // If only the "anyMask" bit is set, then we respond true for requests of
-    // whether either left or right is pressed.
-    // Handles the case where macOS supplies just the "either" modifier flag,
-    // but not the left/right flag. (e.g. modifierShift but not
-    // modifierLeftShift).
+    // whether either left or right is pressed. Handles the case where macOS
+    // supplies just the "either" modifier flag, but not the left/right flag.
+    // (e.g. modifierShift but not modifierLeftShift).
     final bool anyOnly = modifiers & (leftMask | rightMask | anyMask) == anyMask;
     switch (side) {
       case KeyboardSide.any:
@@ -229,7 +231,7 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
   ///
   /// Used by [RawKeyEvent] subclasses to help construct IDs.
   static bool _isUnprintableKey(String label) {
-    if (label.length > 1) {
+    if (label.length != 1) {
       return false;
     }
     final int codeUnit = label.codeUnitAt(0);

packages/flutter/lib/src/services/raw_keyboard_web.dart

@@ -36,7 +36,7 @@ class RawKeyEventDataWeb extends RawKeyEventData {
   ///
   /// See <https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key>
   /// for more information.
-  final String? key;
+  final String key;
 
   /// The modifiers that were present when the key event occurred.
   ///
@@ -56,7 +56,7 @@ class RawKeyEventDataWeb extends RawKeyEventData {
   final int metaState;
 
   @override
-  String? get keyLabel => key;
+  String get keyLabel => key == 'Unidentified' ? '' : key;
 
   @override
   PhysicalKeyboardKey get physicalKey {

packages/flutter/lib/src/services/raw_keyboard_windows.dart

@@ -54,7 +54,7 @@ class RawKeyEventDataWindows extends RawKeyEventData {
   final int modifiers;
 
   @override
-  String? get keyLabel => characterCodePoint == 0 ? null : String.fromCharCode(characterCodePoint);
+  String get keyLabel => characterCodePoint == 0 ? '' : String.fromCharCode(characterCodePoint);
 
   @override
   PhysicalKeyboardKey get physicalKey => kWindowsToPhysicalKey[scanCode] ?? PhysicalKeyboardKey.none;
@@ -73,12 +73,12 @@ class RawKeyEventDataWindows extends RawKeyEventData {
     // constant, or construct a new Unicode-based key from it. Don't mark it as
     // autogenerated, since the label uniquely identifies an ID from the Unicode
     // plane.
-    if (keyLabel != null && keyLabel!.isNotEmpty && !LogicalKeyboardKey.isControlCharacter(keyLabel!)) {
+    if (keyLabel.isNotEmpty && !LogicalKeyboardKey.isControlCharacter(keyLabel)) {
       final int keyId = LogicalKeyboardKey.unicodePlane | (characterCodePoint & LogicalKeyboardKey.valueMask);
       return LogicalKeyboardKey.findKeyByKeyId(keyId) ?? LogicalKeyboardKey(
         keyId,
         keyLabel: keyLabel,
-        debugName: kReleaseMode ? null : 'Key ${keyLabel!.toUpperCase()}',
+        debugName: kReleaseMode ? null : 'Key ${keyLabel.toUpperCase()}',
       );
     }
     // Look to see if the keyCode is one we know about and have a mapping for.
@@ -104,10 +104,9 @@ class RawKeyEventDataWindows extends RawKeyEventData {
       return false;
     }
     // If only the "anyMask" bit is set, then we respond true for requests of
-    // whether either left or right is pressed.
-    // Handles the case where Windows supplies just the "either" modifier flag,
-    // but not the left/right flag. (e.g. modifierShift but not
-    // modifierLeftShift).
+    // whether either left or right is pressed. Handles the case where Windows
+    // supplies just the "either" modifier flag, but not the left/right flag.
+    // (e.g. modifierShift but not modifierLeftShift).
     final bool anyOnly = modifiers & (leftMask | rightMask | anyMask) == anyMask;
     switch (side) {
       case KeyboardSide.any:

packages/flutter_test/lib/src/event_simulation.dart

@@ -180,13 +180,17 @@ class KeyEventSimulator {
     switch (platform) {
       case 'android':
         result['keyCode'] = keyCode;
-        result['codePoint'] = key.keyLabel?.codeUnitAt(0);
+        if (key.keyLabel.isNotEmpty) {
+          result['codePoint'] = key.keyLabel.codeUnitAt(0);
+        }
         result['scanCode'] = scanCode;
         result['metaState'] = _getAndroidModifierFlags(key, isDown);
         break;
       case 'fuchsia':
         result['hidUsage'] = physicalKey?.usbHidUsage ?? (key.keyId & LogicalKeyboardKey.hidPlane != 0 ? key.keyId & LogicalKeyboardKey.valueMask : null);
-        result['codePoint'] = key.keyLabel?.codeUnitAt(0);
+        if (key.keyLabel.isNotEmpty) {
+          result['codePoint'] = key.keyLabel.codeUnitAt(0);
+        }
         result['modifiers'] = _getFuchsiaModifierFlags(key, isDown);
         break;
       case 'linux':
@@ -209,7 +213,9 @@ class KeyEventSimulator {
       case 'windows':
         result['keyCode'] = keyCode;
         result['scanCode'] = scanCode;
-        result['characterCodePoint'] = key.keyLabel?.codeUnitAt(0) ?? 0;
+        if (key.keyLabel.isNotEmpty) {
+          result['characterCodePoint'] = key.keyLabel.codeUnitAt(0);
+        }
         result['modifiers'] = _getWindowsModifierFlags(key, isDown);
     }
     return result;