From b1e63d02214a7baff924e3973c2f84c02ccf7ea8 Mon Sep 17 00:00:00 2001 From: ArthurSonzogni Date: Thu, 5 Jun 2025 11:34:25 +0200 Subject: [PATCH] Update documentation. --- include/ftxui/component/animation.hpp | 20 +++++++--- include/ftxui/component/captured_mouse.hpp | 1 + include/ftxui/component/component_options.hpp | 5 ++- include/ftxui/component/event.hpp | 2 + include/ftxui/component/loop.hpp | 39 +++++++++++++++++++ .../ftxui/component/screen_interactive.hpp | 4 ++ include/ftxui/dom/canvas.hpp | 15 +++++++ include/ftxui/dom/direction.hpp | 5 +++ include/ftxui/dom/elements.hpp | 8 ++++ include/ftxui/dom/flexbox_config.hpp | 13 +++++++ include/ftxui/dom/linear_gradient.hpp | 7 ++++ include/ftxui/dom/node.hpp | 14 +++++++ include/ftxui/dom/requirement.hpp | 5 +++ include/ftxui/dom/selection.hpp | 7 +++- include/ftxui/dom/table.hpp | 38 +++++++++--------- include/ftxui/screen/box.hpp | 7 ++++ include/ftxui/screen/color.hpp | 4 +- include/ftxui/screen/color_info.hpp | 4 ++ include/ftxui/screen/terminal.hpp | 6 +++ 19 files changed, 177 insertions(+), 27 deletions(-) diff --git a/include/ftxui/component/animation.hpp b/include/ftxui/component/animation.hpp index a04aea56..035adb86 100644 --- a/include/ftxui/component/animation.hpp +++ b/include/ftxui/component/animation.hpp @@ -8,11 +8,21 @@ #include // for function namespace ftxui::animation { -// Components who haven't completed their animation can call this function to -// request a new frame to be drawn later. -// -// When there is no new events and no animations to complete, no new frame is -// drawn. +/// @brief RequestAnimationFrame is a function that requests a new frame to be +/// drawn in the next animation cycle. +/// +/// @note This function is typically called by components that need to +/// update their state or appearance over time, such as animations or +/// transitions. This is useful when the change doesn't depend depend on the +/// events seen by the terminal, but rather on the passage of time. +/// +/// Components who haven't completed their animation can call this function to +/// request a new frame to be drawn later. +/// +/// When there is no new events and no animations to complete, no new frame is +/// drawn. +/// +/// @ingroup component void RequestAnimationFrame(); using Clock = std::chrono::steady_clock; diff --git a/include/ftxui/component/captured_mouse.hpp b/include/ftxui/component/captured_mouse.hpp index 234e12f6..42a926b1 100644 --- a/include/ftxui/component/captured_mouse.hpp +++ b/include/ftxui/component/captured_mouse.hpp @@ -7,6 +7,7 @@ #include namespace ftxui { + class CapturedMouseInterface { public: CapturedMouseInterface() = default; diff --git a/include/ftxui/component/component_options.hpp b/include/ftxui/component/component_options.hpp index a5a9cac3..d387fad1 100644 --- a/include/ftxui/component/component_options.hpp +++ b/include/ftxui/component/component_options.hpp @@ -27,6 +27,8 @@ struct EntryState { int index; ///< Index of the entry when applicable or -1. }; +/// @brief Option for the underline effect. +/// @ingroup component struct UnderlineOption { bool enabled = false; @@ -230,7 +232,8 @@ struct SliderOption { std::function on_change; ///> Called when `value` is updated. }; -// Parameter pack used by `WindowOptions::render`. +/// @brief State passed to the `Window` component's render function. +/// @ingroup component struct WindowRenderState { Element inner; ///< The element wrapped inside this window. const std::string& title; ///< The title of the window. diff --git a/include/ftxui/component/event.hpp b/include/ftxui/component/event.hpp index 6ce20e06..f95af310 100644 --- a/include/ftxui/component/event.hpp +++ b/include/ftxui/component/event.hpp @@ -24,6 +24,8 @@ class ComponentBase; /// /// Useful documentation about xterm specification: /// https://invisible-island.net/xterm/ctlseqs/ctlseqs.html +/// +/// @ingroup component struct Event { // --- Constructor section --------------------------------------------------- static Event Character(std::string); diff --git a/include/ftxui/component/loop.hpp b/include/ftxui/component/loop.hpp index faef475c..dcbf92dd 100644 --- a/include/ftxui/component/loop.hpp +++ b/include/ftxui/component/loop.hpp @@ -14,6 +14,45 @@ class ComponentBase; using Component = std::shared_ptr; class ScreenInteractive; +/// @brief Loop is a class that manages the event loop for a component. +/// +/// It is responsible for running the component, handling events, and +/// updating the screen. +/// +/// The Loop class is designed to be used with a ScreenInteractive object, +/// which represents the terminal screen. +/// +/// **Example** +/// ```cpp +/// #include +/// #include +/// #include +/// +/// int main() { +/// auto screen = ftxui::ScreenInteractive::TerminalOutput(); +/// auto component = ftxui::Button("Click me", [] { ... }); +/// +/// ftxui::Loop loop(screen.get(), component); +/// +/// // Either +/// loop.Run(); // Blocking until the component quits. +/// +/// // Or +/// loop.RunOnce(); // Non-blocking, returns immediately. +/// +/// // Or +/// loop.RunOnceBlocking(); // Blocking until handling one event. +/// +/// // Or in a loop: +/// while (!loop.HasQuitted()) { +/// loop.RunOnce(); +/// +/// // Do something else like running a different library loop function. +/// } +/// } +/// ``` +/// +/// @ingroup component class Loop { public: Loop(ScreenInteractive* screen, Component component); diff --git a/include/ftxui/component/screen_interactive.hpp b/include/ftxui/component/screen_interactive.hpp index a2909fca..f3460917 100644 --- a/include/ftxui/component/screen_interactive.hpp +++ b/include/ftxui/component/screen_interactive.hpp @@ -27,6 +27,10 @@ struct Event; using Component = std::shared_ptr; class ScreenInteractivePrivate; +/// @brief ScreenInteractive is a `Screen` that can handle events, run a main +/// loop, and manage components. +/// +/// @ingroup component class ScreenInteractive : public Screen { public: // Constructors: diff --git a/include/ftxui/dom/canvas.hpp b/include/ftxui/dom/canvas.hpp index 5d33d67a..1157772e 100644 --- a/include/ftxui/dom/canvas.hpp +++ b/include/ftxui/dom/canvas.hpp @@ -20,6 +20,21 @@ namespace ftxui { +/// @brief Canvas is a drawable buffer associated with drawing operations. +/// +/// Canvas is a drawable area that can be used to create complex graphics. It +/// supports drawing points, lines, circles, ellipses, text, and images using +/// braille, block, or normal characters. +/// +/// Note: A terminal contains cells. A cells is a unit of: +/// - 2x4 braille characters (1x1 pixel) +/// - 2x2 block characters (2x2 pixels) +/// - 2x4 normal characters (2x4 pixels) +/// +/// You need to multiply the x coordinate by 2 and the y coordinate by 4 to +/// get the correct position in the terminal. +/// +/// @ingroup dom struct Canvas { public: Canvas() = default; diff --git a/include/ftxui/dom/direction.hpp b/include/ftxui/dom/direction.hpp index 2a38f092..9686e2be 100644 --- a/include/ftxui/dom/direction.hpp +++ b/include/ftxui/dom/direction.hpp @@ -5,6 +5,11 @@ #define FTXUI_DOM_DIRECTION_HPP namespace ftxui { + +/// @brief Direction is an enumeration that represents the four cardinal +/// directions. +/// +/// @ingroup dom enum class Direction { Up = 0, Down = 1, diff --git a/include/ftxui/dom/elements.hpp b/include/ftxui/dom/elements.hpp index 4978ded6..63d5bf0b 100644 --- a/include/ftxui/dom/elements.hpp +++ b/include/ftxui/dom/elements.hpp @@ -24,6 +24,14 @@ using Elements = std::vector; using Decorator = std::function; using GraphFunction = std::function(int, int)>; +/// @brief BorderStyle is an enumeration that represents the different styles +/// of borders that can be applied to elements in the terminal UI. +/// +/// BorderStyle is an enumeration that represents the different styles of +/// borders that can be applied to elements in the terminal UI. +/// It is used to define the visual appearance of borders around elements, +/// such as windows, frames, or separators. +/// @ingroup dom enum BorderStyle { LIGHT, DASHED, diff --git a/include/ftxui/dom/flexbox_config.hpp b/include/ftxui/dom/flexbox_config.hpp index 8ae26779..d8e421fd 100644 --- a/include/ftxui/dom/flexbox_config.hpp +++ b/include/ftxui/dom/flexbox_config.hpp @@ -12,6 +12,19 @@ namespace ftxui { + +/// @brief FlexboxConfig is a configuration structure that defines the layout +/// properties for a flexbox container. +// +/// It allows you to specify the direction of the flex items, whether they +/// should wrap, how they should be justified along the main axis, and how +/// they should be aligned along the cross axis. +/// It also includes properties for gaps between flex items in both the +/// main and cross axes. +/// This structure is used to configure the layout behavior of flexbox +/// containers in a terminal user interface. +/// +/// @ingroup dom struct FlexboxConfig { /// This establishes the main-axis, thus defining the direction flex items are /// placed in the flex container. Flexbox is (aside wrapping) single-direction diff --git a/include/ftxui/dom/linear_gradient.hpp b/include/ftxui/dom/linear_gradient.hpp index da7e77b8..44f41cdf 100644 --- a/include/ftxui/dom/linear_gradient.hpp +++ b/include/ftxui/dom/linear_gradient.hpp @@ -27,8 +27,15 @@ namespace ftxui { /// LinearGradient(Color::Red, Color::Blue); /// LinearGradient(45, Color::Red, Color::Blue); /// ``` +/// +/// @ingroup dom struct LinearGradient { float angle = 0.f; + + /// A stop is a color at a specific position in the gradient. + /// The position is a value between 0.0 and 1.0, + /// where 0.0 is the start of the gradient + /// and 1.0 is the end of the gradient. struct Stop { Color color = Color::Default; std::optional position; diff --git a/include/ftxui/dom/node.hpp b/include/ftxui/dom/node.hpp index 6357ee65..4ba90458 100644 --- a/include/ftxui/dom/node.hpp +++ b/include/ftxui/dom/node.hpp @@ -20,6 +20,20 @@ class Screen; using Element = std::shared_ptr; using Elements = std::vector; +/// @brief Node is the base class for all elements in the DOM tree. +/// +/// It represents a single node in the document object model (DOM) and provides +/// the basic structure for layout and rendering. +/// It contains methods for computing layout requirements, setting the box +/// dimensions, selecting content, rendering to the screen, and checking the +/// layout status. +/// It typically contains child elements, which are also instances of Node. +/// +/// Users are expected to derive from this class to create custom elements. +/// +/// A list of builtin elements can be found in the `elements.hpp` file. +/// +/// @ingroup dom class Node { public: Node(); diff --git a/include/ftxui/dom/requirement.hpp b/include/ftxui/dom/requirement.hpp index b8a5c573..d5420ae0 100644 --- a/include/ftxui/dom/requirement.hpp +++ b/include/ftxui/dom/requirement.hpp @@ -10,6 +10,11 @@ namespace ftxui { class Node; +/// @brief Requirement is a structure that defines the layout requirements for a +/// Node in the terminal user interface. +/// +/// It specifies the minimum size required to fully draw the element, +/// @ingroup dom struct Requirement { // The required size to fully draw the element. int min_x = 0; diff --git a/include/ftxui/dom/selection.hpp b/include/ftxui/dom/selection.hpp index 912d9e44..7e7c6299 100644 --- a/include/ftxui/dom/selection.hpp +++ b/include/ftxui/dom/selection.hpp @@ -13,7 +13,12 @@ namespace ftxui { -/// @brief Represent a selection in the terminal. +/// @brief Represents a selection in a terminal user interface. +/// +/// Selection is a class that represents the two endpoints of a selection in a +/// terminal user interface. +/// +/// @ingroup dom class Selection { public: Selection(); // Empty selection. diff --git a/include/ftxui/dom/table.hpp b/include/ftxui/dom/table.hpp index 5460237d..3e677917 100644 --- a/include/ftxui/dom/table.hpp +++ b/include/ftxui/dom/table.hpp @@ -11,28 +11,28 @@ namespace ftxui { -// Usage: -// -// Initialization: -// --------------- -// -// auto table = Table({ -// {"X", "Y"}, -// {"-1", "1"}, -// {"+0", "0"}, -// {"+1", "1"}, -// }); -// -// table.SelectAll().Border(LIGHT); -// -// table.SelectRow(1).Border(DOUBLE); -// table.SelectRow(1).SeparatorInternal(Light); -// -// std::move(table).Element(); - class Table; class TableSelection; +/// @brief Table is a utility to draw tables. +/// +/// **example** +/// ```cpp +/// auto table = Table({ +/// {"X", "Y"}, +/// {"-1", "1"}, +/// {"+0", "0"}, +/// {"+1", "1"}, +/// }); +/// +/// table.SelectAll().Border(LIGHT); +/// table.SelectRow(1).Border(DOUBLE); +/// table.SelectRow(1).SeparatorInternal(LIGHT); +/// +/// std::move(table).Render(); +/// ``` +/// +/// @ingroup dom class Table { public: Table(); diff --git a/include/ftxui/screen/box.hpp b/include/ftxui/screen/box.hpp index 128362d9..192afff4 100644 --- a/include/ftxui/screen/box.hpp +++ b/include/ftxui/screen/box.hpp @@ -6,6 +6,13 @@ namespace ftxui { +/// @brief Box is a structure that represents a rectangular area in a 2D space. +/// +/// It is defined by its minimum and maximum coordinates along the x and y axes. +/// Note that the coordinates are inclusive, meaning that the box includes both +/// the minimum and maximum values. +/// +/// @ingroup screen struct Box { int x_min = 0; int x_max = 0; diff --git a/include/ftxui/screen/color.hpp b/include/ftxui/screen/color.hpp index 1489dca6..8c785b26 100644 --- a/include/ftxui/screen/color.hpp +++ b/include/ftxui/screen/color.hpp @@ -15,7 +15,9 @@ namespace ftxui { -/// @brief A class representing terminal colors. +/// @brief Color is a class that represents a color in the terminal user +/// interface. +/// /// @ingroup screen class Color { public: diff --git a/include/ftxui/screen/color_info.hpp b/include/ftxui/screen/color_info.hpp index 8e625e81..84f4bebc 100644 --- a/include/ftxui/screen/color_info.hpp +++ b/include/ftxui/screen/color_info.hpp @@ -9,6 +9,10 @@ namespace ftxui { +/// @brief ColorInfo is a structure that contains information about the terminal +/// color palette. +/// +/// @ingroup screen struct ColorInfo { const char* name; uint8_t index_256; diff --git a/include/ftxui/screen/terminal.hpp b/include/ftxui/screen/terminal.hpp index 051aed08..10d4199a 100644 --- a/include/ftxui/screen/terminal.hpp +++ b/include/ftxui/screen/terminal.hpp @@ -5,6 +5,9 @@ #define FTXUI_SCREEN_TERMINAL_HPP namespace ftxui { + +/// @brief Dimensions is a structure that represents the size of the terminal +/// @ingroup screen struct Dimensions { int dimx; int dimy; @@ -14,6 +17,9 @@ namespace Terminal { Dimensions Size(); void SetFallbackSize(const Dimensions& fallbackSize); +/// @brief Color is an enumeration that represents the color support of the +/// terminal. +/// @ingroup screen enum Color { Palette1, Palette16,