Update documentation on TextPainter to note default color differences
#165048
Conversation
There was a problem hiding this comment.
I believe the default is current set by flutter not skparagraph / canvaskit. (It looks like we're not setting default text colors for the canvaskit, instead the default is from here).
the non-web default is from here.
And it looks like the canvaskit backend default is from here.
The wasm implementation here
@mdebbar does it make sense to update one of the defaults so it's consistent between backends?
| @@ -583,8 +583,15 @@ class _LineCaretMetrics { | |||
| /// changes, return to step 2. If the text to be painted changes, | |||
| /// return to step 1. | |||
| /// | |||
| /// The default text style is white. To change the color of the text, | |||
| /// pass a [TextStyle] object to the [TextSpan] in `text`. | |||
| /// > [!IMPORTANT] | |||
There was a problem hiding this comment.
I don't think dartdoc supports this markdown extension. Even if it does, this doesn't feel THAT important to warrant a highlighted section.
There was a problem hiding this comment.
Dartdoc does now support this - can't link it right now, but search for "> [!IMPORTANT]" with quotes and you'll get to the issue/PR. Whether or not it's good to use here, I feel it is - in my case, it wasn't immediately clear why the texts were different colours since I couldn't see the background.
There was a problem hiding this comment.
oh dart-lang/dartdoc#3995. TIL thank you!
There was a problem hiding this comment.
Wouldn't "The default text style color is white on non-web platforms and black on the web" suffice? For API docs I would prefer less reading if we can convey the same message.
There was a problem hiding this comment.
I've reduced it, using that text for the first line. There's still the second part, since I think that's also important, but I've also reduced that.
Probably completely misunderstanding you here, and I cant see where the colour is actually set in the second link, so I don't know which backend you'd suggest changing - but doesn't it make sense for the colour to be black on white on web (regardless of backend) and white on black on native (regardless of backend). And from my testing - although I can't fully remember/be sure - I didn't notice a difference in the text colour whether I was using wasm or not on web - because of course, they should both be black on white to be visible. |
Yeah you're right that the second link isn't where the default is set. The default is actually from canvaskit. I'll update the link. |
This change only changes the documentation of
TextPainter.Previously, the documentation was incorrect in stating that the default text color was white. It changes depending on platform to be contrasted to the canvas' background color.
This is in an "important" box because it affects apps working on native & web, and is relatively easy to miss.
It may be worth documenting this elsewhere?
Fixes #165047
Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.