mirror of
https://github.com/flutter/flutter
synced 2024-08-27 20:10:11 +00:00
[Shortcuts] Improve documentation (#123499)
[Shortcuts] Improve documentation
This commit is contained in:
parent
3dfc60c0d1
commit
d9da7c5faa
|
@ -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<Intent> action);
|
||||
|
||||
/// Base class for actions.
|
||||
/// Base class for an action or command to be performed.
|
||||
///
|
||||
/// 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.
|
||||
/// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM}
|
||||
///
|
||||
/// [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;
|
||||
|
||||
|
|
|
@ -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<Shortcuts> {
|
|||
}
|
||||
}
|
||||
|
||||
/// A widget that provides an uncomplicated mechanism for binding a key
|
||||
/// combination to a specific callback.
|
||||
/// A widget that binds key combinations to specific callbacks.
|
||||
///
|
||||
/// 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].
|
||||
/// 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.
|
||||
///
|
||||
/// 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).
|
||||
///
|
||||
/// 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.
|
||||
|
|
Loading…
Reference in a new issue