// Copyright 2021 Arthur Sonzogni. All rights reserved.
// Use of this source code is governed by the MIT license that can be found in
// the LICENSE file.
#ifndef FTXUI_COMPONENT_HPP
#define FTXUI_COMPONENT_HPP
 
#include <functional>  // for function
#include <memory>      // for make_shared, shared_ptr
#include <utility>     // for forward
 
#include <ftxui/util/warn_windows_macro.hpp>
#include "ftxui/component/component_base.hpp"  // for Component, Components
#include "ftxui/component/component_options.hpp"  // for ButtonOption, CheckboxOption, MenuOption
#include "ftxui/dom/elements.hpp"  // for Element
#include "ftxui/util/export.hpp"
#include "ftxui/util/ref.hpp"  // for ConstRef, Ref, ConstStringRef, ConstStringListRef, StringRef
 
namespace ftxui {
struct ButtonOption;
struct CheckboxOption;
struct Event;
struct InputOption;
struct MenuOption;
struct RadioboxOption;
struct MenuEntryOption;
 
template <class T, class... Args>
std::shared_ptr<T> Make(Args&&... args) {
  return std::make_shared<T>(std::forward<Args>(args)...);
}
 
// 管線運算子，用來裝飾元件。
using ComponentDecorator = std::function<Component(Component)>;
using ElementDecorator = std::function<Element(Element)>;
FTXUI_EXPORT(COMPONENT)
Component operator|(Component component, ComponentDecorator decorator);
FTXUI_EXPORT(COMPONENT)
Component operator|(Component component, ElementDecorator decorator);
FTXUI_EXPORT(COMPONENT)
Component& operator|=(Component& component, ComponentDecorator decorator);
FTXUI_EXPORT(COMPONENT)
Component& operator|=(Component& component, ElementDecorator decorator);
 
namespace Container {
FTXUI_EXPORT(COMPONENT) Component Vertical(Components children);
FTXUI_EXPORT(COMPONENT) Component Vertical(Components children, int* selector);
FTXUI_EXPORT(COMPONENT) Component Horizontal(Components children);
FTXUI_EXPORT(COMPONENT)
Component Horizontal(Components children, int* selector);
FTXUI_EXPORT(COMPONENT) Component Tab(Components children, int* selector);
FTXUI_EXPORT(COMPONENT) Component Stacked(Components children);
}  // namespace Container
 
FTXUI_EXPORT(COMPONENT) Component Button(ButtonOption options);
FTXUI_EXPORT(COMPONENT)
Component Button(ConstStringRef label,
                 std::function<void()> on_click,
                 ButtonOption options = ButtonOption::Simple());
 
FTXUI_EXPORT(COMPONENT) Component Checkbox(CheckboxOption options);
FTXUI_EXPORT(COMPONENT)
Component Checkbox(ConstStringRef label,
                   bool* checked,
                   CheckboxOption options = CheckboxOption::Simple());
 
FTXUI_EXPORT(COMPONENT) Component Input(InputOption options = {});
FTXUI_EXPORT(COMPONENT)
Component Input(StringRef content, InputOption options = {});
FTXUI_EXPORT(COMPONENT)
Component Input(StringRef content,
                StringRef placeholder,
                InputOption options = {});
 
FTXUI_EXPORT(COMPONENT) Component Menu(MenuOption options);
FTXUI_EXPORT(COMPONENT)
Component Menu(ConstStringListRef entries,
               int* selected_,
               MenuOption options = MenuOption::Vertical());
FTXUI_EXPORT(COMPONENT) Component MenuEntry(MenuEntryOption options);
FTXUI_EXPORT(COMPONENT)
Component MenuEntry(ConstStringRef label, MenuEntryOption options = {});
 
FTXUI_EXPORT(COMPONENT) Component Radiobox(RadioboxOption options);
FTXUI_EXPORT(COMPONENT)
Component Radiobox(ConstStringListRef entries,
                   int* selected_,
                   RadioboxOption options = {});
 
FTXUI_EXPORT(COMPONENT)
Component Dropdown(ConstStringListRef entries, int* selected);
FTXUI_EXPORT(COMPONENT) Component Dropdown(DropdownOption options);
 
FTXUI_EXPORT(COMPONENT)
Component Toggle(ConstStringListRef entries, int* selected);
 
// 通用的滑桿建構子：
template <typename T>
Component Slider(SliderOption<T> options);
 
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<int8_t>);
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<int16_t>);
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<int32_t>);
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<int64_t>);
 
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<uint8_t>);
extern template FTXUI_EXPORT(COMPONENT) Component
    Slider(SliderOption<uint16_t>);
extern template FTXUI_EXPORT(COMPONENT) Component
    Slider(SliderOption<uint32_t>);
extern template FTXUI_EXPORT(COMPONENT) Component
    Slider(SliderOption<uint64_t>);
 
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<float>);
extern template FTXUI_EXPORT(COMPONENT) Component Slider(SliderOption<double>);
 
// 不需要 `SliderOption` 建構子的簡寫形式：
FTXUI_EXPORT(COMPONENT)
Component Slider(ConstStringRef label,
                 Ref<int> value,
                 ConstRef<int> min = 0,
                 ConstRef<int> max = 100,
                 ConstRef<int> increment = 5);
FTXUI_EXPORT(COMPONENT)
Component Slider(ConstStringRef label,
                 Ref<float> value,
                 ConstRef<float> min = 0.f,
                 ConstRef<float> max = 100.f,
                 ConstRef<float> increment = 5.f);
FTXUI_EXPORT(COMPONENT)
Component Slider(ConstStringRef label,
                 Ref<long> value,
                 ConstRef<long> min = 0L,
                 ConstRef<long> max = 100L,
                 ConstRef<long> increment = 5L);
 
FTXUI_EXPORT(COMPONENT)
Component ResizableSplit(ResizableSplitOption options);
FTXUI_EXPORT(COMPONENT)
Component ResizableSplitLeft(Component main, Component back, int* main_size);
FTXUI_EXPORT(COMPONENT)
Component ResizableSplitRight(Component main, Component back, int* main_size);
FTXUI_EXPORT(COMPONENT)
Component ResizableSplitTop(Component main, Component back, int* main_size);
FTXUI_EXPORT(COMPONENT)
Component ResizableSplitBottom(Component main, Component back, int* main_size);
 
FTXUI_EXPORT(COMPONENT)
Component Renderer(Component child, std::function<Element()>);
FTXUI_EXPORT(COMPONENT) Component Renderer(std::function<Element()>);
FTXUI_EXPORT(COMPONENT)
Component Renderer(std::function<Element(bool /* 已聚焦 */)>);
FTXUI_EXPORT(COMPONENT) ComponentDecorator Renderer(ElementDecorator);
 
FTXUI_EXPORT(COMPONENT)
Component CatchEvent(Component child, std::function<bool(Event)>);
FTXUI_EXPORT(COMPONENT)
ComponentDecorator CatchEvent(std::function<bool(Event)> on_event);
 
FTXUI_EXPORT(COMPONENT) Component Maybe(Component, const bool* show);
FTXUI_EXPORT(COMPONENT) Component Maybe(Component, std::function<bool()>);
FTXUI_EXPORT(COMPONENT) ComponentDecorator Maybe(const bool* show);
FTXUI_EXPORT(COMPONENT) ComponentDecorator Maybe(std::function<bool()>);
 
FTXUI_EXPORT(COMPONENT)
Component Modal(Component main, Component modal, const bool* show_modal);
FTXUI_EXPORT(COMPONENT)
ComponentDecorator Modal(Component modal, const bool* show_modal);
 
FTXUI_EXPORT(COMPONENT)
Component Collapsible(ConstStringRef label,
                      Component child,
                      Ref<bool> show = false);
 
FTXUI_EXPORT(COMPONENT)
Component Hoverable(Component component, bool* hover);
FTXUI_EXPORT(COMPONENT)
Component Hoverable(Component component,
                    std::function<void()> on_enter,
                    std::function<void()> on_leave);
FTXUI_EXPORT(COMPONENT)
Component Hoverable(Component component,  //
                    std::function<void(bool)> on_change);
FTXUI_EXPORT(COMPONENT) ComponentDecorator Hoverable(bool* hover);
FTXUI_EXPORT(COMPONENT)
ComponentDecorator Hoverable(std::function<void()> on_enter,
                             std::function<void()> on_leave);
FTXUI_EXPORT(COMPONENT)
ComponentDecorator Hoverable(std::function<void(bool)> on_change);
 
FTXUI_EXPORT(COMPONENT) Component Window(WindowOptions option);
 
}  // namespace ftxui
 
#endif /* end of include guard: FTXUI_COMPONENT_HPP */

輸入

範例：

由 ftxui::Input() 從 "ftxui/component/component.hpp" 生成。

篩選輸入

可以使用 ftxui::CatchEvent 過濾輸入元件接收到的字元。

std::string phone_number;
Component input = Input(&phone_number, "phone number");
 
// Filter out non-digit characters.
input |= CatchEvent([&](Event event) {
  return event.is_character() && !std::isdigit(event.character()[0]);
});
 
// Filter out characters past the 10th one.
input |= CatchEvent([&](Event event) {
  return event.is_character() && phone_number.size() >= 10;
});

選單

定義一個選單物件。它包含一組項目清單，其中一個項目會被選中。

範例:

由 ftxui::Dropdown() 從 "ftxui/component/component.hpp" 生成。

表示一個滑塊物件，它由一個帶有分箱中間間隔的範圍組成。它可以使用 ftxui::Slider() 創建。

一種特殊的選單。項目會以水平方式顯示。

範例:

Renderer

CheckBox

此元件定義一個核取方塊。它是一個可以開/關的單一項目。

範例：

由以下產生：ftxui::Checkbox()，來自 "ftxui/component/component.hpp"

RadioBox

一個單選按鈕元件。這是一份項目清單，其中可以有一個被開啟。

範例：

由以下產生：ftxui::Radiobox()，來自 "ftxui/component/component.hpp"

Dropdown

下拉式選單是一種元件，展開時會顯示一份項目清單供使用者選擇。

範例：

youtube-video-gif (3)

由以下產生：ftxui::Dropdown()，來自 "ftxui/component/component.hpp"

Slider

表示一個滑桿物件，由一個範圍與分格的中間區間所組成。可以透過 ftxui::Slider() 建立。

範例：

由以下產生：ftxui::Slider()，來自 "ftxui/component/component.hpp"

Renderer

由以下產生：ftxui::Renderer()，來自 ftxui/component/component.hpp。此元件透過使用不同的函式來渲染介面，藉此裝飾另一個元件。

範例：

auto inner = [...]
 
auto renderer = Renderer(inner, [&] {
  return inner->Render() | border
});

ftxui::Renderer 也支援元件裝飾器模式：

auto component = [...]
component = component
  | Renderer([](Element e) { return e | border))
  | Renderer(bold)

作為簡便寫法，你也可以用元素裝飾器來組合元件：

auto component = [...]

component = component | border | bold;

CatchEvent

由 ftxui::CatchEvent() 從 ftxui/component/component.hpp 生成。此元件裝飾其他元件，在底層元件之前捕獲事件。

範例：

auto screen = App::TerminalOutput();
auto renderer = Renderer([] {
  return text("My interface");
});
auto component = CatchEvent(renderer, [&](Event event) {
  if (event == Event::Character('q')) {
    screen.ExitLoopClosure()();
    return true;
  }
  return false;
});
screen.Loop(component);

ftxui::CatchEvent 也可以用作裝飾器：

component = component
  | CatchEvent(handler_1)
  | CatchEvent(handler_2)
  | CatchEvent(handler_3)
  ;

Collapsible

對於使用者可以開啟或關閉其可見性的視覺元素很有用。本質上，這是 ftxui::Checkbox() 和 ftxui::Maybe() 元件的組合。

auto collapsible = Collapsible("Show more", inner_element);

Maybe

由 ftxui::Maybe() 從 ftxui/component/component.hpp 生成。此元件可用於通過布林值或謂詞顯示/隱藏任何其他元件。

使用布林值的範例：

bool show = true;
auto component = Renderer([]{ return "Hello World!"; });
auto maybe_component = Maybe(component, &show)

使用述詞（predicate）的範例：

auto component = Renderer([]{ return "Hello World!"; });

auto maybe_component = Maybe(component, [&] { return time > 10; })

像往常一樣，ftxui::Maybe 也可以用作裝飾器：

component = component
  | Maybe(&a_boolean)
  | Maybe([&] { return time > 10; })
  ;

Container

Horizontal

由 ftxui::Container::Horizontal() 從 "ftxui/component/component.hpp" 生成。它水平顯示元件列表並處理鍵盤/滑鼠導航。

Vertical

由 ftxui::Container::Vertical() 從 "ftxui/component/component.hpp" 生成。它垂直顯示元件列表並處理鍵盤/滑鼠導航。

Tab

由 ftxui::Container::Tab() 從 "ftxui/component/component.hpp" 生成。它接受元件列表並僅顯示其中一個。這對於實現分頁欄很有用。

垂直：

ezgif com-gif-maker (1)

水平：

ezgif com-gif-maker (2)

ResizableSplit

它定義了兩個子元件之間的水平或垂直分隔。分隔的位置是可變的，並且可以使用滑鼠控制。有四種可能的分隔：

ftxui::ResizableSplitLeft()
ftxui::ResizableSplitRight()
ftxui::ResizableSplitTop()
ftxui::ResizableSplitBottom() 從 "ftxui/component/component.hpp"

範例：

ezgif com-gif-maker

強制重新繪製畫面

通常，ftxui::App::Loop() 負責在每一群新的事件（例如鍵盤、滑鼠、視窗大小調整等）被處理完後，繪製一個新的畫面。然而，你可能想要回應 FTXUI 未知的任意事件。要達成這點，你必須透過一個執行緒使用 ftxui::App::PostEvent（**這是執行緒安全的**）來發布事件。你必須發布事件 ftxui::Event::Custom。

範例：

screen->PostEvent(Event::Custom);

如果你不需要處理新的 Event，可以改用：

screen->RequestAnimationFrame();

來代替。

Table of Contents

輸入

篩選輸入

選單

Renderer

CheckBox

RadioBox

Dropdown

Slider

Renderer

CatchEvent

Collapsible

Maybe

Container

Horizontal

Vertical

Tab

ResizableSplit

強制重新繪製畫面