From bb6757d853cecf4f136fac42d997698c96c9930a Mon Sep 17 00:00:00 2001
From: Renan <renancaraujo@users.noreply.github.com>
Date: Sat, 16 Mar 2019 22:15:26 -0300
Subject: [PATCH] composed component docs (#58)

* composed-component-docs

* undo mistakes

* typos
---
 doc/components.md                      | 32 ++++++++++++++++++++++++++
 lib/components/composed_component.dart | 30 +++++++++++++++++++++---
 2 files changed, 59 insertions(+), 3 deletions(-)

diff --git a/doc/components.md b/doc/components.md
index 6dfdabc90..6857c5dd1 100644
--- a/doc/components.md
+++ b/doc/components.md
@@ -57,6 +57,38 @@ If you have a spritesheet, you can use the `sequenced` constructor, identical to
 
 If you are not using `BaseGame`, don't forget this component needs to be update'd even if static, because the animation object needs to be ticked to move the frames.
 
+
+## Composed component
+
+A mixin that helps you to make a `Component` wraps other components. It is useful to group visual components through a hierarchy. When implemented, makes every item in its `components` collection field be updated and rendered with the same conditions.
+
+Example of usage, where visibility of two components are handled by a wrapper:
+
+```dart
+class GameOverPanel extends PositionComponent with Resizable, ComposedComponent {
+  bool visible = false;
+
+  GameOverText gameOverText;
+  GameOverButton gameOverButton;
+
+  GameOverPanel(Image spriteImage) : super() {
+    gameOverText = GameOverText(spriteImage); // GameOverText is a Component
+    gameOverButton = GameOverButton(spriteImage); // GameOverRestart is a SpriteComponent
+
+    components..add(gameOverText)..add(gameOverButton);
+  }
+
+  @override
+  void render(Canvas canvas) {
+    if (visible) {
+      super.render(canvas);
+    } // If not, neither of its `components` will be rendered
+  }
+}
+```
+
+
+
 ## Parallax Component
 
 This Component can be used to render pretty backgrounds, by drawing several transparent images on top of each other, each dislocated by a tiny amount.
diff --git a/lib/components/composed_component.dart b/lib/components/composed_component.dart
index 263ebf761..5626fd5d8 100644
--- a/lib/components/composed_component.dart
+++ b/lib/components/composed_component.dart
@@ -2,12 +2,36 @@ import 'dart:ui';
 
 import 'package:flame/components/component.dart';
 import 'package:flame/components/resizable.dart';
-import 'package:flame/game.dart';
 import 'package:ordered_set/comparing.dart';
 import 'package:ordered_set/ordered_set.dart';
 
-/// A component that lets your component be composed by others
-/// It resembles [BaseGame]. It has an [components] property and an [add] method
+/// A mixin that helps you to make a `Component` wraps other components. It is useful to group visual components through a hierarchy. When implemented, makes every item in its `components` collection field be updated and rendered with the same conditions.
+///
+/// Example of usage, where visibility of two components are handled by a wrapper:
+///
+/// ```dart
+///  class GameOverPanel extends PositionComponent with Resizable, ComposedComponent {
+///   bool visible = false;
+///
+///   GameOverText gameOverText;
+///   GameOverButton gameOverButton;
+///
+///   GameOverPanel(Image spriteImage) : super() {
+///     gameOverText = GameOverText(spriteImage); // GameOverText is a Component
+///     gameOverButton = GameOverButton(spriteImage); // GameOverRestart is a SpriteComponent
+///
+///     components..add(gameOverText)..add(gameOverButton);
+///   }
+///
+///   @override
+///   void render(Canvas canvas) {
+///     if (visible) {
+///       super.render(canvas);
+///     } // If not, neither of its `components` will be rendered
+///   }
+/// }
+/// ```
+///
 mixin ComposedComponent on Component {
   OrderedSet<Component> components =
       OrderedSet(Comparing.on((c) => c.priority()));