From f53dc139e9fd24fee0b7ff0c104024e03879a015 Mon Sep 17 00:00:00 2001 From: ArthurSonzogni Date: Sat, 10 Jul 2021 11:50:17 +0200 Subject: [PATCH] Add documentation for options. --- examples/component/menu_style.cpp | 40 ++++++------- include/ftxui/component/component_options.hpp | 60 +++++++++++-------- include/ftxui/util/ref.hpp | 12 ++-- src/ftxui/component/checkbox.cpp | 4 +- src/ftxui/component/menu.cpp | 8 +-- src/ftxui/component/radiobox.cpp | 9 +-- src/ftxui/component/toggle.cpp | 8 +-- src/ftxui/dom/util.cpp | 2 - 8 files changed, 77 insertions(+), 66 deletions(-) diff --git a/examples/component/menu_style.cpp b/examples/component/menu_style.cpp index 9b6a7fc..1eb2bee 100644 --- a/examples/component/menu_style.cpp +++ b/examples/component/menu_style.cpp @@ -27,46 +27,46 @@ int main(int argc, const char* argv[]) { int menu_6_selected_ = 0; MenuOption option_1; - option_1.focused_style = bold | color(Color::Blue); - option_1.selected_style = color(Color::Blue); - option_1.selected_focused_style = bold | color(Color::Blue); + option_1.style_focused = bold | color(Color::Blue); + option_1.style_selected = color(Color::Blue); + option_1.style_selected_focused = bold | color(Color::Blue); option_1.on_enter = screen.ExitLoopClosure(); auto menu_1_ = Menu(&entries, &menu_1_selected_, &option_1); MenuOption option_2; - option_2.focused_style = bold | color(Color::Blue); - option_2.selected_style = color(Color::Blue); - option_2.selected_focused_style = bold | color(Color::Blue); + option_2.style_focused = bold | color(Color::Blue); + option_2.style_selected = color(Color::Blue); + option_2.style_selected_focused = bold | color(Color::Blue); option_2.on_enter = screen.ExitLoopClosure(); auto menu_2_ = Menu(&entries, &menu_2_selected_, &option_2); MenuOption option_3; - option_3.selected_style = color(Color::Blue); - option_3.focused_style = bgcolor(Color::Blue); - option_3.selected_focused_style = bgcolor(Color::Blue); + option_3.style_selected = color(Color::Blue); + option_3.style_focused = bgcolor(Color::Blue); + option_3.style_selected_focused = bgcolor(Color::Blue); option_3.on_enter = screen.ExitLoopClosure(); auto menu_3_ = Menu(&entries, &menu_3_selected_, &option_3); MenuOption option_4; - option_4.selected_style = bgcolor(Color::Blue); - option_4.focused_style = bgcolor(Color::BlueLight); - option_4.selected_focused_style = bgcolor(Color::BlueLight); + option_4.style_selected = bgcolor(Color::Blue); + option_4.style_focused = bgcolor(Color::BlueLight); + option_4.style_selected_focused = bgcolor(Color::BlueLight); option_4.on_enter = screen.ExitLoopClosure(); auto menu_4_ = Menu(&entries, &menu_4_selected_, &option_4); MenuOption option_5; - option_5.normal_style = bgcolor(Color::Blue); - option_5.selected_style = bgcolor(Color::Yellow); - option_5.focused_style = bgcolor(Color::Red); - option_5.selected_focused_style = bgcolor(Color::Red); + option_5.style_normal = bgcolor(Color::Blue); + option_5.style_selected = bgcolor(Color::Yellow); + option_5.style_focused = bgcolor(Color::Red); + option_5.style_selected_focused = bgcolor(Color::Red); option_5.on_enter = screen.ExitLoopClosure(); auto menu_5_ = Menu(&entries, &menu_5_selected_, &option_5); MenuOption option_6; - option_6.normal_style = dim | color(Color::Blue); - option_6.selected_style = color(Color::Blue); - option_6.focused_style = bold | color(Color::Blue); - option_6.selected_focused_style = bold | color(Color::Blue); + option_6.style_normal = dim | color(Color::Blue); + option_6.style_selected = color(Color::Blue); + option_6.style_focused = bold | color(Color::Blue); + option_6.style_selected_focused = bold | color(Color::Blue); option_6.on_enter = screen.ExitLoopClosure(); auto menu_6_ = Menu(&entries, &menu_6_selected_, &option_6); diff --git a/include/ftxui/component/component_options.hpp b/include/ftxui/component/component_options.hpp index a734178..3fdf0bf 100644 --- a/include/ftxui/component/component_options.hpp +++ b/include/ftxui/component/component_options.hpp @@ -5,56 +5,68 @@ namespace ftxui { +/// @brief Option for the Menu component. struct MenuOption { - Decorator normal_style = nothing; - Decorator focused_style = inverted; - Decorator selected_style = bold; - Decorator selected_focused_style = focused_style | selected_style; + Decorator style_normal = nothing; /// style. + Decorator style_focused = inverted; /// Style when focused. + Decorator style_selected = bold; /// Style when selected. + Decorator style_selected_focused = + Decorator(inverted) | bold; /// Style when selected and focused. - // State update callback. - std::function on_change = []() {}; - std::function on_enter = []() {}; + /// Called when the selected entry changes. + std::function on_change = [] {}; + /// Called when the user presses enter. + std::function on_enter = [] {}; }; +/// @brief Option for the Button component. struct ButtonOption { + /// Whether to show a border around the button. bool border = true; }; +/// @brief Option for the Checkbox component. struct CheckboxOption { - std::wstring checked = L"▣ "; /// Prefix for a "checked" state. - std::wstring unchecked = L"☐ "; /// Prefix for a "unchecked" state. - - Decorator focused_style = inverted; /// Decorator used when focused. - Decorator unfocused_style = nothing; /// Decorator used when unfocused. + std::wstring style_checked = L"▣ "; /// Prefix for a "checked" state. + std::wstring style_unchecked = L"☐ "; /// Prefix for a "unchecked" state. + Decorator style_focused = inverted; /// Decorator used when focused. + Decorator style_unfocused = nothing; /// Decorator used when unfocused. /// Called when the user change the state. std::function on_change = []() {}; }; +/// @brief Option for the Input component. struct InputOption { + /// Called when the content changes. std::function on_change = [] {}; + /// Called when the user presses enter. std::function on_enter = [] {}; }; +/// @brief Option for the Radiobox component. struct RadioboxOption { - std::wstring checked = L"◉ "; - std::wstring unchecked = L"○ "; - - Decorator focused_style = inverted; - Decorator unfocused_style = nothing; + std::wstring style_checked = L"◉ "; /// Prefix for a "checked" state. + std::wstring style_unchecked = L"○ "; /// Prefix for a "unchecked" state. + Decorator style_focused = inverted; /// Decorator used when focused. + Decorator style_unfocused = nothing; /// Decorator used when unfocused. + /// Called when the selected entry changes. std::function on_change = []() {}; }; +/// @brief Option for the Toggle component. struct ToggleOption { - Decorator normal_style = dim; - Decorator focused_style = inverted; - Decorator selected_style = bold; - Decorator selected_focused_style = focused_style | selected_style; + Decorator style_normal = nothing; /// style. + Decorator style_focused = inverted; /// Style when focused. + Decorator style_selected = bold; /// Style when selected. + Decorator style_selected_focused = + Decorator(inverted) | bold; /// Style when selected and focused. - // Callback. - std::function on_change = []() {}; - std::function on_enter = []() {}; + /// Called when the selected entry changes. + std::function on_change = [] {}; + /// Called when the user presses enter. + std::function on_enter = [] {}; }; }; // namespace ftxui diff --git a/include/ftxui/util/ref.hpp b/include/ftxui/util/ref.hpp index 678c528..68b2738 100644 --- a/include/ftxui/util/ref.hpp +++ b/include/ftxui/util/ref.hpp @@ -6,12 +6,12 @@ namespace ftxui { -// An adapter for a const object referenced or owned. +/// @brief An adapter. Own or reference a constant object. template class ConstRef { public: ConstRef() {} - ConstRef(T t): owned_(t) {} + ConstRef(T t) : owned_(t) {} ConstRef(const T* t) : address_(t) {} const T& operator*() { return address_ ? *address_ : owned_; } const T* operator->() { return address_ ? address_ : &owned_; } @@ -21,8 +21,8 @@ class ConstRef { const T* address_ = nullptr; }; -/// @brief For convenience, this class convert multiple mutable string -/// references toward a shared representation. +/// @brief An adapter. Own or reference a constant string. For convenience, this +/// class convert multiple mutable string toward a shared representation. class StringRef { public: StringRef(std::wstring* ref) : address_(ref) {} @@ -37,8 +37,8 @@ class StringRef { std::wstring* address_ = nullptr; }; -/// @brief For convenience, this class convert multiple immutable string -/// references toward shared representation. +/// @brief An adapter. Own or reference a constant string. For convenience, this +/// class convert multiple immutable string toward a shared representation. class ConstStringRef { public: ConstStringRef(const std::wstring* ref) : address_(ref) {} diff --git a/src/ftxui/component/checkbox.cpp b/src/ftxui/component/checkbox.cpp index a1461c7..9324689 100644 --- a/src/ftxui/component/checkbox.cpp +++ b/src/ftxui/component/checkbox.cpp @@ -57,9 +57,9 @@ CheckboxBase::CheckboxBase(ConstStringRef label, Element CheckboxBase::Render() { bool is_focused = Focused(); - auto style = is_focused ? option_->focused_style : option_->unfocused_style; + auto style = is_focused ? option_->style_focused : option_->style_unfocused; auto focus_management = is_focused ? focus : *state_ ? select : nothing; - return hbox(text(*state_ ? option_->checked : option_->unchecked), + return hbox(text(*state_ ? option_->style_checked : option_->style_unchecked), text(*label_) | style | focus_management) | reflect(box_); } diff --git a/src/ftxui/component/menu.cpp b/src/ftxui/component/menu.cpp index dd4b81f..6af46df 100644 --- a/src/ftxui/component/menu.cpp +++ b/src/ftxui/component/menu.cpp @@ -62,10 +62,10 @@ Element MenuBase::Render() { bool is_focused = (focused == int(i)) && is_menu_focused; bool is_selected = (*selected_ == int(i)); - auto style = is_selected ? (is_focused ? option_->selected_focused_style - : option_->selected_style) - : (is_focused ? option_->focused_style - : option_->normal_style); + auto style = is_selected ? (is_focused ? option_->style_selected_focused + : option_->style_selected) + : (is_focused ? option_->style_focused + : option_->style_normal); auto focus_management = !is_selected ? nothing : is_menu_focused ? focus : select; diff --git a/src/ftxui/component/radiobox.cpp b/src/ftxui/component/radiobox.cpp index 5288883..cce7c1c 100644 --- a/src/ftxui/component/radiobox.cpp +++ b/src/ftxui/component/radiobox.cpp @@ -69,14 +69,15 @@ Element RadioboxBase::Render() { bool is_focused = Focused(); boxes_.resize(entries_->size()); for (size_t i = 0; i < entries_->size(); ++i) { - auto style = (focused == int(i) && is_focused) ? option_->focused_style - : option_->unfocused_style; + auto style = (focused == int(i) && is_focused) ? option_->style_focused + : option_->style_unfocused; auto focus_management = (focused != int(i)) ? nothing : is_focused ? focus : select; - const std::wstring& symbol = - *selected_ == int(i) ? option_->checked : option_->unchecked; + const std::wstring& symbol = *selected_ == int(i) + ? option_->style_checked + : option_->style_unchecked; elements.push_back(hbox(text(symbol), text(entries_->at(i)) | style) | focus_management | reflect(boxes_[i])); } diff --git a/src/ftxui/component/toggle.cpp b/src/ftxui/component/toggle.cpp index 72a2860..0eb36c0 100644 --- a/src/ftxui/component/toggle.cpp +++ b/src/ftxui/component/toggle.cpp @@ -38,10 +38,10 @@ Element ToggleBase::Render() { bool is_focused = (focused == int(i)) && is_toggle_focused; bool is_selected = (*selected_ == int(i)); - auto style = is_selected ? (is_focused ? option_->selected_focused_style - : option_->selected_style) - : (is_focused ? option_->focused_style - : option_->normal_style); + auto style = is_selected ? (is_focused ? option_->style_selected_focused + : option_->style_selected) + : (is_focused ? option_->style_focused + : option_->style_normal); auto focus_management = !is_selected ? nothing : is_toggle_focused ? focus : select; diff --git a/src/ftxui/dom/util.cpp b/src/ftxui/dom/util.cpp index 9a49161..0ac1247 100644 --- a/src/ftxui/dom/util.cpp +++ b/src/ftxui/dom/util.cpp @@ -6,13 +6,11 @@ namespace ftxui { -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