Copy edit on Focus page #10432
Copy edit on Focus page #10432
Conversation
atsansone
requested review from
sfshaza2,
parlough,
domesticmouse and
MaryaBelanger
as code owners
|
Visit the preview URL for this PR (updated for commit f64e8c4): https://flutter-docs-prod--pr10432-fix-10168-g1r5uhxa.web.app |
There was a problem hiding this comment.
I'm having problems with some of the new sections of this page. Meanings of some terms have subtly changed and, in some cases, concepts seem less clear. @gspencergoog, can you please take a look?
| This system directs keyboard input to a particular part of an app. | ||
| To "focus" the input to part of an app, | ||
| users tap or click on the desired UI element. | ||
| Once in focus, text entered with the keyboard appears in that element. |
There was a problem hiding this comment.
Text doesn't always appear: if the focused element isn't a text field, then it doesn't necessarily show anything: think of a game where hitting the "s" key moves a game piece up, but "s" never appears anywhere.
That's why it said "flows to that part of": it's an event stream (of keyboard events) that you're capturing with focus. Text fields convert it to visible text, but almost any other widget will just eat it and perform some operation.
| users tap or click on the desired UI element. | ||
| Once in focus, text entered with the keyboard appears in that element. | ||
| This continues until the focus moves to another element in the app. | ||
| App users also can press a particular keyboard shortcut to move focus, |
There was a problem hiding this comment.
I would just leave out "particular". Any key sequence can be assigned to move focus, Tab and Shift+Tab are just the defaults.
| * How to set focus order | ||
| ::: | ||
|
|
||
| Some developers have expressed confusion about how to define and |
There was a problem hiding this comment.
Would this section be set off better in a "note" box?
There was a problem hiding this comment.
Maybe? But not sure stacking two boxes atop each other would look good.
| are listed after this section. | ||
|
|
||
| **Focus tree** | ||
| : A sparse mirror of the widget tree that represents all the widgets |
There was a problem hiding this comment.
This is generally correct. There are cases where the focus tree doesn't mirror the widget tree, but they are esoteric.
| : A focus node that has focus where key events start propagating to | ||
| the primary focus node and its ancestors. |
There was a problem hiding this comment.
| : A focus node that has focus where key events start propagating to | |
| the primary focus node and its ancestors. | |
| : The focused node that is the first to receive key events before propagating them to its ancestors. |
Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]>
Co-authored-by: Greg Spencer <[email protected]>
|
PTAL @gspencergoog |
| This article explains how to direct keyboard input. | ||
| If your app uses a physical keyboard, like desktop and web apps, | ||
| keep reading. If your app won't use a physical keyboard, | ||
| you can skip this guide. |
There was a problem hiding this comment.
Just to double-check - is focus used for accessibility scenarios on mobile?
There was a problem hiding this comment.
Not necessarily: it's any app that can switch between traditional (key/mouse) input and touch input. @gspencergoog , did I read that right?
There was a problem hiding this comment.
There's a separate thing for accessibility focus on mobile. They're different things.
There is focus on mobile, but only if you connect a bluetooth or USB keyboard and/or mouse and use it. If you switch between mouse and touch, the focus highlights will turn on and off depending on which you used last.
| : A sparse mirror of the widget tree that represents all the widgets | ||
| that can receive focus. The nodes in this tree are called _focus nodes_. | ||
|
|
||
| **Focus node** |
There was a problem hiding this comment.
Does it make sense to mention somewhere here that focus nodes aren't widgets? Or do you think that the definition of focus tree makes that point?
| version of them. | ||
|
|
||
| ### Best practices for creating FocusNode objects | ||
| This focus node exists at the farthest point from the root of the focus tree. |
There was a problem hiding this comment.
This is false. You can give primary focus to an element (like a Card) which has descendants (like buttons) that don't have focus.
I'd just remove this sentence, or replace "focus tree" with "focus chain", where the primary focus is the end of the chain furthest from the root.
| in the highlight mode. | ||
| To use a `FocusTraversalPolicy`, give one to a `FocusTraversalGroup`, | ||
| It determines the widget subtree in which the policy will be effective. | ||
| Avoid calling the member functions of the class directly. |
There was a problem hiding this comment.
I wouldn't say "avoid". We try and not say that because people read that as "your app will crash if you do it wrong" and go through crazy hoops to never call it. Just say it's not typical.
parlough
added
review.await-update
The other changes will be covered in a separate commit. Co-authored-by: Greg Spencer <[email protected]>
Fixes #10168