Floating cursor docs #133002
Floating cursor docs #133002
Conversation
| /// | ||
| /// If this is null, the background cursor is not painted. | ||
| /// | ||
| /// @{macro flutter.services.TextInput.floatingCursor} |
There was a problem hiding this comment.
i would just inline the see also in all these places. using a macro means people browsing the source can't easily see what you're trying to inline, and if you ever want to use the macros somewhere that already has a "see also" you'll need to find another solution.
| /// The floating cursor is an iOS feature in which long pressing and dragging on | ||
| /// the spacebar of the soft keyboard causes the cursor in the text field to | ||
| /// move along with the drag gesture. It's used to precisely position the cursor | ||
| /// in some editable text. |
There was a problem hiding this comment.
that doesn't really help me understand what it is, or why it has multiple colors, etc. would it be possible to describe it in more detail, or maybe generate screenshots showing it (in assets-for-api-docs) and pointing to those?
The audience here is people who have never used iOS. They probably need to know all the various modes it can be in, the various properties that can be used to configure it, and so on.
There was a problem hiding this comment.
(the writing prompt i usually give myself is, "if someone is looking at this, that means they have a question that they're trying to answer. what is the question? what will follow-up questions be?")
There was a problem hiding this comment.
Updated, let me know what you think.
|
The referenced gif will be added in flutter/assets-for-api-docs#226. |
| /// This feature works out-of-the-box with Flutter. Support is built into | ||
| /// [EditableText]. | ||
| /// | ||
| /// ![Animation of the native iOS floating cursor feature on an iPhone 14 simulator running iOS 17.0]( |
There was a problem hiding this comment.
This is the title of the image, but what we're supposed to provide in the alternative text is a replacement for the image, for someone who can't see it.
I think in this case what I would recommend is to not have any alternative text and just describe the image so that everyone can see the description. Something like, "when the user long-presses the space bar, they are able to drag the cursor to an arbitrary position. The floating cursor snaps to lines as the user moves it vertically, but does not snap to positions between characters horizontally. The floating cursor renders over the text field, while a faint shadow of the cursor is rendered in the text field in the location between characters where the cursor will drop into when released. The shadow cursor is a faint vertical bar with a blob at its bottom, while the floating cursor has the same appearance as a normal cursor (a blue vertical bar)."
There was a problem hiding this comment.
looks like you call it a placeholder cursor rather than a shadow cursor, so obviously update my terminology to be more correct. :-)
|
Yeah, having a screenshot is a huge improvement! |
|
I've removed the screenshot as it's not possible to generate in a script, and I've linked to the relevant Apple docs. |
|
The Apple docs here are pretty useless. I don't think I would understand anything about floating cursors if I read that without context. If we can't autogenerate the screenshot, let's provide something like what we would have had to write as the alt text, something like what I suggested above, or something like "When the user long-presses the spacebar on the iOS virtual keyboard, iOS enters a "floating cursor" cursor-positioning mode where the whole keyboard becomes a trackpad. In this mode, there are two visible cursors. One hovers over the text, following the user's movements exactly. The other is a "shadow" that snaps to the actual location where the cursor will go when the user releases the trackpad.", or maybe some combination of both:
The point is to provide lots of detail so that someone who has never seen an iPhone has some chance of understanding the API. |
|
@Hixie Thanks for the guidance, I've updated it to integrate something close to what you've written. One thing I changed was not mentioning the "blob" at the bottom of the placeholder cursor, which I didn't see when I tried this on an iOS 17 simulator. |
| /// long-presses the spacebar on the iOS virtual keyboard, iOS enters floating | ||
| /// cursor mode where the whole keyboard becomes a trackpad. In this mode, | ||
| /// there are two visible cursors. One, the floating cursor, hovers over the | ||
| /// text, following the user's horizontal movements exactly and snapping to |
There was a problem hiding this comment.
The "floating" cursor follows the user's gesture movements exactly I believe (there's no line-snapping).
There was a problem hiding this comment.
I tried it again and it does sort of snap. Maybe that's not the best way to call it?
There was a problem hiding this comment.
Is this in a UIKit app? I don't think Flutter does this and I don't remember UIKit doing this either. It could be new.
There was a problem hiding this comment.
Also both cursors being visible when they are so close to each other is different from the behavior I remembered. Pretty sure it used to hide the gray cursor when it's too close to the blue cursor.
There was a problem hiding this comment.
This is the Reminders app on an iOS 17 simulator. I see the same behavior on Messages so maybe it's a new iOS 17 thing.
| /// The state of a "floating cursor" drag on an iOS soft keyboard. | ||
| /// | ||
| /// The "floating cursor" cursor-positioning mode is an iOS feature used to | ||
| /// precisely position the caret in some editable text. When the user |
There was a problem hiding this comment.
nit: force touch/long press/two-finger pan also picks up the cursor so maybe:
some editable text using certain touch gestures. As an example: when the user
flutter/flutter@3ee8ff2...5b673c2 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from fd0335a910b8 to b229878c57f5 (1 revision) (flutter/flutter#142051) 2024-01-23 goderbauer@google.com Remove unused clipBehavior from OverflowBar (flutter/flutter#141976) 2024-01-23 engine-flutter-autoroll@skia.org Roll Packages from e4cbf23 to 841fe90 (7 revisions) (flutter/flutter#142047) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from d2855da628da to fd0335a910b8 (1 revision) (flutter/flutter#142046) 2024-01-23 leroux_bruno@yahoo.fr Add Share button to the SelectableRegion toolbar on Android (flutter/flutter#141447) 2024-01-23 davidmartos96@gmail.com Relax the warning of unavailable tokens in `gen_defaults` when a default value is provided (flutter/flutter#140872) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from 37f68f6fc7fc to d2855da628da (1 revision) (flutter/flutter#142033) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from 9e582c9032e5 to 37f68f6fc7fc (1 revision) (flutter/flutter#142027) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from df6b15d35703 to 9e582c9032e5 (1 revision) (flutter/flutter#142026) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from d3dbd4225e08 to df6b15d35703 (6 revisions) (flutter/flutter#142023) 2024-01-23 ian@hixie.ch Add a comment about how to test flutter_goldens (flutter/flutter#141902) 2024-01-23 ian@hixie.ch Enable contextMenuBuilder in the absence of selectionControls (flutter/flutter#141810) 2024-01-23 engine-flutter-autoroll@skia.org Roll Flutter Engine from b069d7f8f1fd to d3dbd4225e08 (3 revisions) (flutter/flutter#142005) 2024-01-23 98614782+auto-submit[bot]@users.noreply.github.com Reverts "hello_world app: migrate to Gradle Kotlin DSL" (flutter/flutter#142018) 2024-01-22 jmccandless@google.com Floating cursor docs (flutter/flutter#133002) 2024-01-22 git@reb0.org refactor: Rename filterPluginsByPlatform, cleanup Platform Strings (flutter/flutter#141780) 2024-01-22 barpac02@gmail.com hello_world app: migrate to Gradle Kotlin DSL (flutter/flutter#141541) 2024-01-22 engine-flutter-autoroll@skia.org Roll Flutter Engine from b2762f410840 to b069d7f8f1fd (4 revisions) (flutter/flutter#141993) 2024-01-22 matanlurey@users.noreply.github.com Remove duplicate code as suggested by natebosch. (flutter/flutter#141988) 2024-01-22 jesus_sguerrero@hotmail.com Revert "Remove hack from PageView." (flutter/flutter#141977) 2024-01-22 engine-flutter-autoroll@skia.org Roll Flutter Engine from d653559ae183 to b2762f410840 (3 revisions) (flutter/flutter#141978) 2024-01-22 matanlurey@users.noreply.github.com Do not hang on test failures of tests within `flutter_tools` (flutter/flutter#141821) 2024-01-22 gspencergoog@users.noreply.github.com Remove unneeded expectation in test (flutter/flutter#141822) 2024-01-22 engine-flutter-autoroll@skia.org Roll Flutter Engine from 1efe8ba6bc04 to d653559ae183 (3 revisions) (flutter/flutter#141972) 2024-01-22 ueman@users.noreply.github.com Add documentation which explains that `debugPrint` also logs in release mode (flutter/flutter#141595) 2024-01-22 tessertaha@gmail.com Fix `RangeSlider` throws a null-check error after `clearSemantics` is called (flutter/flutter#141965) 2024-01-22 engine-flutter-autoroll@skia.org Roll Flutter Engine from c49989292fc1 to 1efe8ba6bc04 (1 revision) (flutter/flutter#141969) 2024-01-22 110993981+htoor3@users.noreply.github.com [web] - Fix broken `TextField` in semantics mode when it's a sibling of `Navigator` (flutter/flutter#138446) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC bmparr@google.com,rmistry@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: https://skia.googlesource.com/buildbot/+doc/main/autoroll/README.md
Explains what a "floating cursor" is in the docs.
Fixes #132411