Feature: LinearGradient color decorator. (#592)

Based on the existing color decorators, create new ones to apply a gradient effect on the DOM.

Co-authored-by: ArthurSonzogni <sonzogniarthur@gmail.com>

include/ftxui/dom/elements.hpp

@@ -7,6 +7,7 @@
 #include "ftxui/dom/canvas.hpp"
 #include "ftxui/dom/direction.hpp"
 #include "ftxui/dom/flexbox_config.hpp"
+#include "ftxui/dom/linear_gradient.hpp"
 #include "ftxui/dom/node.hpp"
 #include "ftxui/screen/box.hpp"
 #include "ftxui/screen/color.hpp"
@@ -99,8 +100,12 @@ Element blink(Element);
 Element strikethrough(Element);
 Decorator color(Color);
 Decorator bgcolor(Color);
+Decorator color(const LinearGradient&);
+Decorator bgcolor(const LinearGradient&);
 Element color(Color, Element);
 Element bgcolor(Color, Element);
+Element color(const LinearGradient&, Element);
+Element bgcolor(const LinearGradient&, Element);
 Decorator focusPosition(int x, int y);
 Decorator focusPositionRelative(float x, float y);
 Element automerge(Element child);

include/ftxui/dom/linear_gradient.hpp

@@ -0,0 +1,52 @@
+#ifndef FTXUI_DOM_LINEAR_GRADIENT_HPP
+#define FTXUI_DOM_LINEAR_GRADIENT_HPP
+
+#include <optional>
+#include <vector>
+
+#include "ftxui/screen/color.hpp"  // for Colors
+
+namespace ftxui {
+
+/// @brief A class representing the settings for linear-gradient color effect.
+///
+/// Example:
+/// ```cpp
+/// LinearGradient()
+///    .Angle(45)
+///    .Stop(Color::Red, 0.0)
+///    .Stop(Color::Green, 0.5)
+///    .Stop(Color::Blue, 1.0);
+/// ```
+///
+/// There are also shorthand constructors:
+/// ```cpp
+/// LinearGradient(Color::Red, Color::Blue);
+/// LinearGradient(45, Color::Red, Color::Blue);
+/// ```
+struct LinearGradient {
+  float angle = 0.f;
+  struct Stop {
+    Color color = Color::Default;
+    std::optional<float> position;
+  };
+  std::vector<Stop> stops;
+
+  // Simple constructor
+  LinearGradient();
+  LinearGradient(Color begin, Color end);
+  LinearGradient(float angle, Color begin, Color end);
+
+  // Modifier using the builder pattern.
+  LinearGradient& Angle(float angle);
+  LinearGradient& Stop(Color color, float position);
+  LinearGradient& Stop(Color color);
+};
+
+}  // namespace ftxui
+
+#endif  // FTXUI_DOM_LINEAR_GRADIENT_HPP
+
+// Copyright 2023 Arthur Sonzogni. All rights reserved.
+// Use of this source code is governed by the MIT license that can be found in
+// the LICENSE file.

include/ftxui/screen/color.hpp

@@ -2,7 +2,8 @@
 #define FTXUI_SCREEN_COLOR_HPP
 
 #include <cstdint>  // for uint8_t
-#include <string>   // for wstring
+#include <string>   // for string
+#include <vector>   // for vector
 
 #ifdef RGB
 // Workaround for wingdi.h (via Windows.h) defining macros that break things.