KeyMessage class

The assembled information converted from a native key message.

This class is deprecated, and will be removed. There is no direct substitute planned, since this class will no longer be necessary once RawKeyEvent and associated APIs are removed.

Native key messages, produced by physically pressing or releasing keyboard keys, are translated into two different event streams in Flutter:

• The KeyEvent stream, represented by KeyMessage.events (recommended).
• The RawKeyEvent stream, represented by KeyMessage.rawEvent (legacy, to be deprecated).

Either the KeyEvent stream or the RawKeyEvent stream alone provides a complete description of the keyboard messages, but in different event models. Flutter is still transitioning from the legacy model to the new model, therefore it dispatches both streams simultaneously until the transition is completed. KeyMessage is used to bundle the stream segments of both models from a native key message together for the convenience of propagation.

Typically, an application either processes KeyMessage.events or KeyMessage.rawEvent, not both. For example, handling a KeyMessage, means handling each event in KeyMessage.events.

In advanced cases, a widget needs to process both streams at the same time. For example, FocusNode has an onKey that dispatches RawKeyEvents and an onKeyEvent that dispatches KeyEvents. To processes a KeyMessage, it first calls onKeyEvent with each KeyEvent of events, and then onKey with rawEvent. All callbacks are invoked regardless of their KeyEventResult. Their results are combined into the result of the node using combineKeyEventResults.

void handleMessage(FocusNode node, KeyMessage message) {
  final List<KeyEventResult> results = <KeyEventResult>[];
  if (node.onKeyEvent != null) {
    for (final KeyEvent event in message.events) {
      results.add(node.onKeyEvent!(node, event));
    }
  }
  if (node.onKey != null && message.rawEvent != null) {
    results.add(node.onKey!(node, message.rawEvent!));
  }
  final KeyEventResult result = combineKeyEventResults(results);
  // Progress based on `result`...
}