From 114ab4ae2a089a386773b07c193244664ddc277e Mon Sep 17 00:00:00 2001 From: ArthurSonzogni Date: Sun, 16 Aug 2020 02:24:50 +0200 Subject: [PATCH] Add more documentation. --- doc/Doxyfile.in | 4 +- doc/doxygen_layout.xml | 11 ++-- doc/example_list.md | 35 ----------- doc/mainpage.md | 14 +++++ include/ftxui/component/checkbox.hpp | 20 +++--- include/ftxui/component/component.hpp | 5 +- include/ftxui/component/container.hpp | 5 +- include/ftxui/component/event.hpp | 3 + include/ftxui/component/input.hpp | 2 + include/ftxui/component/menu.hpp | 2 + include/ftxui/component/radiobox.hpp | 3 + include/ftxui/component/toggle.hpp | 2 + include/ftxui/dom/elements.hpp | 12 ++-- include/ftxui/util/autoreset.hpp | 1 + src/ftxui/component/component.cpp | 88 +++++++++++++++++++-------- src/ftxui/dom/blink.cpp | 2 +- src/ftxui/dom/border.cpp | 4 +- src/ftxui/dom/color.cpp | 14 ++--- src/ftxui/dom/dbox.cpp | 2 +- src/ftxui/dom/flex.cpp | 19 ++++++ src/ftxui/dom/frame.cpp | 2 +- src/ftxui/dom/inverted.cpp | 3 + src/ftxui/dom/node.cpp | 10 +++ src/ftxui/dom/paragraph.cpp | 5 ++ src/ftxui/dom/size.cpp | 6 ++ src/ftxui/dom/spinner.cpp | 24 +++++--- src/ftxui/dom/text.cpp | 41 +++++++++++++ src/ftxui/dom/underlined.cpp | 2 + src/ftxui/dom/util.cpp | 46 +++++++++++--- src/ftxui/dom/vbox.cpp | 1 + src/ftxui/screen/box.cpp | 2 + src/ftxui/screen/screen.cpp | 62 ++++++++++--------- src/ftxui/screen/string.cpp | 2 + 33 files changed, 310 insertions(+), 144 deletions(-) delete mode 100644 doc/example_list.md diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 9b334e0..4599a80 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -162,7 +162,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = ../.. # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -2319,7 +2319,7 @@ TEMPLATE_RELATIONS = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDE_GRAPH = YES +INCLUDE_GRAPH = NO # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are # set to YES then doxygen will generate a graph for each documented file showing diff --git a/doc/doxygen_layout.xml b/doc/doxygen_layout.xml index 00a1032..1beab94 100644 --- a/doc/doxygen_layout.xml +++ b/doc/doxygen_layout.xml @@ -96,17 +96,18 @@ + + + + + + - - - - - diff --git a/doc/example_list.md b/doc/example_list.md deleted file mode 100644 index 483fa6b..0000000 --- a/doc/example_list.md +++ /dev/null @@ -1,35 +0,0 @@ -# Examples -@example ./examples/util/print_key_press.cpp -@example ./examples/dom/dbox.cpp -@example ./examples/dom/separator.cpp -@example ./examples/dom/style_color.cpp -@example ./examples/dom/paragraph.cpp -@example ./examples/dom/style_blink.cpp -@example ./examples/dom/style_dim.cpp -@example ./examples/dom/style_inverted.cpp -@example ./examples/dom/graph.cpp -@example ./examples/dom/package_manager.cpp -@example ./examples/dom/window.cpp -@example ./examples/dom/html_like.cpp -@example ./examples/dom/border.cpp -@example ./examples/dom/style_underlined.cpp -@example ./examples/dom/gauge.cpp -@example ./examples/dom/style_bold.cpp -@example ./examples/dom/spinner.cpp -@example ./examples/dom/style_gallery.cpp -@example ./examples/dom/vbox_hbox.cpp -@example ./examples/dom/size.cpp -@example ./examples/dom/hflow.cpp -@example ./examples/component/tab_vertical.cpp -@example ./examples/component/gallery.cpp -@example ./examples/component/checkbox.cpp -@example ./examples/component/checkbox_in_frame.cpp -@example ./examples/component/menu2.cpp -@example ./examples/component/tab_horizontal.cpp -@example ./examples/component/input.cpp -@example ./examples/component/homescreen.cpp -@example ./examples/component/radiobox.cpp -@example ./examples/component/menu.cpp -@example ./examples/component/menu_style.cpp -@example ./examples/component/radiobox_in_frame.cpp -@example ./examples/component/toggle.cpp diff --git a/doc/mainpage.md b/doc/mainpage.md index e9bb81a..4692577 100644 --- a/doc/mainpage.md +++ b/doc/mainpage.md @@ -341,26 +341,40 @@ its keyboard. They handle keyboard navigation, including component focus. ## Input +The component: \ref ftxui::Input + @htmlonly @endhtmlonly ## Menu + +The component: \ref ftxui::Menu + @htmlonly @endhtmlonly ## Toggle. + +The component: \ref ftxui::Toggle + @htmlonly @endhtmlonly ## CheckBox + +The component: \ref ftxui::CheckBox + @htmlonly @endhtmlonly ## RadioBox + +The component: \ref ftxui::RadioBox + @htmlonly @endhtmlonly diff --git a/include/ftxui/component/checkbox.hpp b/include/ftxui/component/checkbox.hpp index 046abaa..711490f 100644 --- a/include/ftxui/component/checkbox.hpp +++ b/include/ftxui/component/checkbox.hpp @@ -7,27 +7,29 @@ namespace ftxui { +/// @brief A Checkbox. It can be checked or unchecked.Display an element on a ftxui::Screen. +/// @ingroup dom class CheckBox : public Component { public: // Constructor. CheckBox() = default; ~CheckBox() override = default; - bool state = false; - std::wstring label = L"label"; + bool state = false; // The current state. true=checked, false:unchecked. + std::wstring label = L"label"; // The CheckBox label. #if defined(_WIN32) - std::wstring checked = L"[X] "; - std::wstring unchecked = L"[ ] "; + std::wstring checked = L"[X] "; /// Prefix for a "checked" state. + std::wstring unchecked = L"[ ] "; /// Prefix for an "unchecked" state. #else - std::wstring checked = L"▣ "; - std::wstring unchecked = L"☐ "; + std::wstring checked = L"▣ "; /// Prefix for a "checked" state. + std::wstring unchecked = L"☐ "; /// Prefix for a "unchecked" state. #endif - Decorator focused_style = inverted; - Decorator unfocused_style = nothing; + Decorator focused_style = inverted; /// Decorator used when focused. + Decorator unfocused_style = nothing; /// Decorator used when unfocused. - // State update callback. + /// Called when the user change the state of the CheckBox. std::function on_change = []() {}; // Component implementation. diff --git a/include/ftxui/component/component.hpp b/include/ftxui/component/component.hpp index 3c7129c..5f26e75 100644 --- a/include/ftxui/component/component.hpp +++ b/include/ftxui/component/component.hpp @@ -9,6 +9,9 @@ namespace ftxui { class Delegate; class Focus; +/// @brief It implement rendering itself as ftxui::Element. It implement +/// keyboard navigation by responding to ftxui::Event. +/// @ingroup component class Component { public: // Constructor/Destructor. @@ -16,7 +19,7 @@ class Component { virtual ~Component(); // Component hierarchy. - Component* Parent() { return parent_; } + Component* Parent(); void Add(Component* children); // Renders the component. diff --git a/include/ftxui/component/container.hpp b/include/ftxui/component/container.hpp index 444fa0a..2f14b13 100644 --- a/include/ftxui/component/container.hpp +++ b/include/ftxui/component/container.hpp @@ -5,10 +5,7 @@ namespace ftxui { -// A component where focus and events are automatically handled for you. -// List of container: -// -// Please use HorizontalContainer or VerticalContainer. +/// @brief A component where focus and events are automatically handled for you. class Container : public Component { public: static Container Vertical(); diff --git a/include/ftxui/component/event.hpp b/include/ftxui/component/event.hpp index da10938..6f9f0b1 100644 --- a/include/ftxui/component/event.hpp +++ b/include/ftxui/component/event.hpp @@ -9,6 +9,9 @@ namespace ftxui { +/// @brief Represent an event. It can be key press event, a terminal resize, or +/// more ... +// // Documentation: // https://invisible-island.net/xterm/ctlseqs/ctlseqs.html // diff --git a/include/ftxui/component/input.hpp b/include/ftxui/component/input.hpp index e301eb4..d20cc85 100644 --- a/include/ftxui/component/input.hpp +++ b/include/ftxui/component/input.hpp @@ -7,6 +7,8 @@ namespace ftxui { +/// @brief An input box. The user can type text into it. +/// @ingroup component. class Input : public Component { public: // Constructor. diff --git a/include/ftxui/component/menu.hpp b/include/ftxui/component/menu.hpp index 66108e0..ece6fe8 100644 --- a/include/ftxui/component/menu.hpp +++ b/include/ftxui/component/menu.hpp @@ -8,6 +8,8 @@ namespace ftxui { +/// @brief A list of items. The user can navigate through them. +/// @ingroup component class Menu : public Component { public: // Constructor. diff --git a/include/ftxui/component/radiobox.hpp b/include/ftxui/component/radiobox.hpp index 793e41d..aaf9828 100644 --- a/include/ftxui/component/radiobox.hpp +++ b/include/ftxui/component/radiobox.hpp @@ -7,6 +7,9 @@ namespace ftxui { +/// @brief A list of selectable element. One and only one can be selected at +/// the same time. +/// @ingroup component class RadioBox : public Component { public: // Constructor. diff --git a/include/ftxui/component/toggle.hpp b/include/ftxui/component/toggle.hpp index d0f1290..bbe095c 100644 --- a/include/ftxui/component/toggle.hpp +++ b/include/ftxui/component/toggle.hpp @@ -8,6 +8,8 @@ namespace ftxui { +/// @brief An horizontal list of elements. The user can navigate through them. +/// @ingroup component class Toggle : public Component { public: // Constructor. diff --git a/include/ftxui/dom/elements.hpp b/include/ftxui/dom/elements.hpp index 1e20bb5..012f5da 100644 --- a/include/ftxui/dom/elements.hpp +++ b/include/ftxui/dom/elements.hpp @@ -61,13 +61,13 @@ Element flex(Element); // Expand/Minimize if possible/needed. Element flex_grow(Element); // Expand element if possible. Element flex_shrink(Element); // Minimize element if needed. -Element xflex(Element); // Expand/Minimize if possible/needed. -Element xflex_grow(Element); // Expand element if possible. -Element xflex_shrink(Element); // Minimize element if needed. +Element xflex(Element); // Expand/Minimize if possible/needed on X axis. +Element xflex_grow(Element); // Expand element if possible on X axis. +Element xflex_shrink(Element); // Minimize element if needed on X axis. -Element yflex(Element); // Expand/Minimize if possible/needed. -Element yflex_grow(Element); // Expand element if possible. -Element yflex_shrink(Element); // Minimize element if needed. +Element yflex(Element); // Expand/Minimize if possible/needed on Y axis. +Element yflex_grow(Element); // Expand element if possible on Y axis. +Element yflex_shrink(Element); // Minimize element if needed on Y axis. Element notflex(Element); // Reset the flex attribute. Element filler(); // A blank expandable element. diff --git a/include/ftxui/util/autoreset.hpp b/include/ftxui/util/autoreset.hpp index f71c5df..5c27dc8 100644 --- a/include/ftxui/util/autoreset.hpp +++ b/include/ftxui/util/autoreset.hpp @@ -3,6 +3,7 @@ namespace ftxui { +/// Assign a value to a variable, reset its old value when going out of scope. template class AutoReset { public: diff --git a/src/ftxui/component/component.cpp b/src/ftxui/component/component.cpp index 6588aee..63e7ede 100644 --- a/src/ftxui/component/component.cpp +++ b/src/ftxui/component/component.cpp @@ -5,28 +5,44 @@ #include namespace ftxui { -void Component::Detach() { - if (!parent_) - return; - auto it = std::find(std::begin(parent_->children_), - std::end(parent_->children_), this); - parent_->children_.erase(it); -} - -void Component::Attach(Component* parent) { - Detach(); - parent_ = parent; - parent_->children_.push_back(this); -} - -void Component::Add(Component* child) { - child->Attach(this); -} Component::~Component() { Detach(); } +/// @brief Return the parent Component, or nul if any. +/// @see Attach +/// @see Detach +/// @see Parent +/// @ingroup component +Component* Component::Parent() { + return parent_; +} + +/// @brief Add a children. +/// @@param child The child to be attached. +/// @ingroup component +void Component::Add(Component* child) { + child->Attach(this); +} + +/// @brief Draw the component. +/// Build a ftxui::Element to be drawn on the ftxi::Screen representing this +/// ftxui::Component. +/// @ingroup component +Element Component::Render() { + if (children_.size() == 1) + return children_.front()->Render(); + + return text(L"Not implemented component"); +} + +/// @brief Called in response to an event. +/// @param event The event. +/// @return True when the event has been handled. +/// The default implementation called OnEvent on every child until one return +/// true. If none returns true, return false. +/// @ingroup component bool Component::OnEvent(Event event) { for (Component* child : children_) { if (child->OnEvent(event)) @@ -35,17 +51,16 @@ bool Component::OnEvent(Event event) { return false; } +/// @brief Return the currently Active child. +/// @return the currently Active child. +/// @ingroup component Component* Component::ActiveChild() { return children_.empty() ? nullptr : children_.front(); } -Element Component::Render() { - if (children_.size() == 1) - return children_.front()->Render(); - - return text(L"Not implemented component"); -} - +/// @brief Returns if the elements if focused by the user. +/// True when the Component is focused by the user. An element is Focused when +/// it is with all its ancestors the ActiveChild() of their parents. bool Component::Focused() { Component* current = this; for (;;) { @@ -58,6 +73,31 @@ bool Component::Focused() { } } +/// @brief Detach this children from its parent. +/// @see Attach +/// @see Detach +/// @see Parent +/// @ingroup component +void Component::Detach() { + if (!parent_) + return; + auto it = std::find(std::begin(parent_->children_), + std::end(parent_->children_), this); + parent_->children_.erase(it); +} + +/// @brief Attach this element to its parent. +/// @see Attach +/// @see Detach +/// @see Parent +/// @ingroup component +void Component::Attach(Component* parent) { + Detach(); + parent_ = parent; + parent_->children_.push_back(this); +} + + } // namespace ftxui // Copyright 2020 Arthur Sonzogni. All rights reserved. diff --git a/src/ftxui/dom/blink.cpp b/src/ftxui/dom/blink.cpp index bf07de0..8356d83 100644 --- a/src/ftxui/dom/blink.cpp +++ b/src/ftxui/dom/blink.cpp @@ -18,7 +18,7 @@ class Blink : public NodeDecorator { } }; -/// @brief The text drawn alternate in between visible and hidden. +/// @brief The text drawn alternates in between visible and hidden. /// @ingroup dom Element blink(Element child) { return std::make_shared(unpack(std::move(child))); diff --git a/src/ftxui/dom/border.cpp b/src/ftxui/dom/border.cpp index cd0da33..8e5e8c1 100644 --- a/src/ftxui/dom/border.cpp +++ b/src/ftxui/dom/border.cpp @@ -129,7 +129,7 @@ Element border(Element child) { /// @param title The title of the window. /// @param content The element to be wrapped. /// @ingroup dom -/// @seealso border +/// @see border /// /// ### Example /// @@ -152,7 +152,7 @@ Element window(Element title, Element content) { /// @brief Same as border but with a constant Pixel around the element. /// @ingroup dom -/// @seealso border +/// @see border Decorator borderWith(Pixel pixel) { return [pixel](Element child) { return std::make_shared(unpack(std::move(child)), pixel); diff --git a/src/ftxui/dom/color.cpp b/src/ftxui/dom/color.cpp index c48fdc6..023dc8f 100644 --- a/src/ftxui/dom/color.cpp +++ b/src/ftxui/dom/color.cpp @@ -39,8 +39,8 @@ class FgColor : public NodeDecorator { }; /// @brief Set the foreground color of an element. -/// @param The color of the output element. -/// @param The input element. +/// @param color The color of the output element. +/// @param child The input element. /// @return The output element colored. /// @ingroup dom /// @@ -54,8 +54,8 @@ Element color(Color color, Element child) { } /// @brief Set the background color of an element. -/// @param The color of the output element. -/// @param The input element. +/// @param color The color of the output element. +/// @param child The input element. /// @return The output element colored. /// @ingroup dom /// @@ -83,7 +83,7 @@ Decorator color(Color c) { } /// @brief Decorate using a background color. -/// @param The background color to be applied. +/// @param color The background color to be applied. /// @return The Decorator applying the color. /// @ingroup dom /// @@ -92,8 +92,8 @@ Decorator color(Color c) { /// ```cpp /// Element document = text(L"red") | bgcolor(Color::Red); /// ``` -Decorator bgcolor(Color c) { - return [c](Element child) { return bgcolor(c, std::move(child)); }; +Decorator bgcolor(Color color) { + return [color](Element child) { return bgcolor(color, std::move(child)); }; } } // namespace ftxui diff --git a/src/ftxui/dom/dbox.cpp b/src/ftxui/dom/dbox.cpp index f096417..ea73791 100644 --- a/src/ftxui/dom/dbox.cpp +++ b/src/ftxui/dom/dbox.cpp @@ -40,7 +40,7 @@ class DBox : public Node { }; /// @brief Stack several element on top of each other. -/// @param The input element. +/// @param children The input element. /// @return The right aligned element. /// @ingroup dom Element dbox(Elements children) { diff --git a/src/ftxui/dom/flex.cpp b/src/ftxui/dom/flex.cpp index 2e8705b..bf2942e 100644 --- a/src/ftxui/dom/flex.cpp +++ b/src/ftxui/dom/flex.cpp @@ -92,6 +92,7 @@ Element filler() { /// @brief Make a child element to expand proportionnally to the space left in a /// container. +/// @ingroup dom /// /// #### Examples: /// @@ -114,38 +115,56 @@ Element flex(Element child) { return std::make_shared(function_flex, std::move(child)); } +/// @brief Expand/Minimize if possible/needed on the X axis. +/// @ingroup dom Element xflex(Element child) { return std::make_shared(function_xflex, std::move(child)); } +/// @brief Expand/Minimize if possible/needed on the Y axis. +/// @ingroup dom Element yflex(Element child) { return std::make_shared(function_yflex, std::move(child)); } +/// @brief Expand if possible. +/// @ingroup dom Element flex_grow(Element child) { return std::make_shared(function_flex_grow, std::move(child)); } +/// @brief Expand if possible on the X axis. +/// @ingroup dom Element xflex_grow(Element child) { return std::make_shared(function_xflex_grow, std::move(child)); } +/// @brief Expand if possible on the Y axis. +/// @ingroup dom Element yflex_grow(Element child) { return std::make_shared(function_yflex_grow, std::move(child)); } +/// @brief Minimize if needed. +/// @ingroup dom Element flex_shrink(Element child) { return std::make_shared(function_flex_shrink, std::move(child)); } +/// @brief Minimize if needed on the X axis. +/// @ingroup dom Element xflex_shrink(Element child) { return std::make_shared(function_xflex_shrink, std::move(child)); } +/// @brief Minimize if needed on the Y axis. +/// @ingroup dom Element yflex_shrink(Element child) { return std::make_shared(function_yflex_shrink, std::move(child)); } +/// @brief Make the element not flexible. +/// @ingroup dom Element notflex(Element child) { return std::make_shared(function_not_flex, std::move(child)); } diff --git a/src/ftxui/dom/frame.cpp b/src/ftxui/dom/frame.cpp index 537aabd..7e25c8c 100644 --- a/src/ftxui/dom/frame.cpp +++ b/src/ftxui/dom/frame.cpp @@ -109,7 +109,7 @@ class Frame : public Node { /// @brief Allow an element to be displayed inside a 'virtual' area. It size can /// be larger than its container. In this case only a smaller portion is /// displayed. The view is scrollable to make the focused element visible. -/// @seealso focus +/// @see focus Element frame(Element child) { return std::make_shared(unpack(std::move(child)), true, true); } diff --git a/src/ftxui/dom/inverted.cpp b/src/ftxui/dom/inverted.cpp index 4b06dad..1054990 100644 --- a/src/ftxui/dom/inverted.cpp +++ b/src/ftxui/dom/inverted.cpp @@ -20,6 +20,9 @@ class Inverted : public NodeDecorator { } }; +/// @brief Add a filter that will invert the foreground and the background +/// colors. +/// @ingroup dom Element inverted(Element child) { return std::make_shared(unpack(std::move(child))); } diff --git a/src/ftxui/dom/node.cpp b/src/ftxui/dom/node.cpp index 628356d..d5f08c7 100644 --- a/src/ftxui/dom/node.cpp +++ b/src/ftxui/dom/node.cpp @@ -8,24 +8,34 @@ Node::Node() {} Node::Node(Elements children) : children(std::move(children)) {} Node::~Node() {} +/// @brief Compute how much space an elements needs. +/// @ingroup dom void Node::ComputeRequirement() { for (auto& child : children) child->ComputeRequirement(); } +/// @brief Assign a position and a dimension to an element for drawing. +/// @ingroup dom void Node::SetBox(Box box) { box_ = box; } +/// @brief Display an element on a ftxui::Screen. +/// @ingroup dom void Node::Render(Screen& screen) { for (auto& child : children) child->Render(screen); } +/// @brief Display an element on a ftxui::Screen. +/// @ingroup dom void Render(Screen& screen, const Element& element) { Render(screen, element.get()); } +/// @brief Display an element on a ftxui::Screen. +/// @ingroup dom void Render(Screen& screen, Node* node) { // Step 1: Find what dimension this elements wants to be. node->ComputeRequirement(); diff --git a/src/ftxui/dom/paragraph.cpp b/src/ftxui/dom/paragraph.cpp index 7b9e0e2..7a8a8e7 100644 --- a/src/ftxui/dom/paragraph.cpp +++ b/src/ftxui/dom/paragraph.cpp @@ -4,6 +4,11 @@ namespace ftxui { +/// @brief Return a vector of ftxui::text for every word of the string. This is +/// useful combined with ftxui::hflow. +/// @param the_text The string to be splitted. +/// @ingroup dom +/// @see hflow. Elements paragraph(std::wstring the_text) { Elements output; std::wstringstream ss(the_text); diff --git a/src/ftxui/dom/size.cpp b/src/ftxui/dom/size.cpp index dc6d115..5bb4cb4 100644 --- a/src/ftxui/dom/size.cpp +++ b/src/ftxui/dom/size.cpp @@ -73,6 +73,12 @@ class Size : public Node { int value_; }; +/// @brief Apply a constraint on the size of an element. +/// @param direction Whether the WIDTH of the HEIGHT of the element must be +/// constrained. +/// @param constrain The type of constaint. +/// @param value the value. +/// @ingroup dom Decorator size(Direction direction, Constraint constraint, int value) { return [=](Element e) { return std::make_shared(std::move(e), direction, constraint, value); diff --git a/src/ftxui/dom/spinner.cpp b/src/ftxui/dom/spinner.cpp index a534ea3..58d8c7b 100644 --- a/src/ftxui/dom/spinner.cpp +++ b/src/ftxui/dom/spinner.cpp @@ -241,17 +241,23 @@ static const std::vector>> elements = { L" LOLLOL ", }}}; -Element spinner(int c, size_t index) { - if (c == 0) { - index %= 40; - if (index > 20) - index = 40 - index; - return gauge(index * 0.05); +/// @brief Useful to represent the effect of time and/or events. This display an +/// ASCII art "video". +/// @param charset_index The type of "video". +/// @param image_index The "frame" of the video. You need to increase this for +///every "step". +/// @ingroup dom +Element spinner(int charset_index, size_t image_index) { + if (charset_index == 0) { + image_index %= 40; + if (image_index > 20) + image_index = 40 - image_index; + return gauge(image_index * 0.05); } - c %= elements.size(); - index %= elements[c].size(); + charset_index %= elements.size(); + image_index %= elements[charset_index].size(); std::vector lines; - for (const auto& it : elements[c][index]) + for (const auto& it : elements[charset_index][image_index]) lines.push_back(text(it)); return vbox(std::move(lines)); } diff --git a/src/ftxui/dom/text.cpp b/src/ftxui/dom/text.cpp index 6c90b31..53c3b8b 100644 --- a/src/ftxui/dom/text.cpp +++ b/src/ftxui/dom/text.cpp @@ -64,10 +64,51 @@ class VText : public Node { int width_ = 1; }; +/// @brief Display a pieve of unicode text. +/// @ingroup dom +/// @see ftxui::to_wstring +/// +/// ### Example +/// +/// ```cpp +/// Element document = text(L"Hello world!"); +/// ``` +/// +/// ### Output +/// +/// ```bash +/// Hello world! +/// ``` Element text(std::wstring text) { return std::make_shared(text); } +/// @brief Display a pieve of unicode text vertically. +/// @ingroup dom +/// @see ftxui::to_wstring +/// +/// ### Example +/// +/// ```cpp +/// Element document = vtext(L"Hello world!"); +/// ``` +/// +/// ### Output +/// +/// ```bash +/// H +/// e +/// l +/// l +/// o +/// +/// w +/// o +/// r +/// l +/// d +/// ! +/// ``` Element vtext(std::wstring text) { return std::make_shared(text); } diff --git a/src/ftxui/dom/underlined.cpp b/src/ftxui/dom/underlined.cpp index ade9266..b04a110 100644 --- a/src/ftxui/dom/underlined.cpp +++ b/src/ftxui/dom/underlined.cpp @@ -20,6 +20,8 @@ class Underlined : public NodeDecorator { } }; +/// @brief Make the underlined element to be underlined. +/// @ingroup dom Element underlined(Element child) { return std::make_shared(unpack(std::move(child))); } diff --git a/src/ftxui/dom/util.cpp b/src/ftxui/dom/util.cpp index d4c45e0..82b5292 100644 --- a/src/ftxui/dom/util.cpp +++ b/src/ftxui/dom/util.cpp @@ -2,29 +2,57 @@ namespace ftxui { -Element nothing(Element element) { - return element; -} - +namespace { Decorator compose(Decorator a, Decorator b) { return [a = std::move(a), b = std::move(b)](Element element) { return b(a(std::move(element))); }; } +} // namespace +/// @brief A decoration doing absolutely nothing. +/// @ingroup dom +Element nothing(Element element) { + return element; +} + +/// @brief Compose two decorator into one. +/// @ingroup dom +/// +/// ### Example +/// +/// ```cpp +/// auto decorator = bold | blink; +/// ``` Decorator operator|(Decorator a, Decorator b) { return compose(a, b); } -Elements operator|(Elements es, Decorator d) { +/// @brief From a set of element, apply a decorator to every elements. +/// @return the set of decorated element. +/// @ingroup dom +Elements operator|(Elements elements, Decorator decorator) { Elements output; - for (auto& it : es) - output.push_back(std::move(it) | d); + for (auto& it : elements) + output.push_back(std::move(it) | decorator); return output; } -Element operator|(Element e, Decorator d) { - return d(std::move(e)); +/// @brief From an element, apply a decorator. +/// @return the decorated element. +/// @ingroup dom +/// +/// ### Example +/// +/// Both of these are equivalent: +/// ```cpp +/// bold(text(L"Hello")); +/// ``` +/// ```cpp +/// text(L"Hello") | bold; +/// ``` +Element operator|(Element element, Decorator decorator) { + return decorator(std::move(element)); } } // namespace ftxui diff --git a/src/ftxui/dom/vbox.cpp b/src/ftxui/dom/vbox.cpp index f20951e..e514ae0 100644 --- a/src/ftxui/dom/vbox.cpp +++ b/src/ftxui/dom/vbox.cpp @@ -128,6 +128,7 @@ class VBox : public Node { /// @brief A container displaying elements vertically one by one. /// @param children The elements in the container /// @return The container. +/// @ingroup dom /// /// #### Example /// diff --git a/src/ftxui/screen/box.cpp b/src/ftxui/screen/box.cpp index 85a17e0..b8ed1ee 100644 --- a/src/ftxui/screen/box.cpp +++ b/src/ftxui/screen/box.cpp @@ -3,6 +3,8 @@ #include namespace ftxui { +/// @return the biggest Box contained in both |a| and |b|. +/// @ingroup screen // static Box Box::Intersection(Box a, Box b) { return Box{ diff --git a/src/ftxui/screen/screen.cpp b/src/ftxui/screen/screen.cpp index 453240f..46a844f 100644 --- a/src/ftxui/screen/screen.cpp +++ b/src/ftxui/screen/screen.cpp @@ -67,14 +67,46 @@ void WindowsEmulateVT100Terminal() { } #endif +void UpdatePixelStyle(std::wstringstream& ss, Pixel& previous, Pixel& next) { + if (next.bold != previous.bold) + ss << (next.bold ? BOLD_SET : BOLD_RESET); + + if (next.dim != previous.dim) + ss << (next.dim ? DIM_SET : DIM_RESET); + + if (next.underlined != previous.underlined) + ss << (next.underlined ? UNDERLINED_SET : UNDERLINED_RESET); + + if (next.blink != previous.blink) + ss << (next.blink ? BLINK_SET : BLINK_RESET); + + if (next.inverted != previous.inverted) + ss << (next.inverted ? INVERTED_SET : INVERTED_RESET); + + if (next.foreground_color != previous.foreground_color || + next.background_color != previous.background_color) { + ss << L"\x1B[" + + to_wstring(std::to_string((uint8_t)next.foreground_color)) + L"m"; + ss << L"\x1B[" + + to_wstring(std::to_string(10 + (uint8_t)next.background_color)) + + L"m"; + } + + previous = next; +} + } // namespace /// A fixed dimension. +/// @see Fit +/// @see Full Dimension Dimension::Fixed(int v) { return Dimension{v, v}; } /// The minimal dimension that will fit the given element. +/// @see Fixed +/// @see Full Dimension Dimension::Fit(Element& e) { e->ComputeRequirement(); Terminal::Dimensions size = Terminal::Size(); @@ -83,6 +115,8 @@ Dimension Dimension::Fit(Element& e) { } /// Use the terminal dimensions. +/// @see Fixed +/// @see Fit Dimension Dimension::Full() { Terminal::Dimensions size = Terminal::Size(); return Dimension{size.dimx, size.dimy}; @@ -117,34 +151,6 @@ Screen::Screen(int dimx, int dimy) #endif } -void UpdatePixelStyle(std::wstringstream& ss, Pixel& previous, Pixel& next) { - if (next.bold != previous.bold) - ss << (next.bold ? BOLD_SET : BOLD_RESET); - - if (next.dim != previous.dim) - ss << (next.dim ? DIM_SET : DIM_RESET); - - if (next.underlined != previous.underlined) - ss << (next.underlined ? UNDERLINED_SET : UNDERLINED_RESET); - - if (next.blink != previous.blink) - ss << (next.blink ? BLINK_SET : BLINK_RESET); - - if (next.inverted != previous.inverted) - ss << (next.inverted ? INVERTED_SET : INVERTED_RESET); - - if (next.foreground_color != previous.foreground_color || - next.background_color != previous.background_color) { - ss << L"\x1B[" + - to_wstring(std::to_string((uint8_t)next.foreground_color)) + L"m"; - ss << L"\x1B[" + - to_wstring(std::to_string(10 + (uint8_t)next.background_color)) + - L"m"; - } - - previous = next; -} - /// Produce a std::string that can be used to print the Screen on the terminal. std::string Screen::ToString() { std::wstringstream ss; diff --git a/src/ftxui/screen/string.cpp b/src/ftxui/screen/string.cpp index 215a78e..d0ddcbb 100644 --- a/src/ftxui/screen/string.cpp +++ b/src/ftxui/screen/string.cpp @@ -9,11 +9,13 @@ namespace ftxui { #pragma warning(disable : 4996) // codecvt_utf8_utf16 is deprecated #endif +/// Convert a UTF8 std::string into a std::wstring. std::string to_string(const std::wstring& s) { std::wstring_convert> converter; return converter.to_bytes(s); } +/// Convert a std::wstring into a UTF8 std::string. std::wstring to_wstring(const std::string& s) { std::wstring_convert> converter; return converter.from_bytes(s);