Add output associated type to Drawable

MIGRATING-0.6-0.7.md

@@ -10,6 +10,7 @@
     - [Geometry](#geometry)
     - [Color](#color)
     - [Sub draw targets](#sub-draw-targets)
+    - [Text rendering](#text-rendering)
   - [For display driver authors](#for-display-driver-authors)
   - [For crates that handle images](#for-crates-that-handle-images)
   - [For text rendering crates](#for-text-rendering-crates)
@@ -24,7 +25,7 @@
     - [Triangle](#triangle)
   - [Geometry](#geometry-1)
   - [Mock display](#mock-display-1)
-  - [style module](#style-module)
+  - [Style module](#style-module)
 
 ## New features
 
@@ -162,6 +163,10 @@ To reduce duplication, please search the `DrawTarget` documentation on <https://
 
 The `Drawable` trait now uses an associated type for its pixel color instead of a type parameters.
 
+An associated type, `Output`, has also been added which can be used to return intermediate values
+from drawing operations. The nil type `()` can be used if the `draw` method doesn't need to return
+anything, e.g. `type Output = ();`
+
 ```diff
 - impl<'a, C: 'a> Drawable<C> for &Button<'a, C>
 - where
@@ -177,7 +182,9 @@ The `Drawable` trait now uses an associated type for its pixel color instead of
 + {
 +     type Color = C;
 +
-+     fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
++     type Output = ();
++
++     fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
 +     where
 +         D: DrawTarget<Color = C>,
 +     {
@@ -323,4 +330,4 @@ TODO: Improve this section before release.
 
 - `PrimitiveStyle` & `PrimitiveStyleBuilder` -> `primitives` module
 - `TextStyle` & `TextStyleBuilder` -> `text` module + see text changes
-- `Styled` -> crate root
+- `Styled` -> crate root

core/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 ## [Unreleased] - ReleaseDate
 
+### Added
+
+- **(breaking)** [#552](https://github.com/embedded-graphics/embedded-graphics/pull/552) Added the `Output` associated type to `Drawable` to allow returning non-`()` values from drawing operations.
+
 ## [0.2.0] - 2021-02-03
 
 ### Added
@@ -30,10 +34,9 @@
 - [#498](https://github.com/embedded-graphics/embedded-graphics/pull/498) Split common functionality out of `embedded-graphics` into `embedded-graphics-core`.
 - [#498](https://github.com/embedded-graphics/embedded-graphics/pull/498) Added `Size::saturating_add` and `Size::saturating_sub`.
 
-
 <!-- next-url -->
+
 [unreleased]: https://github.com/embedded-graphics/embedded-graphics-core/compare/embedded-graphics-core-v0.2.0...HEAD
 [0.2.0]: https://github.com/embedded-graphics/embedded-graphics-core/compare/embedded-graphics-core-v0.1.1...embedded-graphics-core-v0.2.0
 [0.1.1]: https://github.com/embedded-graphics/embedded-graphics-core/compare/embedded-graphics-core-v0.1.0...embedded-graphics-core-v0.1.1
-
 [0.1.0]: https://github.com/embedded-graphics/embedded-graphics/compare/embedded-graphics-v0.7.0-alpha.1...embedded-graphics-core-v0.1.0

core/src/drawable.rs

@@ -29,8 +29,9 @@ use crate::{draw_target::DrawTarget, geometry::Point, pixelcolor::PixelColor};
 ///     C: PixelColor + From<BinaryColor>,
 /// {
 ///     type Color = C;
+///     type Output = ();
 ///
-///     fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+///     fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
 ///     where
 ///         D: DrawTarget<Color = C>,
 ///     {
@@ -65,8 +66,27 @@ pub trait Drawable {
     /// The pixel color type.
     type Color: PixelColor;
 
+    // TODO: Remove `ignore` from example code when the `Text` drawable is updated
+    // CC https://github.com/embedded-graphics/embedded-graphics/pull/552#discussion_r576955191
+    /// The return type of the [`draw`] method.
+    ///
+    /// The `Output` type can be used to return results and values produced from the drawing of the
+    /// current item. For example, rendering two differently styled text items next to each other
+    /// can make use of a returned value, allowing the next text to be positioned after the first:
+    ///
+    /// ```rust,ignore
+    /// let next_point = Text::new("Label ", Point::new(10, 20))
+    ///     .into_styled(label_style)
+    ///     .draw(&mut display)?;
+    ///
+    /// Text::new("Value", next_point).into_styled(value_style).draw(&mut display)?;
+    /// ```
+    ///
+    /// Use `()` if no value should be returned.
+    type Output;
+
     /// Draw the graphics object using the supplied DrawTarget.
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = Self::Color>;
 }
@@ -113,8 +133,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/image/mod.rs

@@ -221,8 +221,9 @@ where
     T: ImageDrawable,
 {
     type Color = T::Color;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = Self::Color>,
     {

src/primitives/arc/styled.rs

@@ -85,8 +85,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/circle/styled.rs

@@ -92,8 +92,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/ellipse/styled.rs

@@ -96,8 +96,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/line/styled.rs

@@ -73,8 +73,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/polyline/styled.rs

@@ -158,8 +158,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/rectangle/styled.rs

@@ -86,8 +86,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/rounded_rectangle/styled.rs

@@ -83,8 +83,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/sector/styled.rs

@@ -178,8 +178,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/primitives/triangle/styled.rs

@@ -100,8 +100,9 @@ where
     C: PixelColor,
 {
     type Color = C;
+    type Output = ();
 
-    fn draw<D>(&self, display: &mut D) -> Result<(), D::Error>
+    fn draw<D>(&self, display: &mut D) -> Result<Self::Output, D::Error>
     where
         D: DrawTarget<Color = C>,
     {

src/text/text.rs

@@ -122,6 +122,7 @@ where
     S: TextRenderer<Color = C>,
 {
     type Color = C;
+    type Output = ();
 
     fn draw<D>(&self, target: &mut D) -> Result<(), D::Error>
     where
@@ -141,6 +142,7 @@ where
     S: TextRenderer<Color = C>,
 {
     type Color = C;
+    type Output = ();
 
     fn draw<D>(&self, target: &mut D) -> Result<(), D::Error>
     where