From 49a48820dd63720abaa5f8226908d49db33fe565 Mon Sep 17 00:00:00 2001 From: ArthurSonzogni Date: Sat, 19 Aug 2023 14:56:28 +0200 Subject: [PATCH] Add documentations to every public functions. --- src/ftxui/component/component_options.cpp | 66 +++++++++-- src/ftxui/component/dropdown.cpp | 4 + src/ftxui/component/event.cpp | 17 +++ src/ftxui/component/loop.cpp | 10 ++ src/ftxui/component/maybe.cpp | 7 +- src/ftxui/component/screen_interactive.cpp | 33 ++++++ src/ftxui/component/slider.cpp | 2 +- src/ftxui/dom/blink.cpp | 2 + src/ftxui/dom/bold.cpp | 2 + src/ftxui/dom/border.cpp | 2 + src/ftxui/dom/clear_under.cpp | 2 + src/ftxui/dom/color.cpp | 2 + src/ftxui/dom/dbox.cpp | 2 + src/ftxui/dom/dim.cpp | 2 + src/ftxui/dom/flex.cpp | 4 +- src/ftxui/dom/flexbox_config.cpp | 12 ++ src/ftxui/dom/flexbox_helper.cpp | 3 - src/ftxui/dom/frame.cpp | 132 ++++++++++++++++----- src/ftxui/dom/gauge.cpp | 3 + src/ftxui/dom/graph.cpp | 3 + src/ftxui/dom/gridbox.cpp | 4 +- src/ftxui/dom/hbox.cpp | 3 + src/ftxui/dom/hyperlink.cpp | 2 + src/ftxui/dom/inverted.cpp | 2 + src/ftxui/dom/reflect.cpp | 2 + src/ftxui/dom/separator.cpp | 3 +- src/ftxui/dom/size.cpp | 2 + src/ftxui/dom/table.cpp | 101 ++++++++++++++++ src/ftxui/dom/text.cpp | 3 + src/ftxui/dom/underlined.cpp | 2 + src/ftxui/dom/vbox.cpp | 2 + src/ftxui/screen/terminal.cpp | 8 ++ 32 files changed, 396 insertions(+), 48 deletions(-) diff --git a/src/ftxui/component/component_options.cpp b/src/ftxui/component/component_options.cpp index 37d2e22..b89e65b 100644 --- a/src/ftxui/component/component_options.cpp +++ b/src/ftxui/component/component_options.cpp @@ -13,33 +13,55 @@ namespace ftxui { -void AnimatedColorOption::Set(Color a_inactive, - Color a_active, - animation::Duration a_duration, - animation::easing::Function a_function) { +/// @brief A color option that can be animated. +/// @params _inactive The color when the component is inactive. +/// @params _active The color when the component is active. +/// @params _duration The duration of the animation. +/// @params _function The easing function of the animation. +/// @ingroup component +void AnimatedColorOption::Set(Color _inactive, + Color _active, + animation::Duration _duration, + animation::easing::Function _function) { enabled = true; - inactive = a_inactive; - active = a_active; - duration = a_duration; - function = std::move(a_function); + inactive = _inactive; + active = _active; + duration = _duration; + function = std::move(_function); } +/// @brief Set how the underline should animate. +/// @param d The duration of the animation. +/// @param f The easing function of the animation. +/// @ingroup component void UnderlineOption::SetAnimation(animation::Duration d, animation::easing::Function f) { SetAnimationDuration(d); SetAnimationFunction(std::move(f)); } +/// @brief Set how the underline should animate. +/// @param d The duration of the animation. +/// @ingroup component void UnderlineOption::SetAnimationDuration(animation::Duration d) { leader_duration = d; follower_duration = d; } +/// @brief Set how the underline should animate. +/// @param f The easing function of the animation. +/// @ingroup component void UnderlineOption::SetAnimationFunction(animation::easing::Function f) { leader_function = f; follower_function = std::move(f); } +/// @brief Set how the underline should animate. +/// This is useful to desynchronize the animation of the leader and the +/// follower. +/// @param f_leader The duration of the animation for the leader. +/// @param f_follower The duration of the animation for the follower. +/// @ingroup component void UnderlineOption::SetAnimationFunction( animation::easing::Function f_leader, animation::easing::Function f_follower) { @@ -47,6 +69,9 @@ void UnderlineOption::SetAnimationFunction( follower_function = std::move(f_follower); } +/// @brief Standard options for an horizontal menu. +/// This can be useful to implement a tab bar. +/// @ingroup component // static MenuOption MenuOption::Horizontal() { MenuOption option; @@ -69,6 +94,9 @@ MenuOption MenuOption::Horizontal() { return option; } +/// @brief Standard options for an animated horizontal menu. +/// This can be useful to implement a tab bar. +/// @ingroup component // static MenuOption MenuOption::HorizontalAnimated() { auto option = Horizontal(); @@ -76,6 +104,9 @@ MenuOption MenuOption::HorizontalAnimated() { return option; } +/// @brief Standard options for a vertical menu. +/// This can be useful to implement a list of selectable items. +/// @ingroup component // static MenuOption MenuOption::Vertical() { MenuOption option; @@ -95,6 +126,9 @@ MenuOption MenuOption::Vertical() { return option; } +/// @brief Standard options for an animated vertical menu. +/// This can be useful to implement a list of selectable items. +/// @ingroup component // static MenuOption MenuOption::VerticalAnimated() { auto option = MenuOption::Vertical(); @@ -115,6 +149,9 @@ MenuOption MenuOption::VerticalAnimated() { return option; } +/// @brief Standard options for a horitontal menu with some separator. +/// This can be useful to implement a tab bar. +/// @ingroup component // static MenuOption MenuOption::Toggle() { auto option = MenuOption::Horizontal(); @@ -123,6 +160,7 @@ MenuOption MenuOption::Toggle() { } /// @brief Create a ButtonOption, highlighted using [] characters. +/// @ingroup component // static ButtonOption ButtonOption::Ascii() { ButtonOption option; @@ -135,6 +173,7 @@ ButtonOption ButtonOption::Ascii() { } /// @brief Create a ButtonOption, inverted when focused. +/// @ingroup component // static ButtonOption ButtonOption::Simple() { ButtonOption option; @@ -150,6 +189,7 @@ ButtonOption ButtonOption::Simple() { /// @brief Create a ButtonOption. The button is shown using a border, inverted /// when focused. This is the current default. +/// @ingroup component ButtonOption ButtonOption::Border() { ButtonOption option; option.transform = [](const EntryState& s) { @@ -166,6 +206,7 @@ ButtonOption ButtonOption::Border() { } /// @brief Create a ButtonOption, using animated colors. +/// @ingroup component // static ButtonOption ButtonOption::Animated() { return Animated(Color::Black, Color::GrayLight, // @@ -173,6 +214,7 @@ ButtonOption ButtonOption::Animated() { } /// @brief Create a ButtonOption, using animated colors. +/// @ingroup component // static ButtonOption ButtonOption::Animated(Color color) { return ButtonOption::Animated( @@ -183,6 +225,7 @@ ButtonOption ButtonOption::Animated(Color color) { } /// @brief Create a ButtonOption, using animated colors. +/// @ingroup component // static ButtonOption ButtonOption::Animated(Color background, Color foreground) { // NOLINTBEGIN @@ -195,6 +238,7 @@ ButtonOption ButtonOption::Animated(Color background, Color foreground) { } /// @brief Create a ButtonOption, using animated colors. +/// @ingroup component // static ButtonOption ButtonOption::Animated(Color background, Color foreground, @@ -214,6 +258,7 @@ ButtonOption ButtonOption::Animated(Color background, } /// @brief Option for standard Checkbox. +/// @ingroup component // static CheckboxOption CheckboxOption::Simple() { auto option = CheckboxOption(); @@ -238,6 +283,7 @@ CheckboxOption CheckboxOption::Simple() { } /// @brief Option for standard Radiobox +/// @ingroup component // static RadioboxOption RadioboxOption::Simple() { auto option = RadioboxOption(); @@ -261,6 +307,8 @@ RadioboxOption RadioboxOption::Simple() { return option; } +/// @brief Standard options for the input component. +/// @ingroup component // static InputOption InputOption::Default() { InputOption option; @@ -282,6 +330,8 @@ InputOption InputOption::Default() { return option; } +/// @brief Standard options for a more beautiful input component. +/// @ingroup component // static InputOption InputOption::Spacious() { InputOption option; diff --git a/src/ftxui/component/dropdown.cpp b/src/ftxui/component/dropdown.cpp index 96934e8..a90686e 100644 --- a/src/ftxui/component/dropdown.cpp +++ b/src/ftxui/component/dropdown.cpp @@ -15,6 +15,10 @@ namespace ftxui { +/// @brief A dropdown menu. +/// @ingroup component +/// @param entries The list of entries to display. +/// @param selected The index of the selected entry. Component Dropdown(ConstStringListRef entries, int* selected) { class Impl : public ComponentBase { public: diff --git a/src/ftxui/component/event.cpp b/src/ftxui/component/event.cpp index 801836f..b653074 100644 --- a/src/ftxui/component/event.cpp +++ b/src/ftxui/component/event.cpp @@ -9,6 +9,9 @@ namespace ftxui { +/// @brief An event corresponding to a given typed character. +/// @param input The character typed by the user. +/// @ingroup component // static Event Event::Character(std::string input) { Event event; @@ -17,16 +20,26 @@ Event Event::Character(std::string input) { return event; } +/// @brief An event corresponding to a given typed character. +/// @param c The character typed by the user. +/// @ingroup component // static Event Event::Character(char c) { return Event::Character(std::string{c}); } +/// @brief An event corresponding to a given typed character. +/// @param c The character typed by the user. +/// @ingroup component // static Event Event::Character(wchar_t c) { return Event::Character(to_string(std::wstring{c})); } +/// @brief An event corresponding to a given typed character. +/// @param input The sequence of character send by the terminal. +/// @param mouse The mouse state. +/// @ingroup component // static Event Event::Mouse(std::string input, struct Mouse mouse) { Event event; @@ -36,6 +49,9 @@ Event Event::Mouse(std::string input, struct Mouse mouse) { return event; } +/// @brief An custom event whose meaning is defined by the user of the library. +/// @param input An arbitrary sequence of character defined by the developer. +/// @ingroup component. // static Event Event::Special(std::string input) { Event event; @@ -43,6 +59,7 @@ Event Event::Special(std::string input) { return event; } +/// @internal // static Event Event::CursorReporting(std::string input, int x, int y) { Event event; diff --git a/src/ftxui/component/loop.cpp b/src/ftxui/component/loop.cpp index a003981..b7725b6 100644 --- a/src/ftxui/component/loop.cpp +++ b/src/ftxui/component/loop.cpp @@ -9,6 +9,14 @@ namespace ftxui { +/// @brief A Loop is a wrapper around a Component and a ScreenInteractive. +/// It is used to run a Component in a terminal. +/// @ingroup component +/// @see Component, ScreenInteractive. +/// @see ScreenInteractive::Loop(). +/// @see ScreenInteractive::ExitLoop(). +/// @param screen The screen to use. +/// @param component The component to run. // NOLINTNEXTLINE Loop::Loop(ScreenInteractive* screen, Component component) : screen_(screen), component_(std::move(component)) { @@ -19,6 +27,8 @@ Loop::~Loop() { screen_->PostMain(); } +/// @brief Whether the loop has quitted. +/// @ingroup component bool Loop::HasQuitted() { return screen_->HasQuitted(); } diff --git a/src/ftxui/component/maybe.cpp b/src/ftxui/component/maybe.cpp index 8f5a54b..5289f92 100644 --- a/src/ftxui/component/maybe.cpp +++ b/src/ftxui/component/maybe.cpp @@ -14,6 +14,11 @@ namespace ftxui { +/// @brief Decorate a component |child|. It is shown only when |show| returns +/// true. +/// @param child the compoenent to decorate. +/// @param show a function returning whether |child| should shown. +/// @ingroup component Component Maybe(Component child, std::function show) { class Impl : public ComponentBase { public: @@ -40,7 +45,7 @@ Component Maybe(Component child, std::function show) { /// @brief Decorate a component. It is shown only when the |show| function /// returns true. -/// @param show a function returning whether the decoratorated component should +/// @param show a function returning whether the decorated component should /// be shown. /// @ingroup component /// diff --git a/src/ftxui/component/screen_interactive.cpp b/src/ftxui/component/screen_interactive.cpp index f10a37c..24869a0 100644 --- a/src/ftxui/component/screen_interactive.cpp +++ b/src/ftxui/component/screen_interactive.cpp @@ -402,6 +402,9 @@ void ScreenInteractive::TrackMouse(bool enable) { track_mouse_ = enable; } +/// @brief Add a task to the main loop. +/// It will be executed later, after every other scheduled tasks. +/// @ingroup component void ScreenInteractive::Post(Task task) { // Task/Events sent toward inactive screen or screen waiting to become // inactive are dropped. @@ -412,10 +415,15 @@ void ScreenInteractive::Post(Task task) { task_sender_->Send(std::move(task)); } +/// @brief Add an event to the main loop. +/// It will be executed later, after every other scheduled events. +/// @ingroup component void ScreenInteractive::PostEvent(Event event) { Post(event); } +/// @brief Add a task to draw the screen one more time, until all the animations +/// are done. void ScreenInteractive::RequestAnimationFrame() { if (animation_requested_) { return; @@ -428,6 +436,10 @@ void ScreenInteractive::RequestAnimationFrame() { } } +/// @brief Try to get the unique lock about behing able to capture the mouse. +/// @return A unique lock if the mouse is not already captured, otherwise a +/// null. +/// @ingroup component CapturedMouse ScreenInteractive::CaptureMouse() { if (mouse_captured) { return nullptr; @@ -437,15 +449,21 @@ CapturedMouse ScreenInteractive::CaptureMouse() { [this] { mouse_captured = false; }); } +/// @brief Execute the main loop. +/// @param component The component to draw. +/// @ingroup component void ScreenInteractive::Loop(Component component) { // NOLINT class Loop loop(this, std::move(component)); loop.Run(); } +/// @brief Return whether the main loop has been quit. +/// @ingroup component bool ScreenInteractive::HasQuitted() { return task_receiver_->HasQuitted(); } +// private void ScreenInteractive::PreMain() { // Suspend previously active screen: if (g_active_screen) { @@ -467,6 +485,7 @@ void ScreenInteractive::PreMain() { previous_animation_time_ = animation::Clock::now(); } +// private void ScreenInteractive::PostMain() { // Put cursor position at the end of the drawing. ResetCursorPosition(); @@ -505,11 +524,13 @@ Closure ScreenInteractive::WithRestoredIO(Closure fn) { // NOLINT }; } +/// @brief Return the currently active screen, or null if none. // static ScreenInteractive* ScreenInteractive::Active() { return g_active_screen; } +// private void ScreenInteractive::Install() { frame_valid_ = false; @@ -622,6 +643,7 @@ void ScreenInteractive::Install() { std::thread(&AnimationListener, &quit_, task_receiver_->MakeSender()); } +// private void ScreenInteractive::Uninstall() { ExitNow(); event_listener_.join(); @@ -629,6 +651,7 @@ void ScreenInteractive::Uninstall() { OnExit(); } +// private // NOLINTNEXTLINE void ScreenInteractive::RunOnceBlocking(Component component) { ExecuteSignalHandlers(); @@ -639,6 +662,7 @@ void ScreenInteractive::RunOnceBlocking(Component component) { RunOnce(component); } +// private void ScreenInteractive::RunOnce(Component component) { Task task; while (task_receiver_->ReceiveNonBlocking(&task)) { @@ -648,6 +672,7 @@ void ScreenInteractive::RunOnce(Component component) { Draw(std::move(component)); } +// private void ScreenInteractive::HandleTask(Component component, Task& task) { // clang-format off std::visit([&](auto&& arg) { @@ -699,6 +724,7 @@ void ScreenInteractive::HandleTask(Component component, Task& task) { // clang-format on } +// private // NOLINTNEXTLINE void ScreenInteractive::Draw(Component component) { if (frame_valid_) { @@ -793,24 +819,31 @@ void ScreenInteractive::Draw(Component component) { frame_valid_ = true; } +// private void ScreenInteractive::ResetCursorPosition() { std::cout << reset_cursor_position; reset_cursor_position = ""; } +/// @brief Return a function to exit the main loop. +/// @ingroup component Closure ScreenInteractive::ExitLoopClosure() { return [this] { Exit(); }; } +/// @brief Exit the main loop. +/// @ingroup component void ScreenInteractive::Exit() { Post([this] { ExitNow(); }); } +// private: void ScreenInteractive::ExitNow() { quit_ = true; task_sender_.reset(); } +// private: void ScreenInteractive::Signal(int signal) { if (signal == SIGABRT) { OnExit(); diff --git a/src/ftxui/component/slider.cpp b/src/ftxui/component/slider.cpp index 5b63bf7..d30b87b 100644 --- a/src/ftxui/component/slider.cpp +++ b/src/ftxui/component/slider.cpp @@ -34,7 +34,6 @@ Decorator flexDirection(Direction direction) { } return xflex; // NOT_REACHED() } -} // namespace template class SliderBase : public ComponentBase { @@ -256,6 +255,7 @@ class SliderWithLabel : public ComponentBase { Box box_; bool mouse_hover_ = false; }; +} // namespace /// @brief An horizontal slider. /// @param label The name of the slider. diff --git a/src/ftxui/dom/blink.cpp b/src/ftxui/dom/blink.cpp index a71c305..9a594a4 100644 --- a/src/ftxui/dom/blink.cpp +++ b/src/ftxui/dom/blink.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { class Blink : public NodeDecorator { public: using NodeDecorator::NodeDecorator; @@ -25,6 +26,7 @@ class Blink : public NodeDecorator { } } }; +} // namespace /// @brief The text drawn alternates in between visible and hidden. /// @ingroup dom diff --git a/src/ftxui/dom/bold.cpp b/src/ftxui/dom/bold.cpp index 02dde65..eee1092 100644 --- a/src/ftxui/dom/bold.cpp +++ b/src/ftxui/dom/bold.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { class Bold : public NodeDecorator { public: using NodeDecorator::NodeDecorator; @@ -25,6 +26,7 @@ class Bold : public NodeDecorator { Node::Render(screen); } }; +} // namespace /// @brief Use a bold font, for elements with more emphasis. /// @ingroup dom diff --git a/src/ftxui/dom/border.cpp b/src/ftxui/dom/border.cpp index 9cda0f0..9767f81 100644 --- a/src/ftxui/dom/border.cpp +++ b/src/ftxui/dom/border.cpp @@ -18,6 +18,7 @@ namespace ftxui { +namespace { using Charset = std::array; // NOLINT using Charsets = std::array; // NOLINT // NOLINTNEXTLINE @@ -190,6 +191,7 @@ class BorderPixel : public Node { } } }; +} // namespace /// @brief Draw a border around the element. /// @ingroup dom diff --git a/src/ftxui/dom/clear_under.cpp b/src/ftxui/dom/clear_under.cpp index 8ad2781..a18510d 100644 --- a/src/ftxui/dom/clear_under.cpp +++ b/src/ftxui/dom/clear_under.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { using ftxui::Screen; class ClearUnder : public NodeDecorator { @@ -27,6 +28,7 @@ class ClearUnder : public NodeDecorator { Node::Render(screen); } }; +} // namespace /// @brief Before drawing |child|, clear the pixels below. This is useful in // combinaison with dbox. diff --git a/src/ftxui/dom/color.cpp b/src/ftxui/dom/color.cpp index 18d4c66..859b8a1 100644 --- a/src/ftxui/dom/color.cpp +++ b/src/ftxui/dom/color.cpp @@ -12,6 +12,7 @@ namespace ftxui { + namespace { class BgColor : public NodeDecorator { public: BgColor(Element child, Color color) @@ -45,6 +46,7 @@ class FgColor : public NodeDecorator { Color color_; }; +} // namespace /// @brief Set the foreground color of an element. /// @param color The color of the output element. diff --git a/src/ftxui/dom/dbox.cpp b/src/ftxui/dom/dbox.cpp index d5e414c..af87d20 100644 --- a/src/ftxui/dom/dbox.cpp +++ b/src/ftxui/dom/dbox.cpp @@ -13,6 +13,7 @@ namespace ftxui { + namespace { class DBox : public Node { public: explicit DBox(Elements children) : Node(std::move(children)) {} @@ -47,6 +48,7 @@ class DBox : public Node { } } }; +} // namespace /// @brief Stack several element on top of each other. /// @param children_ The input element. diff --git a/src/ftxui/dom/dim.cpp b/src/ftxui/dom/dim.cpp index f4384a9..7628b07 100644 --- a/src/ftxui/dom/dim.cpp +++ b/src/ftxui/dom/dim.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { class Dim : public NodeDecorator { public: using NodeDecorator::NodeDecorator; @@ -25,6 +26,7 @@ class Dim : public NodeDecorator { } } }; +} // namespace /// @brief Use a light font, for elements with less emphasis. /// @ingroup dom diff --git a/src/ftxui/dom/flex.cpp b/src/ftxui/dom/flex.cpp index 2576761..42a646d 100644 --- a/src/ftxui/dom/flex.cpp +++ b/src/ftxui/dom/flex.cpp @@ -66,8 +66,6 @@ void function_not_flex(Requirement& r) { r.flex_shrink_y = 0; } -} // namespace - class Flex : public Node { public: explicit Flex(FlexFunction f) : f_(f) {} @@ -92,6 +90,8 @@ class Flex : public Node { FlexFunction f_; }; +} // namespace + /// @brief An element that will take expand proportionnally to the space left in /// a container. /// @ingroup dom diff --git a/src/ftxui/dom/flexbox_config.cpp b/src/ftxui/dom/flexbox_config.cpp index c70343b..fbe7822 100644 --- a/src/ftxui/dom/flexbox_config.cpp +++ b/src/ftxui/dom/flexbox_config.cpp @@ -5,31 +5,43 @@ namespace ftxui { +/// @brief Set the flexbox direction. +/// @ingroup dom FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::Direction d) { this->direction = d; return *this; } +/// @brief Set the flexbox wrap. +/// @ingroup dom FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::Wrap w) { this->wrap = w; return *this; } +/// @brief Set the flexbox justify content. +/// @ingroup dom FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::JustifyContent j) { this->justify_content = j; return *this; } +/// @brief Set the flexbox align items. +/// @ingroup dom FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::AlignItems a) { this->align_items = a; return *this; } +/// @brief Set the flexbox align content. +/// @ingroup dom FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::AlignContent a) { this->align_content = a; return *this; } +/// @brief Set the flexbox flex direction. +/// @ingroup dom FlexboxConfig& FlexboxConfig::SetGap(int x, int y) { this->gap_x = x; this->gap_y = y; diff --git a/src/ftxui/dom/flexbox_helper.cpp b/src/ftxui/dom/flexbox_helper.cpp index 96655fe..d75824e 100644 --- a/src/ftxui/dom/flexbox_helper.cpp +++ b/src/ftxui/dom/flexbox_helper.cpp @@ -288,9 +288,6 @@ void JustifyContent(Global& g, std::vector lines) { } } } -} // namespace - -namespace { void Compute1(Global& global); void Compute2(Global& global); diff --git a/src/ftxui/dom/frame.cpp b/src/ftxui/dom/frame.cpp index ee5400e..fe97440 100644 --- a/src/ftxui/dom/frame.cpp +++ b/src/ftxui/dom/frame.cpp @@ -15,8 +15,7 @@ namespace ftxui { -// ----------------------------------------------------------------------------- - +namespace { class Select : public Node { public: explicit Select(Elements children) : Node(std::move(children)) {} @@ -38,11 +37,6 @@ class Select : public Node { } }; -Element select(Element child) { - return std::make_shared(unpack(std::move(child))); +} + +/// @brief Set the `child` to be the one in focus globally. +/// @param child The element to be focused. +/// @ingroup dom +Element focus(Element child) { + return std::make_shared(unpack(std::move(child))); +} + +/// @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. +/// @see frame +/// @see xframe +/// @see yframe +Element frame(Element child) { + return std::make_shared(unpack(std::move(child)), true, true); +} + +/// @brief Same as `frame`, but only on the x-axis. +/// @see frame +/// @see xframe +/// @see yframe +Element xframe(Element child) { + return std::make_shared(unpack(std::move(child)), true, false); +} + +/// @brief Same as `frame`, but only on the y-axis. +/// @see frame +/// @see xframe +/// @see yframe +Element yframe(Element child) { + return std::make_shared(unpack(std::move(child)), false, true); +} + +/// @brief Same as `focus`, but set the cursor shape to be a still block. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorBlock(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::Block); } + +/// @brief Same as `focus`, but set the cursor shape to be a blinking block. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorBlockBlinking(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::BlockBlinking); } + +/// @brief Same as `focus`, but set the cursor shape to be a still block. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorBar(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::Bar); } + +/// @brief Same as `focus`, but set the cursor shape to be a blinking bar. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorBarBlinking(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::BarBlinking); } + +/// @brief Same as `focus`, but set the cursor shape to be a still underline. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorUnderline(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::Underline); } + +/// @brief Same as `focus`, but set the cursor shape to be a blinking underline. +/// @see focus +/// @see focusCursorBlock +/// @see focusCursorBlockBlinking +/// @see focusCursorBar +/// @see focusCursorBarBlinking +/// @see focusCursorUnderline +/// @see focusCursorUnderlineBlinking +/// @ingroup dom Element focusCursorUnderlineBlinking(Element child) { return std::make_shared(unpack(std::move(child)), Screen::Cursor::UnderlineBlinking); diff --git a/src/ftxui/dom/gauge.cpp b/src/ftxui/dom/gauge.cpp index c210f79..d6436aa 100644 --- a/src/ftxui/dom/gauge.cpp +++ b/src/ftxui/dom/gauge.cpp @@ -13,6 +13,7 @@ namespace ftxui { +namespace { // NOLINTNEXTLINE static const std::string charset_horizontal[11] = { #if defined(FTXUI_MICROSOFT_TERMINAL_FALLBACK) @@ -158,6 +159,8 @@ class Gauge : public Node { Direction direction_; }; +} // namespace ftxui + /// @brief Draw a high definition progress bar progressing in specified /// direction. /// @param progress The proportion of the area to be filled. Belong to [0,1]. diff --git a/src/ftxui/dom/graph.cpp b/src/ftxui/dom/graph.cpp index ca32088..927558b 100644 --- a/src/ftxui/dom/graph.cpp +++ b/src/ftxui/dom/graph.cpp @@ -15,6 +15,7 @@ namespace ftxui { +namespace { // NOLINTNEXTLINE static std::string charset[] = #if defined(FTXUI_MICROSOFT_TERMINAL_FALLBACK) @@ -63,6 +64,8 @@ class Graph : public Node { GraphFunction graph_function_; }; +} // namespace + /// @brief Draw a graph using a GraphFunction. /// @param graph_function the function to be called to get the data. Element graph(GraphFunction graph_function) { diff --git a/src/ftxui/dom/gridbox.cpp b/src/ftxui/dom/gridbox.cpp index 1137f5a..37e88bf 100644 --- a/src/ftxui/dom/gridbox.cpp +++ b/src/ftxui/dom/gridbox.cpp @@ -31,7 +31,6 @@ int Integrate(std::vector& elements) { } return accu; } -} // namespace class GridBox : public Node { public: @@ -153,7 +152,8 @@ class GridBox : public Node { int y_size = 0; std::vector lines_; }; - +} // namespace + // /// @brief A container displaying a grid of elements. /// @param lines A list of lines, each line being a list of elements. /// @return The container. diff --git a/src/ftxui/dom/hbox.cpp b/src/ftxui/dom/hbox.cpp index 45e6010..2053e84 100644 --- a/src/ftxui/dom/hbox.cpp +++ b/src/ftxui/dom/hbox.cpp @@ -15,6 +15,7 @@ namespace ftxui { +namespace { class HBox : public Node { public: explicit HBox(Elements children) : Node(std::move(children)) {} @@ -65,6 +66,8 @@ class HBox : public Node { } }; +} // namespace + /// @brief A container displaying elements horizontally one by one. /// @param children The elements in the container /// @return The container. diff --git a/src/ftxui/dom/hyperlink.cpp b/src/ftxui/dom/hyperlink.cpp index 5c493c4..f14502d 100644 --- a/src/ftxui/dom/hyperlink.cpp +++ b/src/ftxui/dom/hyperlink.cpp @@ -13,6 +13,7 @@ namespace ftxui { +namespace { class Hyperlink : public NodeDecorator { public: Hyperlink(Element child, std::string link) @@ -30,6 +31,7 @@ class Hyperlink : public NodeDecorator { std::string link_; }; +} // namespace /// @brief Make the rendered area clickable using a web browser. /// The link will be opened when the user click on it. diff --git a/src/ftxui/dom/inverted.cpp b/src/ftxui/dom/inverted.cpp index 9769216..c693299 100644 --- a/src/ftxui/dom/inverted.cpp +++ b/src/ftxui/dom/inverted.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { class Inverted : public NodeDecorator { public: using NodeDecorator::NodeDecorator; @@ -25,6 +26,7 @@ class Inverted : public NodeDecorator { } } }; +} // namespace /// @brief Add a filter that will invert the foreground and the background /// colors. diff --git a/src/ftxui/dom/reflect.cpp b/src/ftxui/dom/reflect.cpp index 6bf6187..b3eccc9 100644 --- a/src/ftxui/dom/reflect.cpp +++ b/src/ftxui/dom/reflect.cpp @@ -12,6 +12,7 @@ #include "ftxui/screen/screen.hpp" // for Screen namespace ftxui { +namespace { // Helper class. class Reflect : public Node { @@ -38,6 +39,7 @@ class Reflect : public Node { private: Box& reflected_box_; }; +} // namespace Decorator reflect(Box& box) { return [&](Element child) -> Element { diff --git a/src/ftxui/dom/separator.cpp b/src/ftxui/dom/separator.cpp index 8a556e8..dc902af 100644 --- a/src/ftxui/dom/separator.cpp +++ b/src/ftxui/dom/separator.cpp @@ -28,8 +28,6 @@ const Charsets charsets = { Charset{" ", " "}, // EMPTY }; -} // namespace - class Separator : public Node { public: explicit Separator(std::string value) : value_(std::move(value)) {} @@ -96,6 +94,7 @@ class SeparatorWithPixel : public SeparatorAuto { private: Pixel pixel_; }; +} // namespace /// @brief Draw a vertical or horizontal separation in between two other /// elements. diff --git a/src/ftxui/dom/size.cpp b/src/ftxui/dom/size.cpp index 388649e..91fa702 100644 --- a/src/ftxui/dom/size.cpp +++ b/src/ftxui/dom/size.cpp @@ -13,6 +13,7 @@ namespace ftxui { +namespace { class Size : public Node { public: Size(Element child, WidthOrHeight direction, Constraint constraint, int value) @@ -78,6 +79,7 @@ class Size : public Node { Constraint constraint_; int value_; }; +} // namespace /// @brief Apply a constraint on the size of an element. /// @param direction Whether the WIDTH of the HEIGHT of the element must be diff --git a/src/ftxui/dom/table.cpp b/src/ftxui/dom/table.cpp index 38369c1..4927ea9 100644 --- a/src/ftxui/dom/table.cpp +++ b/src/ftxui/dom/table.cpp @@ -41,10 +41,16 @@ void Order(int& a, int& b) { } // namespace +/// @brief Create an empty table. +/// @ingroup dom Table::Table() { Initialize({}); } + +/// @brief Create a table from a vector of vector of string. +/// @param input The input data. +/// @ingroup dom Table::Table(std::vector> input) { std::vector> output; output.reserve(input.size()); @@ -59,10 +65,14 @@ Table::Table(std::vector> input) { Initialize(std::move(output)); } +/// @brief Create a table from a vector of vector of Element +/// @param input The input elements. +/// @ingroup dom Table::Table(std::vector> input) { Initialize(std::move(input)); } +// private void Table::Initialize(std::vector> input) { input_dim_y_ = input.size(); input_dim_x_ = 0; @@ -109,26 +119,56 @@ void Table::Initialize(std::vector> input) { } } +/// @brief Select a row of the table. +/// @param index The index of the row to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectRow(int index) { return SelectRectangle(0, -1, index, index); } +/// @brief Select a range of rows of the table. +/// @param row_min The first row to select. +/// @param row_max The last row to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectRows(int row_min, int row_max) { return SelectRectangle(0, -1, row_min, row_max); } +/// @brief Select a column of the table. +/// @param index The index of the column to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectColumn(int index) { return SelectRectangle(index, index, 0, -1); } +/// @brief Select a range of columns of the table. +/// @param column_min The first column to select. +/// @param column_max The last column to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectColumns(int column_min, int column_max) { return SelectRectangle(column_min, column_max, 0, -1); } +/// @brief Select a cell of the table. +/// @param column The column of the cell to select. +/// @param row The row of the cell to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectCell(int column, int row) { return SelectRectangle(column, column, row, row); } +/// @brief Select a rectangle of the table. +/// @param column_min The first column to select. +/// @param column_max The last column to select. +/// @param row_min The first row to select. +/// @param row_max The last row to select. +/// @note You can use negative index to select from the end. +/// @ingroup dom TableSelection Table::SelectRectangle(int column_min, int column_max, int row_min, @@ -149,6 +189,8 @@ TableSelection Table::SelectRectangle(int column_min, return output; } +/// @brief Select all the table. +/// @ingroup dom TableSelection Table::SelectAll() { TableSelection output; // NOLINT output.table_ = this; @@ -159,6 +201,9 @@ TableSelection Table::SelectAll() { return output; } +/// @brief Render the table. +/// @return The rendered table. This is an element you can draw. +/// @ingroup dom Element Table::Render() { for (int y = 0; y < dim_y_; ++y) { for (int x = 0; x < dim_x_; ++x) { @@ -185,6 +230,10 @@ Element Table::Render() { return gridbox(std::move(elements_)); } +/// @brief Apply the `decorator` to the selection. +/// This decorate both the cells, the lines and the corners. +/// @param decorator The decorator to apply. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::Decorate(Decorator decorator) { for (int y = y_min_; y <= y_max_; ++y) { @@ -195,6 +244,10 @@ void TableSelection::Decorate(Decorator decorator) { } } +/// @brief Apply the `decorator` to the selection. +/// @param decorator The decorator to apply. +/// This decorate only the cells. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::DecorateCells(Decorator decorator) { for (int y = y_min_; y <= y_max_; ++y) { @@ -207,6 +260,12 @@ void TableSelection::DecorateCells(Decorator decorator) { } } +/// @brief Apply the `decorator` to the selection. +/// This decorate only the lines modulo `modulo` with a shift of `shift`. +/// @param decorator The decorator to apply. +/// @param modulo The modulo of the lines to decorate. +/// @param shift The shift of the lines to decorate. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::DecorateAlternateColumn(Decorator decorator, int modulo, @@ -221,6 +280,12 @@ void TableSelection::DecorateAlternateColumn(Decorator decorator, } } +/// @brief Apply the `decorator` to the selection. +/// This decorate only the lines modulo `modulo` with a shift of `shift`. +/// @param decorator The decorator to apply. +/// @param modulo The modulo of the lines to decorate. +/// @param shift The shift of the lines to decorate. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::DecorateAlternateRow(Decorator decorator, int modulo, @@ -235,6 +300,12 @@ void TableSelection::DecorateAlternateRow(Decorator decorator, } } +/// @brief Apply the `decorator` to the selection. +/// This decorate only the corners modulo `modulo` with a shift of `shift`. +/// @param decorator The decorator to apply. +/// @param modulo The modulo of the corners to decorate. +/// @param shift The shift of the corners to decorate. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::DecorateCellsAlternateColumn(Decorator decorator, int modulo, @@ -249,6 +320,12 @@ void TableSelection::DecorateCellsAlternateColumn(Decorator decorator, } } +/// @brief Apply the `decorator` to the selection. +/// This decorate only the corners modulo `modulo` with a shift of `shift`. +/// @param decorator The decorator to apply. +/// @param modulo The modulo of the corners to decorate. +/// @param shift The shift of the corners to decorate. +/// @ingroup dom // NOLINTNEXTLINE void TableSelection::DecorateCellsAlternateRow(Decorator decorator, int modulo, @@ -263,6 +340,9 @@ void TableSelection::DecorateCellsAlternateRow(Decorator decorator, } } +/// @brief Apply a `border` around the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::Border(BorderStyle border) { BorderLeft(border); BorderRight(border); @@ -279,6 +359,9 @@ void TableSelection::Border(BorderStyle border) { table_->elements_[y_max_][x_max_] = text(charset[border][3]) | automerge; } +/// @brief Draw some separator lines in the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::Separator(BorderStyle border) { for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) { for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) { @@ -292,6 +375,9 @@ void TableSelection::Separator(BorderStyle border) { } } +/// @brief Draw some vertical separator lines in the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::SeparatorVertical(BorderStyle border) { for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) { for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) { @@ -303,6 +389,9 @@ void TableSelection::SeparatorVertical(BorderStyle border) { } } +/// @brief Draw some horizontal separator lines in the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::SeparatorHorizontal(BorderStyle border) { for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) { for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) { @@ -314,6 +403,9 @@ void TableSelection::SeparatorHorizontal(BorderStyle border) { } } +/// @brief Draw some separator lines to the left side of the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::BorderLeft(BorderStyle border) { for (int y = y_min_; y <= y_max_; y++) { table_->elements_[y][x_min_] = @@ -321,6 +413,9 @@ void TableSelection::BorderLeft(BorderStyle border) { } } +/// @brief Draw some separator lines to the right side of the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::BorderRight(BorderStyle border) { for (int y = y_min_; y <= y_max_; y++) { table_->elements_[y][x_max_] = @@ -328,6 +423,9 @@ void TableSelection::BorderRight(BorderStyle border) { } } +/// @brief Draw some separator lines to the top side of the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::BorderTop(BorderStyle border) { for (int x = x_min_; x <= x_max_; x++) { table_->elements_[y_min_][x] = @@ -335,6 +433,9 @@ void TableSelection::BorderTop(BorderStyle border) { } } +/// @brief Draw some separator lines to the bottom side of the selection. +/// @param border The border style to apply. +/// @ingroup dom void TableSelection::BorderBottom(BorderStyle border) { for (int x = x_min_; x <= x_max_; x++) { table_->elements_[y_max_][x] = diff --git a/src/ftxui/dom/text.cpp b/src/ftxui/dom/text.cpp index 36b31a2..e8117b5 100644 --- a/src/ftxui/dom/text.cpp +++ b/src/ftxui/dom/text.cpp @@ -17,6 +17,7 @@ namespace ftxui { +namespace { using ftxui::Screen; class Text : public Node { @@ -80,6 +81,8 @@ class VText : public Node { int width_ = 1; }; +} // namespace + /// @brief Display a piece of UTF8 encoded unicode text. /// @ingroup dom /// @see ftxui::to_wstring diff --git a/src/ftxui/dom/underlined.cpp b/src/ftxui/dom/underlined.cpp index f1958a6..9d703bc 100644 --- a/src/ftxui/dom/underlined.cpp +++ b/src/ftxui/dom/underlined.cpp @@ -12,6 +12,7 @@ namespace ftxui { +namespace { class Underlined : public NodeDecorator { public: using NodeDecorator::NodeDecorator; @@ -25,6 +26,7 @@ class Underlined : public NodeDecorator { } } }; +} // namespace /// @brief Make the underlined element to be underlined. /// @ingroup dom diff --git a/src/ftxui/dom/vbox.cpp b/src/ftxui/dom/vbox.cpp index cab9d40..28d885d 100644 --- a/src/ftxui/dom/vbox.cpp +++ b/src/ftxui/dom/vbox.cpp @@ -15,6 +15,7 @@ namespace ftxui { +namespace { class VBox : public Node { public: explicit VBox(Elements children) : Node(std::move(children)) {} @@ -64,6 +65,7 @@ class VBox : public Node { } } }; +} // namespace /// @brief A container displaying elements vertically one by one. /// @param children The elements in the container diff --git a/src/ftxui/screen/terminal.cpp b/src/ftxui/screen/terminal.cpp index 19c93b2..8878a1f 100644 --- a/src/ftxui/screen/terminal.cpp +++ b/src/ftxui/screen/terminal.cpp @@ -87,6 +87,10 @@ Terminal::Color ComputeColorSupport() { } // namespace namespace Terminal { + +/// @brief Get the terminal size. +/// @return The terminal size. +/// @ingroup screen Dimensions Size() { #if defined(__EMSCRIPTEN__) // This dimension was chosen arbitrarily to be able to display: @@ -121,6 +125,8 @@ void SetFallbackSize(const Dimensions& fallbackSize) { FallbackSize() = fallbackSize; } +/// @brief Get the color support of the terminal. +/// @ingroup screen Color ColorSupport() { if (!g_cached) { g_cached = true; @@ -129,6 +135,8 @@ Color ColorSupport() { return g_cached_supported_color; } +/// @brief Override terminal color support in case auto-detection fails +/// @ingroup dom void SetColorSupport(Color color) { g_cached = true; g_cached_supported_color = color;