Unverified Commit 638a9449 authored by Greg Spencer's avatar Greg Spencer Committed by GitHub

Fix doc warnings for focus code (#62602)

parent 87dbfa83
......@@ -975,7 +975,7 @@ class EditableText extends StatefulWidget {
/// {@tool dartpad --template=stateful_widget_material}
/// When a non-completion action is pressed, such as "next" or "previous", it
/// is often desirable to move the focus to the next or previous field. To do
/// this, handle it as in this example, by calling [FocusNode.focusNext] in
/// this, handle it as in this example, by calling [FocusNode.nextFocus] in
/// the `onFieldSubmitted` callback of [TextFormField]. ([TextFormField] wraps
/// [EditableText] internally, and uses the value of `onFieldSubmitted` as its
/// [onSubmitted]).
......
......@@ -196,9 +196,9 @@ enum UnfocusDisposition {
/// receive a notification when the focus changes. If the [Focus] and
/// [FocusScope] widgets are being used to manage the nodes, consider
/// establishing an [InheritedWidget] dependency on them by calling [Focus.of]
/// or [FocusScope.of] instead. [Focus.hasFocus] can also be used to establish a
/// similar dependency, especially if all that is needed is to determine whether
/// or not the widget is focused at build time.
/// or [FocusScope.of] instead. [FocusNode.hasFocus] can also be used to
/// establish a similar dependency, especially if all that is needed is to
/// determine whether or not the widget is focused at build time.
///
/// To see the focus tree in the debug console, call [debugDumpFocusTree]. To
/// get the focus tree as a string, call [debugDescribeFocusTree].
......@@ -224,12 +224,12 @@ enum UnfocusDisposition {
/// [FocusAttachment] object. This attachment is created by calling [attach],
/// usually from the [State.initState] method. If the hosting widget is updated
/// to have a different focus node, then the updated node needs to be attached
/// in [State.didUpdateWidget], after calling [detach] on the previous
/// [FocusAttachment].
/// in [State.didUpdateWidget], after calling [FocusAttachment.detach] on the
/// previous [FocusAttachment].
///
/// Because [FocusNode]s form a sparse representation of the widget tree,
/// they must be updated whenever the widget tree is rebuilt. This is done by
/// calling [FocusAttachment.reparent], usually from the [State.build] or
/// Because [FocusNode]s form a sparse representation of the widget tree, they
/// must be updated whenever the widget tree is rebuilt. This is done by calling
/// [FocusAttachment.reparent], usually from the [State.build] or
/// [State.didChangeDependencies] methods of the widget that represents the
/// focused region, so that the [BuildContext] assigned to the [FocusScopeNode]
/// can be tracked (the context is used to obtain the [RenderObject], from which
......@@ -241,9 +241,9 @@ enum UnfocusDisposition {
///
/// If, as is common, the hosting [StatefulWidget] is also the owner of the
/// focus node, then it will also call [dispose] from its [State.dispose] (in
/// which case the [detach] may be skipped, since dispose will automatically
/// detach). If another object owns the focus node, then it must call [dispose]
/// when the node is done being used.
/// which case the [FocusAttachment.detach] may be skipped, since dispose will
/// automatically detach). If another object owns the focus node, then it must
/// call [dispose] when the node is done being used.
/// {@endtemplate}
///
/// {@template flutter.widgets.focus_manager.focus.keyEvents}
......@@ -284,10 +284,10 @@ enum UnfocusDisposition {
/// [DirectionalFocusTraversalPolicyMixin], but custom policies can be built
/// based upon these policies. See [FocusTraversalPolicy] for more information.
///
/// {@tool dartpad --template=stateless_widget_scaffold}
/// This example shows how a FocusNode should be managed if not using the
/// [Focus] or [FocusScope] widgets. See the [Focus] widget for a similar
/// example using [Focus] and [FocusScope] widgets.
/// {@tool dartpad --template=stateless_widget_scaffold} This example shows how
/// a FocusNode should be managed if not using the [Focus] or [FocusScope]
/// widgets. See the [Focus] widget for a similar example using [Focus] and
/// [FocusScope] widgets.
///
/// ```dart imports
/// import 'package:flutter/services.dart';
......@@ -396,14 +396,14 @@ enum UnfocusDisposition {
///
/// See also:
///
/// * [Focus], a widget that manages a [FocusNode] and provides access to
/// focus information and actions to its descendant widgets.
/// * [FocusTraversalGroup], a widget used to group together and configure the
/// focus traversal policy for a widget subtree.
/// * [FocusManager], a singleton that manages the primary focus and
/// distributes key events to focused nodes.
/// * [FocusTraversalPolicy], a class used to determine how to move the focus
/// to other nodes.
/// * [Focus], a widget that manages a [FocusNode] and provides access to focus
/// information and actions to its descendant widgets.
/// * [FocusTraversalGroup], a widget used to group together and configure the
/// focus traversal policy for a widget subtree.
/// * [FocusManager], a singleton that manages the primary focus and distributes
/// key events to focused nodes.
/// * [FocusTraversalPolicy], a class used to determine how to move the focus to
/// other nodes.
class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
/// Creates a focus node.
///
......@@ -1039,10 +1039,10 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
/// will add the [node] as a child of this node before requesting focus.
///
/// If the given [node] is a [FocusScopeNode] and that focus scope node has a
/// non-null [focusedChild], then request the focus for the focused child.
/// This process is recursive and continues until it encounters either a focus
/// scope node with a null focused child or an ordinary (non-scope)
/// [FocusNode] is found.
/// non-null [FocusScopeNode.focusedChild], then request the focus for the
/// focused child. This process is recursive and continues until it encounters
/// either a focus scope node with a null focused child or an ordinary
/// (non-scope) [FocusNode] is found.
///
/// The node is notified that it has received the primary focus in a
/// microtask, so notification may lag the request by up to one frame.
......
......@@ -29,7 +29,7 @@ import 'inherited_notifier.dart';
/// changes, use the [Focus.of] and [FocusScope.of] static methods.
///
/// To access the focused state of the nearest [Focus] widget, use
/// [Focus.hasFocus] from a build method, which also establishes a relationship
/// [FocusNode.hasFocus] from a build method, which also establishes a relationship
/// between the calling widget and the [Focus] widget that will rebuild the
/// calling widget when the focus changes.
///
......@@ -364,16 +364,17 @@ class Focus extends StatefulWidget {
/// This is sometimes useful if a [Focus] widget should receive key events as
/// part of the focus chain, but shouldn't be accessible via focus traversal.
///
/// This is different from [canRequestFocus] because it only implies that the
/// widget can't be reached via traversal, not that it can't be focused. It may
/// still be focused explicitly.
/// This is different from [FocusNode.canRequestFocus] because it only implies
/// that the widget can't be reached via traversal, not that it can't be
/// focused. It may still be focused explicitly.
final bool skipTraversal;
/// {@template flutter.widgets.Focus.includeSemantics}
/// Include semantics information in this widget.
///
/// If true, this widget will include a [Semantics] node that
/// indicates the [Semantics.focusable] and [Semantics.focused] properties.
/// If true, this widget will include a [Semantics] node that indicates the
/// [SemanticsProperties.focusable] and [SemanticsProperties.focused]
/// properties.
///
/// It is not typical to set this to false, as that can affect the semantics
/// information available to accessibility systems.
......@@ -386,22 +387,22 @@ class Focus extends StatefulWidget {
/// If true, this widget may request the primary focus.
///
/// Defaults to true. Set to false if you want the [FocusNode] this widget
/// manages to do nothing when [requestFocus] is called on it. Does not affect
/// the children of this node, and [FocusNode.hasFocus] can still return true
/// if this node is the ancestor of the primary focus.
/// manages to do nothing when [FocusNode.requestFocus] is called on it. Does
/// not affect the children of this node, and [FocusNode.hasFocus] can still
/// return true if this node is the ancestor of the primary focus.
///
/// This is different than [skipTraversal] because [skipTraversal] still
/// allows the widget to be focused, just not traversed to.
/// This is different than [Focus.skipTraversal] because [Focus.skipTraversal]
/// still allows the widget to be focused, just not traversed to.
///
/// Setting [canRequestFocus] to false implies that the widget will also be
/// skipped for traversal purposes.
/// Setting [FocusNode.canRequestFocus] to false implies that the widget will
/// also be skipped for traversal purposes.
///
/// See also:
///
/// * [FocusTraversalGroup], a widget that sets the traversal policy for
/// its descendants.
/// * [FocusTraversalPolicy], a class that can be extended to describe a
/// traversal policy.
/// * [FocusTraversalGroup], a widget that sets the traversal policy for its
/// descendants.
/// * [FocusTraversalPolicy], a class that can be extended to describe a
/// traversal policy.
/// {@endtemplate}
final bool canRequestFocus;
......@@ -409,22 +410,23 @@ class Focus extends StatefulWidget {
/// If false, will make this widget's descendants unfocusable.
///
/// Defaults to true. Does not affect focusability of this node (just its
/// descendants): for that, use [canRequestFocus].
/// descendants): for that, use [FocusNode.canRequestFocus].
///
/// If any descendants are focused when this is set to false, they will be
/// unfocused. When `descendantsAreFocusable` is set to true again, they will
/// not be refocused, although they will be able to accept focus again.
///
/// Does not affect the value of [canRequestFocus] on the descendants.
/// Does not affect the value of [FocusNode.canRequestFocus] on the
/// descendants.
///
/// See also:
///
/// * [ExcludeFocus], a widget that uses this property to conditionally
/// exclude focus for a subtree.
/// * [FocusTraversalGroup], a widget used to group together and configure
/// the focus traversal policy for a widget subtree that has a
/// `descendantsAreFocusable` parameter to conditionally block focus for a
/// subtree.
/// * [ExcludeFocus], a widget that uses this property to conditionally
/// exclude focus for a subtree.
/// * [FocusTraversalGroup], a widget used to group together and configure the
/// focus traversal policy for a widget subtree that has a
/// `descendantsAreFocusable` parameter to conditionally block focus for a
/// subtree.
/// {@endtemplate}
final bool descendantsAreFocusable;
......@@ -870,7 +872,7 @@ class FocusScope extends Focus {
///
/// The [child] argument is required and must not be null.
///
/// The [autofocus], and [showDecorations] arguments must not be null.
/// The [autofocus] argument must not be null.
const FocusScope({
Key key,
FocusScopeNode node,
......@@ -979,16 +981,17 @@ class ExcludeFocus extends StatelessWidget {
/// unfocused. When `excluding` is set to false again, they will not be
/// refocused, although they will be able to accept focus again.
///
/// Does not affect the value of [canRequestFocus] on the descendants.
/// Does not affect the value of [FocusNode.canRequestFocus] on the
/// descendants.
///
/// See also:
///
/// * [Focus.descendantsAreFocusable], the attribute of a [Focus] widget that
/// controls this same property for focus widgets.
/// * [FocusTraversalGroup], a widget used to group together and configure
/// the focus traversal policy for a widget subtree that has a
/// `descendantsAreFocusable` parameter to conditionally block focus for a
/// subtree.
/// * [Focus.descendantsAreFocusable], the attribute of a [Focus] widget that
/// controls this same property for focus widgets.
/// * [FocusTraversalGroup], a widget used to group together and configure the
/// focus traversal policy for a widget subtree that has a
/// `descendantsAreFocusable` parameter to conditionally block focus for a
/// subtree.
final bool excluding;
/// The child widget of this [ExcludeFocus].
......
......@@ -64,8 +64,8 @@ class _FocusTraversalGroupInfo {
/// A direction along either the horizontal or vertical axes.
///
/// This is used by the [DirectionalFocusTraversalPolicyMixin], and
/// [Focus.focusInDirection] to indicate which direction to look in for the next
/// focus.
/// [FocusNode.focusInDirection] to indicate which direction to look in for the
/// next focus.
enum TraversalDirection {
/// Indicates a direction above the currently focused widget.
up,
......@@ -433,7 +433,7 @@ class _DirectionalPolicyData {
///
/// Since hysteresis in the navigation order is undesirable, this implementation
/// maintains a stack of previous locations that have been visited on the
/// [policyData] for the affected [FocusScopeNode]. If the previous direction
/// policy data for the affected [FocusScopeNode]. If the previous direction
/// was the opposite of the current direction, then the this policy will request
/// focus on the previously focused node. Change to another direction other than
/// the current one or its opposite will clear the stack.
......@@ -682,7 +682,7 @@ mixin DirectionalFocusTraversalPolicyMixin on FocusTraversalPolicy {
/// Returns true if it successfully found a node and requested focus.
///
/// Maintains a stack of previous locations that have been visited on the
/// [policyData] for the affected [FocusScopeNode]. If the previous direction
/// policy data for the affected [FocusScopeNode]. If the previous direction
/// was the opposite of the current direction, then the this policy will
/// request focus on the previously focused node. Change to another direction
/// other than the current one or its opposite will clear the stack.
......@@ -1122,25 +1122,26 @@ class ReadingOrderTraversalPolicy extends FocusTraversalPolicy with DirectionalF
///
/// {@template flutter.widgets.focusorder.comparable}
/// Only orders of the same type are comparable. If a set of widgets in the same
/// [FocusTraversalGroup] contains orders that are not comparable with each other, it
/// will assert, since the ordering between such keys is undefined. To avoid
/// collisions, use a [FocusTraversalGroup] to group similarly ordered widgets
/// together.
///
/// When overriding, [doCompare] must be overridden instead of [compareTo],
/// which calls [doCompare] to do the actual comparison.
/// [FocusTraversalGroup] contains orders that are not comparable with each
/// other, it will assert, since the ordering between such keys is undefined. To
/// avoid collisions, use a [FocusTraversalGroup] to group similarly ordered
/// widgets together.
///
/// When overriding, [FocusOrder.doCompare] must be overridden instead of
/// [FocusOrder.compareTo], which calls [FocusOrder.doCompare] to do the actual
/// comparison.
/// {@endtemplate}
///
/// See also:
///
/// * [FocusTraversalGroup], a widget that groups together and imposes a
/// traversal policy on the [Focus] nodes below it in the widget hierarchy.
/// * [FocusTraversalOrder], a widget that assigns an order to a widget subtree
/// for the [OrderedTraversalPolicy] to use.
/// * [NumericFocusOrder], for a focus order that describes its order with a
/// `double`.
/// * [LexicalFocusOrder], a focus order that assigns a string-based lexical
/// traversal order to a [FocusTraversalOrder] widget.
/// * [FocusTraversalGroup], a widget that groups together and imposes a
/// traversal policy on the [Focus] nodes below it in the widget hierarchy.
/// * [FocusTraversalOrder], a widget that assigns an order to a widget subtree
/// for the [OrderedTraversalPolicy] to use.
/// * [NumericFocusOrder], for a focus order that describes its order with a
/// `double`.
/// * [LexicalFocusOrder], a focus order that assigns a string-based lexical
/// traversal order to a [FocusTraversalOrder] widget.
@immutable
abstract class FocusOrder with Diagnosticable implements Comparable<FocusOrder> {
/// Abstract const constructor. This constructor enables subclasses to provide
......
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