I was playing around with the rule avoid-global-state
While I don't think we should enable it, because we do have several totally legitimate cases of what the rule considers global state, it did help me find any current cases where the things just should be final constants.
So this PR will mark semantically final variables as final (or const) proper, exclusively on examples (no violations on actual src code are legit).
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 is part of my ongoing effort to simplify the text rendering
pipeline.
My ultimate goal is to:
* get rid of renders
* rename formatters to renderers
* make the interface complies to both
All details are specified here:
https://github.com/flame-engine/flame/pull/2663
As a first step to break down that huge PR, this makes a small change to
TextElements to make them more useful
This PR will:
### rename render -> draw
draw becomes the "internal", underlying impl, raw method, that just
draws the element w/ any custom options
### add a new render method that takes in more options
this does not need to be extended by every impl.
this is for end users and accepts parameters like position and anchor to
be more in line with the renderer interface
This is technically a breaking change but should have no effect for
users, unless you are creating your own custom `TextElement`s. In that
case, to migrate:
* rename your `render` method to `draw`
This PR continues the work for enabling rich text support within Flame.
Here I add support for different text fragments having different TextStyles, and allow those styles to be inheritable within the text node tree.
This PR introduces the notions of structured text, and text styles, to support rendering of rich text bodies.
Specifically, we recognize that sometimes in games one needs to render pieces of text that are larger than a single word or even a single paragraph. These pieces may include: books, quest descriptions, mission objectives, tutorials, in-game help system, dialogues, etc. Rendering such a piece of text is non-trivial, however. In order to tackle this problem, I break into the following parts:
Text structure, represented as a tree of Nodes. The nodes describe the logical structure of the text, for example the document may contain a header, and then several paragraphs, and a list, where the list contains some list items, some of which having possibly several paragraphs, etc. This structure is similar to how in HTML the text is marked up with HTML tags.
Text styles are struct-like classes that contain properties describing how the text is to be styled: font size, font renderer, borders, backgrounds, margins, padding, etc. This representation is also tree-like, so that for example text inside paragraphs can have different style than text within headers, and paragraphs within lists can have different margins. A text style is similar to a stylesheet in HTML.
Text elements are the result of applying the document style to a document node: they are the "prepared" and laid out pieces, ready to be rendered. Elements are a bit like mini-components, or perhaps text "particles" in a particle system.
