refactor!: Make TextElement more usable on its own (#2679)

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:
#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`

examples/lib/stories/input/hardware_keyboard_example.dart

@@ -250,7 +250,7 @@ class KeyboardKey extends PositionComponent {
   void render(Canvas canvas) {
     if (visible) {
       canvas.drawRRect(rect, borderPaint);
-      textElement.render(canvas);
+      textElement.draw(canvas);
     }
   }
 }

examples/lib/stories/rendering/rich_text_example.dart

@@ -73,6 +73,6 @@ class MyTextComponent extends PositionComponent {
 
   @override
   void render(Canvas canvas) {
-    element.render(canvas);
+    element.draw(canvas);
   }
 }

packages/flame/lib/src/components/text_box_component.dart

@@ -282,7 +282,7 @@ class TextBoxComponent<T extends TextRenderer> extends TextComponent {
             (boxHeight - nLines * _lineHeight) * align.y +
             i * _lineHeight,
       );
-      textRenderer.renderElement(canvas, textElement, position, anchor: anchor);
+      textElement.render(canvas, position, anchor: anchor);
 
       charCount += lines[i].length;
     }

packages/flame/lib/src/components/text_component.dart

@@ -51,6 +51,6 @@ class TextComponent<T extends TextRenderer> extends PositionComponent {
 
   @override
   void render(Canvas canvas) {
-    _textElement.render(canvas);
+    _textElement.draw(canvas);
   }
 }

packages/flame/lib/src/text/elements/element.dart

@@ -20,5 +20,5 @@ abstract class Element {
   /// In order to render the element at a different location, consider either
   /// calling the [translate] method, or applying a translation transform to the
   /// canvas itself.
-  void render(Canvas canvas);
+  void draw(Canvas canvas);
 }

packages/flame/lib/src/text/elements/group_element.dart

@@ -17,7 +17,7 @@ class GroupElement extends BlockElement {
   }
 
   @override
-  void render(Canvas canvas) {
-    children.forEach((child) => child.render(canvas));
+  void draw(Canvas canvas) {
+    children.forEach((child) => child.draw(canvas));
   }
 }

packages/flame/lib/src/text/elements/group_text_element.dart

@@ -17,9 +17,9 @@ class GroupTextElement extends TextElement {
   LineMetrics get metrics => _metrics;
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     for (final child in _children) {
-      child.render(canvas);
+      child.draw(canvas);
     }
   }
 

packages/flame/lib/src/text/elements/rect_element.dart

@@ -15,7 +15,7 @@ class RectElement extends Element {
   }
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     canvas.drawRect(_rect, _paint);
   }
 }

packages/flame/lib/src/text/elements/rrect_element.dart

@@ -19,7 +19,7 @@ class RRectElement extends Element {
   }
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     canvas.drawRRect(_rrect, _paint);
   }
 }

packages/flame/lib/src/text/elements/sprite_font_text_element.dart

@@ -32,7 +32,7 @@ class SpriteFontTextElement extends TextElement {
   }
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     canvas.drawRawAtlas(source, transforms, rects, null, null, null, paint);
   }
 }

packages/flame/lib/src/text/elements/text_element.dart

@@ -1,3 +1,5 @@
+import 'package:flame/extensions.dart';
+import 'package:flame/src/anchor.dart';
 import 'package:flame/src/text/common/line_metrics.dart';
 import 'package:flame/src/text/elements/element.dart';
 
@@ -6,4 +8,17 @@ import 'package:flame/src/text/elements/element.dart';
 abstract class TextElement extends Element {
   /// The dimensions of this line.
   LineMetrics get metrics;
+
+  void render(
+    Canvas canvas,
+    Vector2 position, {
+    Anchor anchor = Anchor.topLeft,
+  }) {
+    final box = metrics;
+    translate(
+      position.x - box.width * anchor.x,
+      position.y - box.height * anchor.y - box.top,
+    );
+    draw(canvas);
+  }
 }

packages/flame/lib/src/text/elements/text_painter_text_element.dart

@@ -24,7 +24,7 @@ class TextPainterTextElement extends TextElement {
   void translate(double dx, double dy) => _box.translate(dx, dy);
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     _textPainter.paint(canvas, Offset(_box.left, _box.top));
   }
 }

packages/flame/lib/src/text/text_renderer.dart

@@ -39,22 +39,7 @@ class TextRenderer<T extends TextFormatter> {
     Vector2 position, {
     Anchor anchor = Anchor.topLeft,
   }) {
-    final element = format(text);
-    renderElement(canvas, element, position, anchor: anchor);
-  }
-
-  void renderElement(
-    Canvas canvas,
-    TextElement element,
-    Vector2 position, {
-    Anchor anchor = Anchor.topLeft,
-  }) {
-    final box = element.metrics;
-    element.translate(
-      position.x - box.width * anchor.x,
-      position.y - box.height * anchor.y - box.top,
-    );
-    element.render(canvas);
+    format(text).render(canvas, position, anchor: anchor);
   }
 
   /// A registry containing default providers for every [TextRenderer] subclass;

packages/flame/test/text/text_renderer_test.dart

@@ -48,7 +48,7 @@ class CustomTextElement extends TextElement {
   LineMetrics get metrics => LineMetrics();
 
   @override
-  void render(Canvas canvas) {}
+  void draw(Canvas canvas) {}
 
   @override
   void translate(double dx, double dy) {}

packages/flame_test/lib/src/debug_text_formatter.dart

@@ -53,7 +53,7 @@ class _DebugTextElement extends TextElement {
   late final LineMetrics metrics;
 
   @override
-  void render(Canvas canvas) {
+  void draw(Canvas canvas) {
     canvas.save();
     if (style.fontStyle == FontStyle.italic) {
       canvas.skew(-0.25, 0);

packages/flame_test/test/debug_text_formatter_test.dart

@@ -50,7 +50,7 @@ class TextElementsComponent extends PositionComponent {
   @override
   void render(Canvas canvas) {
     for (final element in elements) {
-      element.render(canvas);
+      element.draw(canvas);
     }
   }
 }