Unverified Commit d9da7c5f authored by Loïc Sharma's avatar Loïc Sharma Committed by GitHub

[Shortcuts] Improve documentation (#123499)

[Shortcuts] Improve documentation
parent 3dfc60c0
...@@ -43,6 +43,8 @@ BuildContext _getParent(BuildContext context) { ...@@ -43,6 +43,8 @@ BuildContext _getParent(BuildContext context) {
/// ///
/// See also: /// 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 /// * [Actions.invoke], which invokes the action associated with a specified
/// [Intent] using the [Actions] widget that most tightly encloses the given /// [Intent] using the [Actions] widget that most tightly encloses the given
/// [BuildContext]. /// [BuildContext].
...@@ -67,13 +69,14 @@ abstract class Intent with Diagnosticable { ...@@ -67,13 +69,14 @@ abstract class Intent with Diagnosticable {
/// To register an action listener, call [Action.addActionListener]. /// To register an action listener, call [Action.addActionListener].
typedef ActionListenerCallback = void Function(Action<Intent> action); typedef ActionListenerCallback = void Function(Action<Intent> 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. /// [Action]s are typically invoked as a result of a user action. For example,
/// They are typically invoked as a result of a user action, such as a keyboard /// the [Shortcuts] widget will map a keyboard shortcut into an [Intent], which
/// shortcut in a [Shortcuts] widget, which is used to look up an [Intent], /// is given to an [ActionDispatcher] to map the [Intent] to an [Action] and
/// which is given to an [ActionDispatcher] to map the [Intent] to an [Action] /// invoke it.
/// and invoke it.
/// ///
/// The [ActionDispatcher] can invoke an [Action] on the primary focus, or /// The [ActionDispatcher] can invoke an [Action] on the primary focus, or
/// without regard for focus. /// without regard for focus.
...@@ -612,13 +615,13 @@ class ActionDispatcher with Diagnosticable { ...@@ -612,13 +615,13 @@ class ActionDispatcher with Diagnosticable {
} }
} }
/// A widget that establishes an [ActionDispatcher] and a map of [Intent] to /// A widget that maps [Intent]s to [Action]s to be used by its descendants
/// [Action] to be used by its descendants when invoking an [Action]. /// when invoking an [Action].
/// ///
/// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM} /// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM}
/// ///
/// Actions are typically invoked using [Actions.invoke] with the context /// Actions are typically invoked using [Shortcuts]. They can also be invoked
/// containing the ambient [Actions] widget. /// using [Actions.invoke] on a context containing an ambient [Actions] widget.
/// ///
/// {@tool dartpad} /// {@tool dartpad}
/// This example creates a custom [Action] subclass `ModifyAction` for modifying /// This example creates a custom [Action] subclass `ModifyAction` for modifying
...@@ -641,12 +644,12 @@ class ActionDispatcher with Diagnosticable { ...@@ -641,12 +644,12 @@ class ActionDispatcher with Diagnosticable {
/// ///
/// See also: /// 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], a class for containing and defining an invocation of a user
/// action. /// action.
/// * [Intent], a class that holds a unique [LocalKey] identifying an action, /// * [ActionDispatcher], the object that this widget uses to manage actions.
/// as well as configuration information for running the [Action].
/// * [Shortcuts], a widget used to bind key combinations to [Intent]s.
class Actions extends StatefulWidget { class Actions extends StatefulWidget {
/// Creates an [Actions] widget. /// Creates an [Actions] widget.
/// ///
...@@ -664,7 +667,7 @@ class Actions extends StatefulWidget { ...@@ -664,7 +667,7 @@ class Actions extends StatefulWidget {
/// ///
/// If this [dispatcher] is null, then [Actions.of] and [Actions.invoke] will /// 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 /// 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]. /// default-constructed [ActionDispatcher].
final ActionDispatcher? dispatcher; final ActionDispatcher? dispatcher;
......
...@@ -869,6 +869,13 @@ class ShortcutManager with Diagnosticable, ChangeNotifier { ...@@ -869,6 +869,13 @@ class ShortcutManager with Diagnosticable, ChangeNotifier {
/// when invoking an [Action] via a keyboard key combination that maps to an /// when invoking an [Action] via a keyboard key combination that maps to an
/// [Intent]. /// [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 /// See the article on [Using Actions and
/// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts) /// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts)
/// for a detailed explanation. /// for a detailed explanation.
...@@ -903,8 +910,8 @@ class ShortcutManager with Diagnosticable, ChangeNotifier { ...@@ -903,8 +910,8 @@ class ShortcutManager with Diagnosticable, ChangeNotifier {
/// ///
/// See also: /// See also:
/// ///
/// * [CallbackShortcuts], a less complicated (but less flexible) way of /// * [CallbackShortcuts], a simpler but less flexible widget that defines key
/// defining key bindings that just invoke callbacks. /// bindings that invoke callbacks.
/// * [Intent], a class for containing a description of a user action to be /// * [Intent], a class for containing a description of a user action to be
/// invoked. /// invoked.
/// * [Action], a class for defining an invocation of a user action. /// * [Action], a class for defining an invocation of a user action.
...@@ -1038,32 +1045,32 @@ class _ShortcutsState extends State<Shortcuts> { ...@@ -1038,32 +1045,32 @@ class _ShortcutsState extends State<Shortcuts> {
} }
} }
/// A widget that provides an uncomplicated mechanism for binding a key /// A widget that binds key combinations to specific callbacks.
/// 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].
/// ///
/// Because it is a simpler mechanism, it doesn't provide the ability to disable /// This is similar to but simpler than the [Shortcuts] widget as it doesn't
/// the callbacks, or to separate the definition of the shortcuts from the /// require [Intent]s and [Actions] widgets. Instead, it accepts a map
/// definition of the code that is triggered by them (the role that actions play /// of [ShortcutActivator]s to [VoidCallback]s.
/// in the [Shortcuts]/[Actions] system).
/// ///
/// However, for some applications the complexity and flexibility of the /// Unlike [Shortcuts], this widget does not separate key bindings and their
/// [Shortcuts] and [Actions] mechanism is overkill, and this widget is here for /// implementations. This separation allows [Shortcuts] to have key bindings
/// those apps. /// 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 /// [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 /// 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 /// 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 /// 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 /// a descendant of this widget handles the key, then the key event will not
/// reach this widget for handling. /// 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: /// See also:
/// * [Shortcuts], a more powerful widget for defining key bindings.
/// * [Focus], a widget that defines which widgets can receive keyboard focus. /// * [Focus], a widget that defines which widgets can receive keyboard focus.
class CallbackShortcuts extends StatelessWidget { class CallbackShortcuts extends StatelessWidget {
/// Creates a const [CallbackShortcuts] widget. /// Creates a const [CallbackShortcuts] widget.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment