actions.dart 41.4 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
Ian Hickson's avatar
Ian Hickson committed
4

5 6
// @dart = 2.8

7
import 'package:flutter/foundation.dart';
8
import 'package:flutter/scheduler.dart';
9
import 'package:flutter/gestures.dart';
10
import 'package:flutter/rendering.dart';
11

12
import 'basic.dart';
13
import 'focus_manager.dart';
14
import 'focus_scope.dart';
15
import 'framework.dart';
16
import 'media_query.dart';
17
import 'shortcuts.dart';
18

19 20 21 22 23 24 25 26 27 28 29 30 31
// BuildContext/Element doesn't have a parent accessor, but it can be
// simulated with visitAncestorElements. _getParent is needed because
// context.getElementForInheritedWidgetOfExactType will return itself if it
// happens to be of the correct type. getParent should be O(1), since we
// always return false at the first ancestor.
BuildContext _getParent(BuildContext context) {
  BuildContext parent;
  context.visitAncestorElements((Element ancestor) {
    parent = ancestor;
    return false;
  });
  return parent;
}
32

33
/// A class representing a particular configuration of an [Action].
34
///
35
/// This class is what the [Shortcuts.shortcuts] map has as values, and is used
36 37
/// by an [ActionDispatcher] to look up an action and invoke it, giving it this
/// object to extract configuration information from.
38 39 40 41 42 43
///
/// See also:
///
///  * [Actions.invoke], which invokes the action associated with a specified
///    [Intent] using the [Actions] widget that most tightly encloses the given
///    [BuildContext].
44
@immutable
45
class Intent with Diagnosticable {
46
  /// A const constructor for an [Intent].
47
  const Intent();
48

49 50
  /// An intent that can't be mapped to an action.
  ///
51 52 53
  /// This Intent is mapped to an action in the [WidgetsApp] that does nothing,
  /// so that it can be bound to a key in a [Shortcuts] widget in order to
  /// disable a key binding made above it in the hierarchy.
54
  static const DoNothingIntent doNothing = DoNothingIntent._();
55 56
}

57 58 59 60 61 62
/// The kind of callback that an [Action] uses to notify of changes to the
/// action's state.
///
/// To register an action listener, call [Action.addActionListener].
typedef ActionListenerCallback = void Function(Action<Intent> action);

63 64 65 66 67 68 69 70 71 72 73 74 75
/// Base class for actions.
///
/// As the name implies, an [Action] is an action or command to be performed.
/// They are typically invoked as a result of a user action, such as a keyboard
/// shortcut in a [Shortcuts] widget, which is used to look up an [Intent],
/// which is given to an [ActionDispatcher] to map the [Intent] to an [Action]
/// and invoke it.
///
/// The [ActionDispatcher] can invoke an [Action] on the primary focus, or
/// without regard for focus.
///
/// See also:
///
76
///  * [Shortcuts], which is a widget that contains a key map, in which it looks
77
///    up key combinations in order to invoke actions.
78
///  * [Actions], which is a widget that defines a map of [Intent] to [Action]
79
///    and allows redefining of actions for its descendants.
80 81 82 83 84 85 86
///  * [ActionDispatcher], a class that takes an [Action] and invokes it, passing
///    a given [Intent].
abstract class Action<T extends Intent> with Diagnosticable {
  final ObserverList<ActionListenerCallback> _listeners = ObserverList<ActionListenerCallback>();

  /// Gets the type of intent this action responds to.
  Type get intentType => T;
87

88
  /// Returns true if the action is enabled and is ready to be invoked.
89
  ///
90 91 92 93 94
  /// This will be called by the [ActionDispatcher] before attempting to invoke
  /// the action.
  ///
  /// If the enabled state changes, overriding subclasses must call
  /// [notifyActionListeners] to notify any listeners of the change.
95
  bool isEnabled(covariant T intent) => true;
96 97 98

  /// Called when the action is to be performed.
  ///
99 100 101
  /// This is called by the [ActionDispatcher] when an action is invoked via
  /// [Actions.invoke], or when an action is invoked using
  /// [ActionDispatcher.invokeAction] directly.
102 103
  ///
  /// This method is only meant to be invoked by an [ActionDispatcher], or by
104
  /// its subclasses, and only when [isEnabled] is true.
105 106 107 108 109 110 111
  ///
  /// When overriding this method, the returned value can be any Object, but
  /// changing the return type of the override to match the type of the returned
  /// value provides more type safety.
  ///
  /// For instance, if your override of `invoke` returns an `int`, then define
  /// it like so:
112
  ///
113 114 115 116 117 118 119 120 121 122 123 124 125 126
  /// ```dart
  /// class IncrementIntent extends Intent {
  ///   const IncrementIntent({this.index});
  ///
  ///   final int index;
  /// }
  ///
  /// class MyIncrementAction extends Action<IncrementIntent> {
  ///   @override
  ///   int invoke(IncrementIntent intent) {
  ///     return intent.index + 1;
  ///   }
  /// }
  /// ```
127
  @protected
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 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
  Object invoke(covariant T intent);

  /// Register a callback to listen for changes to the state of this action.
  ///
  /// If you call this, you must call [removeActionListener] a matching number
  /// of times, or memory leaks will occur. To help manage this and avoid memory
  /// leaks, use of the [ActionListener] widget to register and unregister your
  /// listener appropriately is highly recommended.
  ///
  /// {@template flutter.widgets.actions.multipleAdds}
  /// If a listener had been added twice, and is removed once during an
  /// iteration (i.e. in response to a notification), it will still be called
  /// again. If, on the other hand, it is removed as many times as it was
  /// registered, then it will no longer be called. This odd behavior is the
  /// result of the [Action] not being able to determine which listener
  /// is being removed, since they are identical, and therefore conservatively
  /// still calling all the listeners when it knows that any are still
  /// registered.
  ///
  /// This surprising behavior can be unexpectedly observed when registering a
  /// listener on two separate objects which are both forwarding all
  /// registrations to a common upstream object.
  /// {@endtemplate}
  @mustCallSuper
  void addActionListener(ActionListenerCallback listener) => _listeners.add(listener);

  /// Remove a previously registered closure from the list of closures that are
  /// notified when the object changes.
  ///
  /// If the given listener is not registered, the call is ignored.
  ///
  /// If you call [addActionListener], you must call this method a matching
  /// number of times, or memory leaks will occur. To help manage this and avoid
  /// memory leaks, use of the [ActionListener] widget to register and
  /// unregister your listener appropriately is highly recommended.
  ///
  /// {@macro flutter.widgets.actions.multipleAdds}
  @mustCallSuper
  void removeActionListener(ActionListenerCallback listener) => _listeners.remove(listener);

  /// Call all the registered listeners.
  ///
  /// Subclasses should call this method whenever the object changes, to notify
  /// any clients the object may have changed. Listeners that are added during this
  /// iteration will not be visited. Listeners that are removed during this
  /// iteration will not be visited after they are removed.
  ///
  /// Exceptions thrown by listeners will be caught and reported using
  /// [FlutterError.reportError].
  ///
  /// Surprising behavior can result when reentrantly removing a listener (i.e.
  /// in response to a notification) that has been registered multiple times.
  /// See the discussion at [removeActionListener].
  @protected
  @visibleForTesting
  void notifyActionListeners() {
    if (_listeners.isEmpty) {
      return;
    }

    // Make a local copy so that a listener can unregister while the list is
    // being iterated over.
    final List<ActionListenerCallback> localListeners = List<ActionListenerCallback>.from(_listeners);
    for (final ActionListenerCallback listener in localListeners) {
      InformationCollector collector;
      assert(() {
        collector = () sync* {
          yield DiagnosticsProperty<Action<T>>(
            'The $runtimeType sending notification was',
            this,
            style: DiagnosticsTreeStyle.errorProperty,
          );
        };
        return true;
      }());
      try {
        if (_listeners.contains(listener)) {
          listener(this);
        }
      } catch (exception, stack) {
        FlutterError.reportError(FlutterErrorDetails(
          exception: exception,
          stack: stack,
          library: 'widgets library',
          context: ErrorDescription('while dispatching notifications for $runtimeType'),
          informationCollector: collector,
        ));
      }
    }
  }
}

/// A helper widget for making sure that listeners on an action are removed properly.
///
/// Listeners on the [Action] class must have their listener callbacks removed
/// with [Action.removeActionListener] when the listener is disposed of. This widget
/// helps with that, by providing a lifetime for the connection between the
/// [listener] and the [Action], and by handling the adding and removing of
/// the [listener] at the right points in the widget lifecycle.
///
/// If you listen to an [Action] widget in a widget hierarchy, you should use
/// this widget. If you are using an [Action] outside of a widget context, then
/// you must call removeListener yourself.
@immutable
class ActionListener extends StatefulWidget {
  /// Create a const [ActionListener].
  ///
  /// The [listener], [action], and [child] arguments must not be null.
  const ActionListener({
    Key key,
    @required this.listener,
    @required this.action,
    @required this.child,
  })  : assert(listener != null),
        assert(action != null),
        assert(child != null),
        super(key: key);

  /// The [ActionListenerCallback] callback to register with the [action].
  ///
  /// Must not be null.
  final ActionListenerCallback listener;

  /// The [Action] that the callback will be registered with.
  ///
  /// Must not be null.
  final Action<Intent> action;

  /// {@macro flutter.widgets.child}
  final Widget child;
258 259

  @override
260 261 262 263 264 265 266 267
  _ActionListenerState createState() => _ActionListenerState();
}

class _ActionListenerState extends State<ActionListener> {
  @override
  void initState() {
    super.initState();
    widget.action.addActionListener(widget.listener);
268
  }
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302

  @override
  void didUpdateWidget(ActionListener oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (oldWidget.action == widget.action && oldWidget.listener == widget.listener) {
      return;
    }
    oldWidget.action.removeActionListener(oldWidget.listener);
    widget.action.addActionListener(widget.listener);
  }

  @override
  void dispose() {
    widget.action.removeActionListener(widget.listener);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => widget.child;
}

/// An abstract [Action] subclass that adds an optional [BuildContext] to the
/// [invoke] method to be able to provide context to actions.
///
/// [ActionDispatcher.invokeAction] checks to see if the action it is invoking
/// is a [ContextAction], and if it is, supplies it with a context.
abstract class ContextAction<T extends Intent> extends Action<T> {
  /// Called when the action is to be performed.
  ///
  /// This is called by the [ActionDispatcher] when an action is invoked via
  /// [Actions.invoke], or when an action is invoked using
  /// [ActionDispatcher.invokeAction] directly.
  ///
  /// This method is only meant to be invoked by an [ActionDispatcher], or by
303
  /// its subclasses, and only when [isEnabled] is true.
304 305
  ///
  /// The optional `context` parameter is the context of the invocation of the
306
  /// action, and in the case of an action invoked by a [ShortcutManager], via
307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
  /// a [Shortcuts] widget, will be the context of the [Shortcuts] widget.
  ///
  /// When overriding this method, the returned value can be any Object, but
  /// changing the return type of the override to match the type of the returned
  /// value provides more type safety.
  ///
  /// For instance, if your override of `invoke` returns an `int`, then define
  /// it like so:
  ///
  /// ```dart
  /// class IncrementIntent extends Intent {
  ///   const IncrementIntent({this.index});
  ///
  ///   final int index;
  /// }
  ///
  /// class MyIncrementAction extends ContextAction<IncrementIntent> {
  ///   @override
  ///   int invoke(IncrementIntent intent, [BuildContext context]) {
  ///     return intent.index + 1;
  ///   }
  /// }
  /// ```
  @protected
  @override
  Object invoke(covariant T intent, [BuildContext context]);
333 334 335
}

/// The signature of a callback accepted by [CallbackAction].
336
typedef OnInvokeCallback<T extends Intent> = Object Function(T intent);
337 338

/// An [Action] that takes a callback in order to configure it without having to
339
/// create an explicit [Action] subclass just to call a callback.
340 341 342
///
/// See also:
///
343
///  * [Shortcuts], which is a widget that contains a key map, in which it looks
344
///    up key combinations in order to invoke actions.
345
///  * [Actions], which is a widget that defines a map of [Intent] to [Action]
346
///    and allows redefining of actions for its descendants.
347
///  * [ActionDispatcher], a class that takes an [Action] and invokes it using a
348
///    [FocusNode] for context.
349 350
class CallbackAction<T extends Intent> extends Action<T> {
  /// A constructor for a [CallbackAction].
351 352 353
  ///
  /// The `intentKey` and [onInvoke] parameters must not be null.
  /// The [onInvoke] parameter is required.
354
  CallbackAction({@required this.onInvoke}) : assert(onInvoke != null);
355 356 357 358 359

  /// The callback to be called when invoked.
  ///
  /// Must not be null.
  @protected
360
  final OnInvokeCallback<T> onInvoke;
361 362

  @override
363
  Object invoke(covariant T intent) => onInvoke(intent);
364 365
}

366 367 368 369 370 371 372 373
/// An action dispatcher that simply invokes the actions given to it.
///
/// See also:
///
///  - [ShortcutManager], that uses this class to invoke actions.
///  - [Shortcuts] widget, which defines key mappings to [Intent]s.
///  - [Actions] widget, which defines a mapping between a in [Intent] type and
///    an [Action].
374
class ActionDispatcher with Diagnosticable {
375
  /// Const constructor so that subclasses can be immutable.
376 377
  const ActionDispatcher();

378
  /// Invokes the given `action`, passing it the given `intent`.
379
  ///
380 381 382 383
  /// The action will be invoked with the given `context`, if given, but only if
  /// the action is a [ContextAction] subclass. If no `context` is given, and
  /// the action is a [ContextAction], then the context from the [primaryFocus]
  /// is used.
384
  ///
385 386 387 388
  /// Returns the object returned from [Action.invoke] if the action was
  /// successfully invoked, and null if the action is not enabled. May also
  /// return null if [Action.invoke] returns null.
  Object invokeAction(covariant Action<Intent> action, covariant Intent intent, [BuildContext context]) {
389 390
    assert(action != null);
    assert(intent != null);
391
    context ??= primaryFocus?.context;
392
    if (action.isEnabled(intent)) {
393 394 395 396 397
      if (action is ContextAction) {
        return action.invoke(intent, context);
      } else {
        return action.invoke(intent);
      }
398
    }
399
    return null;
400 401 402 403 404 405 406 407 408 409 410
  }
}

/// A widget that establishes an [ActionDispatcher] and a map of [Intent] to
/// [Action] to be used by its descendants when invoking an [Action].
///
/// Actions are typically invoked using [Actions.invoke] with the context
/// containing the ambient [Actions] widget.
///
/// See also:
///
411 412 413 414 415 416
///  * [ActionDispatcher], the object that this widget uses to manage actions.
///  * [Action], a class for containing and defining an invocation of a user
///    action.
///  * [Intent], a class that holds a unique [LocalKey] identifying an action,
///    as well as configuration information for running the [Action].
///  * [Shortcuts], a widget used to bind key combinations to [Intent]s.
417
class Actions extends StatefulWidget {
418 419 420 421 422
  /// Creates an [Actions] widget.
  ///
  /// The [child], [actions], and [dispatcher] arguments must not be null.
  const Actions({
    Key key,
423
    this.dispatcher,
424
    @required this.actions,
425
    @required this.child,
426
  })  : assert(actions != null),
427 428
        assert(child != null),
        super(key: key);
429 430 431 432

  /// The [ActionDispatcher] object that invokes actions.
  ///
  /// This is what is returned from [Actions.of], and used by [Actions.invoke].
433 434 435 436 437
  ///
  /// If this [dispatcher] is null, then [Actions.of] and [Actions.invoke] will
  /// look up the tree until they find an Actions widget that has a dispatcher
  /// set. If not such widget is found, then they will return/use a
  /// default-constructed [ActionDispatcher].
438 439
  final ActionDispatcher dispatcher;

440
  /// {@template flutter.widgets.actions.actions}
441 442
  /// A map of [Intent] keys to [Action<Intent>] objects that defines which
  /// actions this widget knows about.
443 444 445 446
  ///
  /// For performance reasons, it is recommended that a pre-built map is
  /// passed in here (e.g. a final variable from your widget class) instead of
  /// defining it inline in the build function.
447
  /// {@endtemplate}
448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469
  final Map<Type, Action<Intent>> actions;

  /// {@macro flutter.widgets.child}
  final Widget child;

  // Visits the Actions widget ancestors of the given element using
  // getElementForInheritedWidgetOfExactType. Returns true if the visitor found
  // what it was looking for.
  static bool _visitActionsAncestors(BuildContext context, bool visitor(InheritedElement element)) {
    InheritedElement actionsElement = context.getElementForInheritedWidgetOfExactType<_ActionsMarker>();
    while (actionsElement != null) {
      if (visitor(actionsElement) == true) {
        break;
      }
      // _getParent is needed here because
      // context.getElementForInheritedWidgetOfExactType will return itself if it
      // happens to be of the correct type.
      final BuildContext parent = _getParent(actionsElement);
      actionsElement = parent.getElementForInheritedWidgetOfExactType<_ActionsMarker>();
    }
    return actionsElement != null;
  }
470

471 472
  // Finds the nearest valid ActionDispatcher, or creates a new one if it
  // doesn't find one.
473 474 475 476 477 478 479
  static ActionDispatcher _findDispatcher(BuildContext context) {
    ActionDispatcher dispatcher;
    _visitActionsAncestors(context, (InheritedElement element) {
      final ActionDispatcher found = (element.widget as _ActionsMarker).dispatcher;
      if (found != null) {
        dispatcher = found;
        return true;
480
      }
481 482 483 484
      return false;
    });
    return dispatcher ?? const ActionDispatcher();
  }
485

486 487 488 489 490 491 492 493 494 495 496 497 498
  /// Returns a [VoidCallback] handler that invokes the bound action for the
  /// given `intent` if the action is enabled, and returns null if the action is
  /// not enabled.
  ///
  /// This is intended to be used in widgets which have something similar to an
  /// `onTap` handler, which takes a `VoidCallback`, and can be set to the
  /// result of calling this function.
  ///
  /// Creates a dependency on the [Actions] widget that maps the bound action so
  /// that if the actions change, the context will be rebuilt and find the
  /// updated action.
  static VoidCallback handler<T extends Intent>(BuildContext context, T intent, {bool nullOk = false}) {
    final Action<T> action = Actions.find<T>(context, nullOk: nullOk);
499
    if (action != null && action.isEnabled(intent)) {
500 501 502
      return () {
        Actions.of(context).invokeAction(action, intent, context);
      };
503
    }
504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542
    return null;
  }

  /// Finds the [Action] bound to the given intent type `T` in the given `context`.
  ///
  /// Creates a dependency on the [Actions] widget that maps the bound action so
  /// that if the actions change, the context will be rebuilt and find the
  /// updated action.
  static Action<T> find<T extends Intent>(BuildContext context, {bool nullOk = false}) {
    Action<T> action;

    _visitActionsAncestors(context, (InheritedElement element) {
      final _ActionsMarker actions = element.widget as _ActionsMarker;
      final Action<T> result = actions.actions[T] as Action<T>;
      if (result != null) {
        context.dependOnInheritedElement(element);
        action = result;
        return true;
      }
      return false;
    });

    assert(() {
      if (nullOk) {
        return true;
      }
      if (action == null) {
        throw FlutterError('Unable to find an action for a $T in an $Actions widget '
            'in the given context.\n'
            "$Actions.find() was called on a context that doesn\'t contain an "
            '$Actions widget with a mapping for the given intent type.\n'
            'The context used was:\n'
            '  $context\n'
            'The intent type requested was:\n'
            '  $T');
      }
      return true;
    }());
    return action;
543 544
  }

545 546 547 548 549 550 551 552 553 554 555
  /// Returns the [ActionDispatcher] associated with the [Actions] widget that
  /// most tightly encloses the given [BuildContext].
  ///
  /// Will throw if no ambient [Actions] widget is found.
  ///
  /// If `nullOk` is set to true, then if no ambient [Actions] widget is found,
  /// this will return null.
  ///
  /// The `context` argument must not be null.
  static ActionDispatcher of(BuildContext context, {bool nullOk = false}) {
    assert(context != null);
556
    final _ActionsMarker marker = context.dependOnInheritedWidgetOfExactType<_ActionsMarker>();
557 558 559 560
    assert(() {
      if (nullOk) {
        return true;
      }
561 562
      if (marker == null) {
        throw FlutterError('Unable to find an $Actions widget in the given context.\n'
563 564 565 566 567 568 569 570 571 572
            '$Actions.of() was called with a context that does not contain an '
            '$Actions widget.\n'
            'No $Actions ancestor could be found starting from the context that '
            'was passed to $Actions.of(). This can happen if the context comes '
            'from a widget above those widgets.\n'
            'The context used was:\n'
            '  $context');
      }
      return true;
    }());
573
    return marker?.dispatcher ?? _findDispatcher(context);
574 575
  }

Kate Lovett's avatar
Kate Lovett committed
576
  /// Invokes the action associated with the given [Intent] using the
577 578 579 580 581
  /// [Actions] widget that most tightly encloses the given [BuildContext].
  ///
  /// The `context`, `intent` and `nullOk` arguments must not be null.
  ///
  /// If the given `intent` isn't found in the first [Actions.actions] map, then
582
  /// it will look to the next [Actions] widget in the hierarchy until it
583 584 585
  /// reaches the root.
  ///
  /// Will throw if no ambient [Actions] widget is found, or if the given
Kate Lovett's avatar
Kate Lovett committed
586
  /// `intent` doesn't map to an action in any of the [Actions.actions] maps
587 588 589
  /// that are found.
  ///
  /// Setting `nullOk` to true means that if no ambient [Actions] widget is
590 591 592 593 594 595 596
  /// found, then this method will return null instead of throwing.
  ///
  /// Returns the result of invoking the action's [Action.invoke] method. If
  /// no action mapping was found for the specified intent, or if the action
  /// that was found was disabled, then this returns null. Callers can detect
  /// whether or not the action is available (found, and not disabled) using
  /// [Actions.find] with its `nullOk` argument set to true.
597
  static Object invoke<T extends Intent>(
598
    BuildContext context,
599
    T intent, {
600 601 602
    bool nullOk = false,
  }) {
    assert(intent != null);
603 604 605 606
    assert(nullOk != null);
    assert(context != null);
    Action<T> action;
    InheritedElement actionElement;
607

608 609 610 611 612 613
    _visitActionsAncestors(context, (InheritedElement element) {
      final _ActionsMarker actions = element.widget as _ActionsMarker;
      final Action<T> result = actions.actions[intent.runtimeType] as Action<T>;
      if (result != null) {
        action = result;
        actionElement = element;
614 615
        return true;
      }
616 617
      return false;
    });
618 619 620 621 622 623

    assert(() {
      if (nullOk) {
        return true;
      }
      if (action == null) {
624 625 626 627 628 629
        throw FlutterError('Unable to find an action for an Intent with type '
            '${intent.runtimeType} in an $Actions widget in the given context.\n'
            '$Actions.invoke() was unable to find an $Actions widget that '
            "contained a mapping for the given intent, or the intent type isn't the "
            'same as the type argument to invoke (which is $T - try supplying a '
            'type argument to invoke if one was not given)\n'
630 631
            'The context used was:\n'
            '  $context\n'
632 633
            'The intent type requested was:\n'
            '  ${intent.runtimeType}');
634 635 636
      }
      return true;
    }());
637 638
    // Invoke the action we found using the relevant dispatcher from the Actions
    // Element we found.
639
    return actionElement != null ? _findDispatcher(actionElement).invokeAction(action, intent, context) : null;
640 641 642
  }

  @override
643
  State<Actions> createState() => _ActionsState();
644 645 646 647 648

  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DiagnosticsProperty<ActionDispatcher>('dispatcher', dispatcher));
649 650 651 652 653
    properties.add(DiagnosticsProperty<Map<Type, Action<Intent>>>('actions', actions));
  }
}

class _ActionsState extends State<Actions> {
654 655 656 657
  // The set of actions that this Actions widget is current listening to.
  Set<Action<Intent>> listenedActions = <Action<Intent>>{};
  // Used to tell the marker to rebuild its dependencies when the state of an
  // action in the map changes.
658 659 660 661 662 663 664 665 666
  Object rebuildKey = Object();

  @override
  void initState() {
    super.initState();
    _updateActionListeners();
  }

  void _handleActionChanged(Action<Intent> action) {
667 668 669 670
    // Generate a new key so that the marker notifies dependents.
    setState(() {
      rebuildKey = Object();
    });
671 672 673
  }

  void _updateActionListeners() {
674 675 676 677 678 679
    final Set<Action<Intent>> widgetActions = widget.actions.values.toSet();
    final Set<Action<Intent>> removedActions = listenedActions.difference(widgetActions);
    final Set<Action<Intent>> addedActions = widgetActions.difference(listenedActions);

    for (final Action<Intent> action in removedActions) {
      action.removeActionListener(_handleActionChanged);
680
    }
681 682
    for (final Action<Intent> action in addedActions) {
      action.addActionListener(_handleActionChanged);
683
    }
684
    listenedActions = widgetActions;
685 686 687 688 689 690 691 692 693 694 695
  }

  @override
  void didUpdateWidget(Actions oldWidget) {
    super.didUpdateWidget(oldWidget);
    _updateActionListeners();
  }

  @override
  void dispose() {
    super.dispose();
696
    for (final Action<Intent> action in listenedActions) {
697 698
      action.removeActionListener(_handleActionChanged);
    }
699
    listenedActions = null;
700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734
  }

  @override
  Widget build(BuildContext context) {
    return _ActionsMarker(
      actions: widget.actions,
      dispatcher: widget.dispatcher,
      rebuildKey: rebuildKey,
      child: widget.child,
    );
  }
}

// An inherited widget used by Actions widget for fast lookup of the Actions
// widget information.
class _ActionsMarker extends InheritedWidget {
  const _ActionsMarker({
    @required this.dispatcher,
    @required this.actions,
    @required this.rebuildKey,
    Key key,
    @required Widget child,
  })  : assert(child != null),
        assert(actions != null),
        super(key: key, child: child);

  final ActionDispatcher dispatcher;
  final Map<Type, Action<Intent>> actions;
  final Object rebuildKey;

  @override
  bool updateShouldNotify(_ActionsMarker oldWidget) {
    return rebuildKey != oldWidget.rebuildKey
        || oldWidget.dispatcher != dispatcher
        || !mapEquals<Type, Action<Intent>>(oldWidget.actions, actions);
735 736
  }
}
737

738 739 740 741 742 743 744 745 746 747
/// A widget that combines the functionality of [Actions], [Shortcuts],
/// [MouseRegion] and a [Focus] widget to create a detector that defines actions
/// and key bindings, and provides callbacks for handling focus and hover
/// highlights.
///
/// This widget can be used to give a control the required detection modes for
/// focus and hover handling. It is most often used when authoring a new control
/// widget, and the new control should be enabled for keyboard traversal and
/// activation.
///
748
/// {@tool dartpad --template=stateful_widget_material}
749 750
/// This example shows how keyboard interaction can be added to a custom control
/// that changes color when hovered and focused, and can toggle a light when
751 752 753
/// activated, either by touch or by hitting the `X` key on the keyboard when
/// the "And Me" button has the keyboard focus (be sure to use TAB to move the
/// focus to the "And Me" button before trying it out).
754 755 756 757
///
/// This example defines its own key binding for the `X` key, but in this case,
/// there is also a default key binding for [ActivateAction] in the default key
/// bindings created by [WidgetsApp] (the parent for [MaterialApp], and
758
/// [CupertinoApp]), so the `ENTER` key will also activate the buttons.
759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778
///
/// ```dart imports
/// import 'package:flutter/services.dart';
/// ```
///
/// ```dart preamble
/// class FadButton extends StatefulWidget {
///   const FadButton({Key key, this.onPressed, this.child}) : super(key: key);
///
///   final VoidCallback onPressed;
///   final Widget child;
///
///   @override
///   _FadButtonState createState() => _FadButtonState();
/// }
///
/// class _FadButtonState extends State<FadButton> {
///   bool _focused = false;
///   bool _hovering = false;
///   bool _on = false;
779
///   Map<Type, Action<Intent>> _actionMap;
780 781 782 783 784
///   Map<LogicalKeySet, Intent> _shortcutMap;
///
///   @override
///   void initState() {
///     super.initState();
785 786 787 788
///     _actionMap = <Type, Action<Intent>>{
///       ActivateIntent: CallbackAction(
///         onInvoke: (Intent intent) => _toggleState(),
///       ),
789 790
///     };
///     _shortcutMap = <LogicalKeySet, Intent>{
791
///       LogicalKeySet(LogicalKeyboardKey.keyX): const ActivateIntent(),
792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865
///     };
///   }
///
///   Color get color {
///     Color baseColor = Colors.lightBlue;
///     if (_focused) {
///       baseColor = Color.alphaBlend(Colors.black.withOpacity(0.25), baseColor);
///     }
///     if (_hovering) {
///       baseColor = Color.alphaBlend(Colors.black.withOpacity(0.1), baseColor);
///     }
///     return baseColor;
///   }
///
///   void _toggleState() {
///     setState(() {
///       _on = !_on;
///     });
///   }
///
///   void _handleFocusHighlight(bool value) {
///     setState(() {
///       _focused = value;
///     });
///   }
///
///   void _handleHoveHighlight(bool value) {
///     setState(() {
///       _hovering = value;
///     });
///   }
///
///   @override
///   Widget build(BuildContext context) {
///     return GestureDetector(
///       onTap: _toggleState,
///       child: FocusableActionDetector(
///         actions: _actionMap,
///         shortcuts: _shortcutMap,
///         onShowFocusHighlight: _handleFocusHighlight,
///         onShowHoverHighlight: _handleHoveHighlight,
///         child: Row(
///           children: <Widget>[
///             Container(
///               padding: EdgeInsets.all(10.0),
///               color: color,
///               child: widget.child,
///             ),
///             Container(
///               width: 30,
///               height: 30,
///               margin: EdgeInsets.all(10.0),
///               color: _on ? Colors.red : Colors.transparent,
///             ),
///           ],
///         ),
///       ),
///     );
///   }
/// }
/// ```
///
/// ```dart
/// Widget build(BuildContext context) {
///   return Scaffold(
///     appBar: AppBar(
///       title: Text('FocusableActionDetector Example'),
///     ),
///     body: Center(
///       child: Row(
///         mainAxisAlignment: MainAxisAlignment.center,
///         children: <Widget>[
///           Padding(
///             padding: const EdgeInsets.all(8.0),
866
///             child: TextButton(onPressed: () {}, child: Text('Press Me')),
867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886
///           ),
///           Padding(
///             padding: const EdgeInsets.all(8.0),
///             child: FadButton(onPressed: () {}, child: Text('And Me')),
///           ),
///         ],
///       ),
///     ),
///   );
/// }
/// ```
/// {@end-tool}
///
/// This widget doesn't have any visual representation, it is just a detector that
/// provides focus and hover capabilities.
///
/// It hosts its own [FocusNode] or uses [focusNode], if given.
class FocusableActionDetector extends StatefulWidget {
  /// Create a const [FocusableActionDetector].
  ///
887
  /// The [enabled], [autofocus], [mouseCursor], and [child] arguments must not be null.
888 889 890 891 892 893 894 895 896 897
  const FocusableActionDetector({
    Key key,
    this.enabled = true,
    this.focusNode,
    this.autofocus = false,
    this.shortcuts,
    this.actions,
    this.onShowFocusHighlight,
    this.onShowHoverHighlight,
    this.onFocusChange,
898
    this.mouseCursor = MouseCursor.defer,
899 900 901
    @required this.child,
  })  : assert(enabled != null),
        assert(autofocus != null),
902
        assert(mouseCursor != null),
903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921
        assert(child != null),
        super(key: key);

  /// Is this widget enabled or not.
  ///
  /// If disabled, will not send any notifications needed to update highlight or
  /// focus state, and will not define or respond to any actions or shortcuts.
  ///
  /// When disabled, adds [Focus] to the widget tree, but sets
  /// [Focus.canRequestFocus] to false.
  final bool enabled;

  /// {@macro flutter.widgets.Focus.focusNode}
  final FocusNode focusNode;

  /// {@macro flutter.widgets.Focus.autofocus}
  final bool autofocus;

  /// {@macro flutter.widgets.actions.actions}
922
  final Map<Type, Action<Intent>> actions;
923 924 925 926

  /// {@macro flutter.widgets.shortcuts.shortcuts}
  final Map<LogicalKeySet, Intent> shortcuts;

927 928 929 930
  /// A function that will be called when the focus highlight should be shown or
  /// hidden.
  ///
  /// This method is not triggered at the unmount of the widget.
931 932 933
  final ValueChanged<bool> onShowFocusHighlight;

  /// A function that will be called when the hover highlight should be shown or hidden.
934 935
  ///
  /// This method is not triggered at the unmount of the widget.
936 937 938 939 940 941 942
  final ValueChanged<bool> onShowHoverHighlight;

  /// A function that will be called when the focus changes.
  ///
  /// Called with true if the [focusNode] has primary focus.
  final ValueChanged<bool> onFocusChange;

943 944 945
  /// The cursor for a mouse pointer when it enters or is hovering over the
  /// widget.
  ///
946
  /// The [mouseCursor] defaults to [MouseCursor.defer], deferring the choice of
947
  /// cursor to the next region behind it in hit-test order.
948 949
  final MouseCursor mouseCursor;

950 951 952 953 954 955 956 957 958 959 960 961 962
  /// The child widget for this [FocusableActionDetector] widget.
  ///
  /// {@macro flutter.widgets.child}
  final Widget child;

  @override
  _FocusableActionDetectorState createState() => _FocusableActionDetectorState();
}

class _FocusableActionDetectorState extends State<FocusableActionDetector> {
  @override
  void initState() {
    super.initState();
963 964 965
    SchedulerBinding.instance.addPostFrameCallback((Duration duration) {
      _updateHighlightMode(FocusManager.instance.highlightMode);
    });
966 967 968 969 970 971 972 973 974 975 976
    FocusManager.instance.addHighlightModeListener(_handleFocusHighlightModeChange);
  }

  @override
  void dispose() {
    FocusManager.instance.removeHighlightModeListener(_handleFocusHighlightModeChange);
    super.dispose();
  }

  bool _canShowHighlight = false;
  void _updateHighlightMode(FocusHighlightMode mode) {
977 978 979 980 981 982 983 984 985 986
    _mayTriggerCallback(task: () {
      switch (FocusManager.instance.highlightMode) {
        case FocusHighlightMode.touch:
          _canShowHighlight = false;
          break;
        case FocusHighlightMode.traditional:
          _canShowHighlight = true;
          break;
      }
    });
987 988
  }

989 990 991 992
  // Have to have this separate from the _updateHighlightMode because it gets
  // called in initState, where things aren't mounted yet.
  // Since this method is a highlight mode listener, it is only called
  // immediately following pointer events.
993 994 995 996 997 998 999 1000 1001 1002
  void _handleFocusHighlightModeChange(FocusHighlightMode mode) {
    if (!mounted) {
      return;
    }
    _updateHighlightMode(mode);
  }

  bool _hovering = false;
  void _handleMouseEnter(PointerEnterEvent event) {
    if (!_hovering) {
1003 1004 1005
      _mayTriggerCallback(task: () {
        _hovering = true;
      });
1006 1007 1008 1009 1010
    }
  }

  void _handleMouseExit(PointerExitEvent event) {
    if (_hovering) {
1011 1012 1013
      _mayTriggerCallback(task: () {
        _hovering = false;
      });
1014 1015 1016 1017 1018 1019
    }
  }

  bool _focused = false;
  void _handleFocusChange(bool focused) {
    if (_focused != focused) {
1020
      _mayTriggerCallback(task: () {
1021 1022
        _focused = focused;
      });
1023
      widget.onFocusChange?.call(_focused);
1024 1025 1026
    }
  }

1027 1028 1029 1030 1031 1032 1033 1034 1035 1036
  // Record old states, do `task` if not null, then compare old states with the
  // new states, and trigger callbacks if necessary.
  //
  // The old states are collected from `oldWidget` if it is provided, or the
  // current widget (before doing `task`) otherwise. The new states are always
  // collected from the current widget.
  void _mayTriggerCallback({VoidCallback task, FocusableActionDetector oldWidget}) {
    bool shouldShowHoverHighlight(FocusableActionDetector target) {
      return _hovering && target.enabled && _canShowHighlight;
    }
1037

1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049
    bool canRequestFocus(FocusableActionDetector target) {
      final NavigationMode mode = MediaQuery.of(context, nullOk: true)?.navigationMode ?? NavigationMode.traditional;
      switch (mode) {
        case NavigationMode.traditional:
          return target.enabled;
        case NavigationMode.directional:
          return true;
      }
      assert(false, 'Navigation mode $mode not handled');
      return null;
    }

1050
    bool shouldShowFocusHighlight(FocusableActionDetector target) {
1051
      return _focused && _canShowHighlight && canRequestFocus(target);
1052 1053 1054 1055 1056 1057
    }

    assert(SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks);
    final FocusableActionDetector oldTarget = oldWidget ?? widget;
    final bool didShowHoverHighlight = shouldShowHoverHighlight(oldTarget);
    final bool didShowFocusHighlight = shouldShowFocusHighlight(oldTarget);
1058
    if (task != null) {
1059
      task();
1060
    }
1061 1062
    final bool doShowHoverHighlight = shouldShowHoverHighlight(widget);
    final bool doShowFocusHighlight = shouldShowFocusHighlight(widget);
1063
    if (didShowFocusHighlight != doShowFocusHighlight) {
1064
      widget.onShowFocusHighlight?.call(doShowFocusHighlight);
1065 1066
    }
    if (didShowHoverHighlight != doShowHoverHighlight) {
1067
      widget.onShowHoverHighlight?.call(doShowHoverHighlight);
1068
    }
1069 1070
  }

1071 1072 1073 1074 1075 1076 1077 1078
  @override
  void didUpdateWidget(FocusableActionDetector oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.enabled != oldWidget.enabled) {
      SchedulerBinding.instance.addPostFrameCallback((Duration duration) {
        _mayTriggerCallback(oldWidget: oldWidget);
      });
    }
1079 1080
  }

1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092
  bool get _canRequestFocus {
    final NavigationMode mode = MediaQuery.of(context, nullOk: true)?.navigationMode ?? NavigationMode.traditional;
    switch (mode) {
      case NavigationMode.traditional:
        return widget.enabled;
      case NavigationMode.directional:
        return true;
    }
    assert(false, 'NavigationMode $mode not handled.');
    return null;
  }

1093 1094 1095 1096 1097
  @override
  Widget build(BuildContext context) {
    Widget child = MouseRegion(
      onEnter: _handleMouseEnter,
      onExit: _handleMouseExit,
1098
      cursor: widget.mouseCursor,
1099 1100 1101
      child: Focus(
        focusNode: widget.focusNode,
        autofocus: widget.autofocus,
1102
        canRequestFocus: _canRequestFocus,
1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116
        onFocusChange: _handleFocusChange,
        child: widget.child,
      ),
    );
    if (widget.enabled && widget.actions != null && widget.actions.isNotEmpty) {
      child = Actions(actions: widget.actions, child: child);
    }
    if (widget.enabled && widget.shortcuts != null && widget.shortcuts.isNotEmpty) {
      child = Shortcuts(shortcuts: widget.shortcuts, child: child);
    }
    return child;
  }
}

1117 1118 1119 1120
/// An [Intent], that, as the name implies, is bound to a [DoNothingAction].
///
/// Attaching a [DoNothingIntent] to a [Shortcuts] mapping is one way to disable
/// a keyboard shortcut defined by a widget higher in the widget hierarchy.
1121
///
1122 1123 1124 1125
/// This intent cannot be subclassed.
class DoNothingIntent extends Intent {
  /// Creates a const [DoNothingIntent].
  factory DoNothingIntent() => const DoNothingIntent._();
1126

1127 1128 1129
  // Make DoNothingIntent constructor private so it can't be subclassed.
  const DoNothingIntent._();
}
1130

1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141
/// An [Action], that, as the name implies, does nothing.
///
/// Attaching a [DoNothingAction] to an [Actions] mapping is one way to disable
/// an action defined by a widget higher in the widget hierarchy.
///
/// This action can be bound to any intent.
///
/// See also:
///  - [DoNothingIntent], which is an intent that can be bound to a keystroke in
///    a [Shortcuts] widget to do nothing.
class DoNothingAction extends Action<Intent> {
1142
  @override
1143 1144 1145 1146 1147 1148 1149
  void invoke(Intent intent) {}
}

/// An intent that activates the currently focused control.
class ActivateIntent extends Intent {
  /// Creates a const [ActivateIntent] so subclasses can be const.
  const ActivateIntent();
1150
}
1151

1152
/// An action that activates the currently focused control.
1153 1154
///
/// This is an abstract class that serves as a base class for actions that
1155 1156 1157 1158 1159 1160 1161
/// activate a control. By default, is bound to [LogicalKeyboardKey.enter],
/// [LogicalKeyboardKey.gameButtonA], and [LogicalKeyboardKey.space] in the
/// default keyboard map in [WidgetsApp].
abstract class ActivateAction extends Action<ActivateIntent> {}

/// An intent that selects the currently focused control.
class SelectIntent extends Intent {}
1162 1163 1164 1165

/// An action that selects the currently focused control.
///
/// This is an abstract class that serves as a base class for actions that
1166
/// select something. It is not bound to any key by default.
1167
abstract class SelectAction extends Action<SelectIntent> {}
1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185

/// An [Intent] that dismisses the currently focused widget.
///
/// The [WidgetsApp.defaultShortcuts] binds this intent to the
/// [LogicalKeyboardKey.escape] and [LogicalKeyboardKey.gameButtonB] keys.
///
/// See also:
///  - [ModalRoute] which listens for this intent to dismiss modal routes
///    (dialogs, pop-up menus, drawers, etc).
class DismissIntent extends Intent {
  /// Creates a const [DismissIntent].
  const DismissIntent();
}

/// An action that dismisses the focused widget.
///
/// This is an abstract class that serves as a base class for dismiss actions.
abstract class DismissAction extends Action<DismissIntent> {}