From 4b3cf9bbd63f90c492fb4c1e783ae6b171caef97 Mon Sep 17 00:00:00 2001 From: Bruno Leroux Date: Tue, 17 Jan 2023 22:23:04 +0100 Subject: [PATCH] Add reference to HardwareKeyboard in RawKeyboard documentation (#118607) --- .../lib/src/services/raw_keyboard.dart | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/flutter/lib/src/services/raw_keyboard.dart b/packages/flutter/lib/src/services/raw_keyboard.dart index e7789eb17fe..35985390510 100644 --- a/packages/flutter/lib/src/services/raw_keyboard.dart +++ b/packages/flutter/lib/src/services/raw_keyboard.dart @@ -585,6 +585,24 @@ typedef RawKeyEventHandler = bool Function(RawKeyEvent event); /// These key events are typically only key events generated by a hardware /// keyboard, and not those from software keyboards or input method editors. /// +/// ## Compared to [HardwareKeyboard] +/// +/// [RawKeyboard] is the legacy API, and will be deprecated and removed in the +/// future. It is recommended to always use [HardwareKeyboard] and [KeyEvent] +/// APIs (such as [FocusNode.onKeyEvent]) to handle key events. +/// +/// Behavior-wise, [RawKeyboard] provides a less unified, less regular +/// event model than [HardwareKeyboard]. For example: +/// +/// * Down events might not be matched with an up event, and vice versa (the +/// set of pressed keys is silently updated). +/// * The logical key of the down event might not be the same as that of the up +/// event. +/// * Down events and repeat events are not easily distinguishable (must be +/// tracked manually). +/// * Lock modes (such as CapsLock) only have their "enabled" state recorded. +/// There's no way to acquire their pressing state. +/// /// See also: /// /// * [RawKeyDownEvent] and [RawKeyUpEvent], the classes used to describe @@ -592,6 +610,7 @@ typedef RawKeyEventHandler = bool Function(RawKeyEvent event); /// * [RawKeyboardListener], a widget that listens for raw key events. /// * [SystemChannels.keyEvent], the low-level channel used for receiving /// events from the system. +/// * [HardwareKeyboard], the recommended replacement. class RawKeyboard { RawKeyboard._();