ftxui / component

Table of Contents

• Input
  • Filtered input
• Menu
• Toggle 
• CheckBox
• RadioBox
• Dropdown
• Slider
• Renderer
• CatchEvent
• Collapsible
• Maybe
• Container
  • Horizontal
  • Vertical
  • Tab
• ResizableSplit
• Force a frame redraw.

ftxui::component 模組定義了生成互動元件的邏輯，這些元件響應使用者事件（鍵盤、滑鼠等）。

Example 章節提供了一系列範例。

ftxui::ScreenInteractive 定義了一個主循環，用於渲染元件。

ftxui::Component 是 ftxui::ComponentBase 的共享指針。後者定義了：

• ftxui::ComponentBase::Render(): 如何渲染介面。
• ftxui::ComponentBase::OnEvent(): 如何響應事件。
• ftxui::ComponentBase::Add(): 在兩個元件之間建立父/子關係。元件樹用於定義如何使用鍵盤導航。

ftxui::Element 用於渲染單個畫面。

ftxui::Component 用於渲染動態使用者介面，生成多個畫面，並在事件發生時更新其狀態。

畫廊 多個元件的集合。 (demo)

所有預定義的元件都可以在 "ftxui/dom/component.hpp" 中找到。

// Copyright 2021 Arthur Sonzogni. 版權所有。
// 本源代碼受 MIT 許可證約束，詳情請參閱 LICENSE 文件。
#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/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)>;
Component operator|(Component component, ComponentDecorator decorator);
Component operator|(Component component, ElementDecorator decorator);
Component& operator|=(Component& component, ComponentDecorator decorator);
Component& operator|=(Component& component, ElementDecorator decorator);
 
namespace Container {
Component Vertical(Components children);
Component Vertical(Components children, int* selector);
Component Horizontal(Components children);
Component Horizontal(Components children, int* selector);
Component Tab(Components children, int* selector);
Component Stacked(Components children);
}  // namespace Container
 
Component Button(ButtonOption options);
Component Button(ConstStringRef label,
                 std::function<void()> on_click,
                 ButtonOption options = ButtonOption::Simple());
 
Component Checkbox(CheckboxOption options);
Component Checkbox(ConstStringRef label,
                   bool* checked,
                   CheckboxOption options = CheckboxOption::Simple());
 
Component Input(InputOption options = {});
Component Input(StringRef content, InputOption options = {});
Component Input(StringRef content,
                StringRef placeholder,
                InputOption options = {});
 
Component Menu(MenuOption options);
Component Menu(ConstStringListRef entries,
               int* selected_,
               MenuOption options = MenuOption::Vertical());
Component MenuEntry(MenuEntryOption options);
Component MenuEntry(ConstStringRef label, MenuEntryOption options = {});
 
Component Radiobox(RadioboxOption options);
Component Radiobox(ConstStringListRef entries,
                   int* selected_,
                   RadioboxOption options = {});
 
Component Dropdown(ConstStringListRef entries, int* selected);
Component Dropdown(DropdownOption options);
 
Component Toggle(ConstStringListRef entries, int* selected);
 
// General slider constructor:
template <typename T>
Component Slider(SliderOption<T> options);
 
// Shorthand without the `SliderOption` constructor:
Component Slider(ConstStringRef label,
                 Ref<int> value,
                 ConstRef<int> min = 0,
                 ConstRef<int> max = 100,
                 ConstRef<int> increment = 5);
Component Slider(ConstStringRef label,
                 Ref<float> value,
                 ConstRef<float> min = 0.f,
                 ConstRef<float> max = 100.f,
                 ConstRef<float> increment = 5.f);
Component Slider(ConstStringRef label,
                 Ref<long> value,
                 ConstRef<long> min = 0L,
                 ConstRef<long> max = 100L,
                 ConstRef<long> increment = 5L);
 
Component ResizableSplit(ResizableSplitOption options);
Component ResizableSplitLeft(Component main, Component back, int* main_size);
Component ResizableSplitRight(Component main, Component back, int* main_size);
Component ResizableSplitTop(Component main, Component back, int* main_size);
Component ResizableSplitBottom(Component main, Component back, int* main_size);
 
Component Renderer(Component child, std::function<Element()>);
Component Renderer(std::function<Element()>);
Component Renderer(std::function<Element(bool /* focused */)>);
ComponentDecorator Renderer(ElementDecorator);
 
Component CatchEvent(Component child, std::function<bool(Event)>);
ComponentDecorator CatchEvent(std::function<bool(Event)> on_event);
 
Component Maybe(Component, const bool* show);
Component Maybe(Component, std::function<bool()>);
ComponentDecorator Maybe(const bool* show);
ComponentDecorator Maybe(std::function<bool()>);
 
Component Modal(Component main, Component modal, const bool* show_modal);
ComponentDecorator Modal(Component modal, const bool* show_modal);
 
Component Collapsible(ConstStringRef label,
                      Component child,
                      Ref<bool> show = false);
 
Component Hoverable(Component component, bool* hover);
Component Hoverable(Component component,
                    std::function<void()> on_enter,
                    std::function<void()> on_leave);
Component Hoverable(Component component,  //
                    std::function<void(bool)> on_change);
ComponentDecorator Hoverable(bool* hover);
ComponentDecorator Hoverable(std::function<void()> on_enter,
                             std::function<void()> on_leave);
ComponentDecorator Hoverable(std::function<void(bool)> on_change);
 
Component Window(WindowOptions option);
 
}  // namespace ftxui
 
#endif /* end of include guard: FTXUI_COMPONENT_HPP */

Input

範例：

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

Filtered input

可以使用 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;
});

Menu

定義一個選單物件。它包含一個條目列表，其中一個被選中。

範例：

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

Toggle 

一種特殊的選單。條目水平顯示。

範例：

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

CheckBox

此元件定義了一個核取方塊。它是一個單一條目，可以開啟/關閉。

範例：

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

RadioBox

一個單選按鈕元件。這是一個條目列表，其中一個可以開啟。

範例：

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

Dropdown

下拉式選單是一個元件，當開啟時，會顯示一個元素列表供使用者選擇。

範例：

由 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 = ScreenInteractive::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)

謂詞範例：

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" 生成。它接受元件列表並僅顯示其中一個。這對於實現分頁欄很有用。

垂直：

水平：

ResizableSplit

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

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

範例：

Force a frame redraw.

通常，ftxui::ScreenInteractive::Loop() 負責在處理完新的事件組（例如鍵盤、滑鼠、視窗大小調整等）時繪製新畫面。但是，您可能希望響應 FTXUI 未知的任意事件。為此，您必須通過執行緒使用 ftxui::ScreenInteractive::PostEvent（**這是執行緒安全的**）發布事件。您必須發布事件 ftxui::Event::Custom。

範例：

screen->PostEvent(Event::Custom);

如果您不需要處理新事件，可以使用：

screen->RequestAnimationFrame();

代替。

```