From d9da7c5faadcc2e92f80a76db1f838b975f6e331 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Sharma?= <737941+loic-sharma@users.noreply.github.com> Date: Tue, 28 Mar 2023 09:47:06 -0700 Subject: [PATCH] [Shortcuts] Improve documentation (#123499) [Shortcuts] Improve documentation --- packages/flutter/lib/src/widgets/actions.dart | 33 ++++++++------- .../flutter/lib/src/widgets/shortcuts.dart | 41 +++++++++++-------- 2 files changed, 42 insertions(+), 32 deletions(-) diff --git a/packages/flutter/lib/src/widgets/actions.dart b/packages/flutter/lib/src/widgets/actions.dart index 81b58eb5bc8b..ab746a0e6cde 100644 --- a/packages/flutter/lib/src/widgets/actions.dart +++ b/packages/flutter/lib/src/widgets/actions.dart @@ -43,6 +43,8 @@ BuildContext _getParent(BuildContext context) { /// /// See also: /// +/// * [Shortcuts], a widget used to bind key combinations to [Intent]s. +/// * [Actions], a widget used to map [Intent]s to [Action]s. /// * [Actions.invoke], which invokes the action associated with a specified /// [Intent] using the [Actions] widget that most tightly encloses the given /// [BuildContext]. @@ -67,13 +69,14 @@ abstract class Intent with Diagnosticable { /// To register an action listener, call [Action.addActionListener]. typedef ActionListenerCallback = void Function(Action action); -/// Base class for actions. +/// Base class for an action or command to be performed. +/// +/// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM} /// -/// 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. +/// [Action]s are typically invoked as a result of a user action. For example, +/// the [Shortcuts] widget will map a keyboard shortcut into 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. @@ -612,13 +615,13 @@ class ActionDispatcher with Diagnosticable { } } -/// A widget that establishes an [ActionDispatcher] and a map of [Intent] to -/// [Action] to be used by its descendants when invoking an [Action]. +/// A widget that maps [Intent]s to [Action]s to be used by its descendants +/// when invoking an [Action]. /// /// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM} /// -/// Actions are typically invoked using [Actions.invoke] with the context -/// containing the ambient [Actions] widget. +/// Actions are typically invoked using [Shortcuts]. They can also be invoked +/// using [Actions.invoke] on a context containing an ambient [Actions] widget. /// /// {@tool dartpad} /// This example creates a custom [Action] subclass `ModifyAction` for modifying @@ -641,12 +644,12 @@ class ActionDispatcher with Diagnosticable { /// /// See also: /// -/// * [ActionDispatcher], the object that this widget uses to manage actions. +/// * [Shortcuts], a widget used to bind key combinations to [Intent]s. +/// * [Intent], a class that contains configuration information for running an +/// [Action]. /// * [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. +/// * [ActionDispatcher], the object that this widget uses to manage actions. class Actions extends StatefulWidget { /// Creates an [Actions] widget. /// @@ -664,7 +667,7 @@ class Actions extends StatefulWidget { /// /// 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 + /// set. If no such widget is found, then they will return/use a /// default-constructed [ActionDispatcher]. final ActionDispatcher? dispatcher; diff --git a/packages/flutter/lib/src/widgets/shortcuts.dart b/packages/flutter/lib/src/widgets/shortcuts.dart index 5873c679e08d..d5a5998ef88b 100644 --- a/packages/flutter/lib/src/widgets/shortcuts.dart +++ b/packages/flutter/lib/src/widgets/shortcuts.dart @@ -869,6 +869,13 @@ class ShortcutManager with Diagnosticable, ChangeNotifier { /// when invoking an [Action] via a keyboard key combination that maps to an /// [Intent]. /// +/// This is similar to but more powerful than the [CallbackShortcuts] widget. +/// Unlike [CallbackShortcuts], this widget separates key bindings and their +/// implementations. This separation allows [Shortcuts] to have key bindings +/// that adapt to the focused context. For example, the desired action for a +/// deletion intent may be to delete a character in a text input, or to delete +/// a file in a file menu. +/// /// See the article on [Using Actions and /// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts) /// for a detailed explanation. @@ -903,8 +910,8 @@ class ShortcutManager with Diagnosticable, ChangeNotifier { /// /// See also: /// -/// * [CallbackShortcuts], a less complicated (but less flexible) way of -/// defining key bindings that just invoke callbacks. +/// * [CallbackShortcuts], a simpler but less flexible widget that defines key +/// bindings that invoke callbacks. /// * [Intent], a class for containing a description of a user action to be /// invoked. /// * [Action], a class for defining an invocation of a user action. @@ -1038,32 +1045,32 @@ class _ShortcutsState extends State { } } -/// A widget that provides an uncomplicated mechanism for binding a key -/// combination to a specific callback. -/// -/// This is similar to the functionality provided by the [Shortcuts] widget, but -/// instead of requiring a mapping to an [Intent], and an [Actions] widget -/// somewhere in the widget tree to bind the [Intent] to, it just takes a set of -/// bindings that bind the key combination directly to a [VoidCallback]. +/// A widget that binds key combinations to specific callbacks. /// -/// Because it is a simpler mechanism, it doesn't provide the ability to disable -/// the callbacks, or to separate the definition of the shortcuts from the -/// definition of the code that is triggered by them (the role that actions play -/// in the [Shortcuts]/[Actions] system). +/// This is similar to but simpler than the [Shortcuts] widget as it doesn't +/// require [Intent]s and [Actions] widgets. Instead, it accepts a map +/// of [ShortcutActivator]s to [VoidCallback]s. /// -/// However, for some applications the complexity and flexibility of the -/// [Shortcuts] and [Actions] mechanism is overkill, and this widget is here for -/// those apps. +/// Unlike [Shortcuts], this widget does not separate key bindings and their +/// implementations. This separation allows [Shortcuts] to have key bindings +/// that adapt to the focused context. For example, the desired action for a +/// deletion intent may be to delete a character in a text input, or to delete +/// a file in a file menu. /// /// [Shortcuts] and [CallbackShortcuts] can both be used in the same app. As /// with any key handling widget, if this widget handles a key event then /// widgets above it in the focus chain will not receive the event. This means /// that if this widget handles a key, then an ancestor [Shortcuts] widget (or -/// any other key handling widget) will not receive that key, and similarly, if +/// any other key handling widget) will not receive that key. Similarly, if /// a descendant of this widget handles the key, then the key event will not /// reach this widget for handling. /// +/// See the article on [Using Actions and +/// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts) +/// for a detailed explanation. +/// /// See also: +/// * [Shortcuts], a more powerful widget for defining key bindings. /// * [Focus], a widget that defines which widgets can receive keyboard focus. class CallbackShortcuts extends StatelessWidget { /// Creates a const [CallbackShortcuts] widget.