refactor!: Rename (Text) Elements, Nodes and Styles for clarity, add docs (#2700)

This occurred to me after a discussion on the [new FCS component
PR](https://github.com/flame-engine/flame/pull/2694#discussion_r1312450113).
As per usual, @spydon has opened my eyes to the ultimate truth:

We should rename loads of files, and it shall affect almost no one.

The idea is to (1) add a "Text" prefix to all text-rendering-related
classes and (2) rename the existing `Text*` to `InlineText*` (which is
what they are).

This PR is a bit big, but the changes should hopefully be simple to
review, and can be broken down into:

* Add a proper base class for the node inheritance chain, call it
TextNode (while working on Flame Markdown I realized the value this will
have to me)
* Rename the old TextNode to InlineTextNode
* Rename DocumentNode to DocumentRoot because it is not a node
* Rename Element to TextElement
* Rename the old TextElement to InlineTextElement
* Rename Style to FlameTextStyle (note: we could consider dropping the
Flame here)
* Rename the old FlameTextStyle to InlineTextStyle
* Update the docs accordingly
* Add some more diagrams and explanations to the docs, following the new
nomenclature
* I also updated our "internal" imports to use the text module to make
life so much easier (this could arguably be done in a separate PR, but I
honestly think it's easier to review together, please lmk if you prefer
me to split).

These are all breaking changes but likely won't actually affect most
users (see below).

While this is breaking, it should hopefully not affect most users,
because these are all infrastructure classes that most people aren't
using directly. If you are using the FCS components, or the renderers
`TextPaint` or `SpriteFontRenderer` directly, this should have zero
effect to you.

If you are using the Nodes, Stlyes or Elements directly, or have a
custom TextRenderer, see below.

Migrating should be a simple matter of renaming your type references:

* from TextNode to InlineTextNode
* from TextElement to InlineTextElement
* from Element to TextElement
* from FlameTextStyle to InlineTextStyle
* from Style to FlameTextStyle

Make sure to do it in the appropriate order not to cause any
double-replace issues.

If you are importing via the module `package:flame/text.dart`, which we
highly encourage, you should not have to change any import statements
whatsoever.
This commit is contained in:
Luan Nico
2023-09-02 09:59:59 -07:00
committed by GitHub
parent 99a1016f72
commit 4b420b7952
40 changed files with 492 additions and 359 deletions

View File

@ -17,7 +17,7 @@ class RichTextExample extends FlameGame {
}
class MyTextComponent extends PositionComponent {
late final Element element;
late final TextElement element;
@override
Future<void> onLoad() async {
@ -38,7 +38,7 @@ class MyTextComponent extends PositionComponent {
),
),
);
final document = DocumentNode([
final document = DocumentRoot([
HeaderNode.simple('1984', level: 1),
ParagraphNode.simple(
'Anything could be true. The so-called laws of nature were nonsense.',