ftxui / dom

Table of Contents

• text
• vtext
• paragraph 
• border
• window
• separator
• gauge
• graph
• 顏色
  • 16色調色板
  • 256色調色板
  • TrueColor (真彩色)
• 線性漸層
• 樣式
• 佈局
• 表格
• 畫布

此模組定義了一組分層的 ftxui::Element。元素管理佈局，並能響應終端尺寸的變化。請注意以下範例，其中此模組用於創建一個帶有多個操作符的簡單佈局：

Example 部分提供了一系列範例。

Example:

namespace ftxui {
    ...
 
// 定義文件
Element document = vbox({
  text("The window") | bold | color(Color::Blue),
  gauge(0.5)
  text("The footer")
});
 
// 添加邊框，透過呼叫 `ftxui::border` 裝飾器函數。
document = border(document);
 
// 使用 pipe 運算符添加另一個邊框。
document = document | border.
 
// 使用 |= 運算符添加另一個邊框。
document |= border
 
...
}

元素列表

所有元素的列表都已包含，可以透過包含相應的頭文件來訪問：

#include <ftxui/dom/elements.hpp>

// Copyright 2020 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_DOM_ELEMENTS_HPP
#define FTXUI_DOM_ELEMENTS_HPP
 
#include <functional>
#include <memory>
 
#include "ftxui/dom/canvas.hpp"
#include "ftxui/dom/direction.hpp"
#include "ftxui/dom/flexbox_config.hpp"
#include "ftxui/dom/linear_gradient.hpp"
#include "ftxui/dom/node.hpp"
#include "ftxui/screen/box.hpp"
#include "ftxui/screen/color.hpp"
#include "ftxui/screen/terminal.hpp"
#include "ftxui/util/ref.hpp"
 
namespace ftxui {
class Node;
using Element = std::shared_ptr<Node>;
using Elements = std::vector<Element>;
using Decorator = std::function<Element(Element)>;
using GraphFunction = std::function<std::vector<int>(int, int)>;
 
/// @brief BorderStyle 是一個列舉，表示可以應用於終端機 UI 元素的不同邊框樣式。
///
/// BorderStyle 是一個列舉，表示可以應用於終端機 UI 元素的不同邊框樣式。
/// 它用於定義元素周圍邊框的視覺外觀，例如視窗、框架或分隔符。
/// @ingroup dom
enum BorderStyle {
  LIGHT,
  DASHED,
  HEAVY,
  DOUBLE,
  ROUNDED,
  EMPTY,
};
 
// 將元素串聯到裝飾器中。
// 例如，以下幾行是等效的：
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))
Element operator|(Element, Decorator);
Element& operator|=(Element&, Decorator);
Elements operator|(Elements, Decorator);
Decorator operator|(Decorator, Decorator);
 
// --- 小工具 ---
Element text(std::string text);
Element vtext(std::string text);
Element separator();
Element separatorLight();
Element separatorDashed();
Element separatorHeavy();
Element separatorDouble();
Element separatorRounded();
Element separatorEmpty();
Element separatorStyled(BorderStyle);
Element separator(Pixel);
Element separatorCharacter(std::string);
Element separatorHSelector(float left,
                           float right,
                           Color unselected_color,
                           Color selected_color);
Element separatorVSelector(float up,
                           float down,
                           Color unselected_color,
                           Color selected_color);
Element gauge(float progress);
Element gaugeLeft(float progress);
Element gaugeRight(float progress);
Element gaugeUp(float progress);
Element gaugeDown(float progress);
Element gaugeDirection(float progress, Direction direction);
Element border(Element);
Element borderLight(Element);
Element borderDashed(Element);
Element borderHeavy(Element);
Element borderDouble(Element);
Element borderRounded(Element);
Element borderEmpty(Element);
Decorator borderStyled(BorderStyle);
Decorator borderStyled(BorderStyle, Color);
Decorator borderStyled(Color);
Decorator borderWith(const Pixel&);
Element window(Element title, Element content, BorderStyle border = ROUNDED);
Element spinner(int charset_index, size_t image_index);
Element paragraph(const std::string& text);
Element paragraphAlignLeft(const std::string& text);
Element paragraphAlignRight(const std::string& text);
Element paragraphAlignCenter(const std::string& text);
Element paragraphAlignJustify(const std::string& text);
Element graph(GraphFunction);
Element emptyElement();
Element canvas(ConstRef<Canvas>);
Element canvas(int width, int height, std::function<void(Canvas&)>);
Element canvas(std::function<void(Canvas&)>);
 
// -- 裝飾器 ---
Element bold(Element);
Element dim(Element);
Element italic(Element);
Element inverted(Element);
Element underlined(Element);
Element underlinedDouble(Element);
Element blink(Element);
Element strikethrough(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);
Element color(Color, Element);
Element bgcolor(Color, Element);
Element color(const LinearGradient&, Element);
Element bgcolor(const LinearGradient&, Element);
Decorator focusPosition(int x, int y);
Decorator focusPositionRelative(float x, float y);
Element automerge(Element child);
Decorator hyperlink(std::string link);
Element hyperlink(std::string link, Element child);
Element selectionStyleReset(Element);
Decorator selectionColor(Color foreground);
Decorator selectionBackgroundColor(Color foreground);
Decorator selectionForegroundColor(Color foreground);
Decorator selectionStyle(std::function<void(Pixel&)> style);
 
// --- 佈局是
// 水平、垂直或堆疊的元素集合。
Element hbox(Elements);
Element vbox(Elements);
Element dbox(Elements);
Element flexbox(Elements, FlexboxConfig config = FlexboxConfig());
Element gridbox(std::vector<Elements> lines);
 
Element hflow(Elements);  // Helper: default flexbox with row direction.
Element vflow(Elements);  // Helper: default flexbox with column direction.
 
// -- 彈性 ---
// 定義當容器中並非所有空間都被使用時，如何分享剩餘空間。
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 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 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.
 
// -- 大小覆蓋；
enum WidthOrHeight { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(WidthOrHeight, Constraint, int value);
 
// --- 框架 ---
// 框架是可滾動的區域。內部區域可能大於外部區域。內部區域會滾動以使焦點元素可見。
Element frame(Element);
Element xframe(Element);
Element yframe(Element);
Element focus(Element);
Element select(Element e);  // Deprecated - Alias for focus.
 
// --- 光標 ---
// 這些與 `focus` 相似，但也會改變光標的形狀。
Element focusCursorBlock(Element);
Element focusCursorBlockBlinking(Element);
Element focusCursorBar(Element);
Element focusCursorBarBlinking(Element);
Element focusCursorUnderline(Element);
Element focusCursorUnderlineBlinking(Element);
 
// --- 其他 ---
Element vscroll_indicator(Element);
Element hscroll_indicator(Element);
Decorator reflect(Box& box);
// 在繪製 |element| 之前清除下方的像素。這對於結合 dbox 很有用。
Element clear_under(Element element);
 
// --- 公用程式 --------------------------------------------------------------------
Element hcenter(Element);
Element vcenter(Element);
Element center(Element);
Element align_right(Element);
Element nothing(Element element);
 
namespace Dimension {
Dimensions Fit(Element&, bool extend_beyond_screen = false);
}  // namespace Dimension
 
}  // namespace ftxui
 
// 使容器能夠接受任意數量的子元素作為輸入。
#include "ftxui/dom/take_any_args.hpp"
 
// 包含使用 wstring 的舊定義。
#include "ftxui/dom/deprecated.hpp"
#endif  // FTXUI_DOM_ELEMENTS_HPP

text

最簡單的小部件。它顯示一段文字。

text("I am a piece of text");

I am a piece of text.

vtext

與 ftxui::text 相同，但垂直顯示。

Code:

vtext("HELLO");

Terminal output:

H
E
L
L
O

paragraph 

類似於 ftxui::text，但單詞會根據其容器的寬度自動換行到多行。

範例程式碼：

paragraph("A very long text")

有關更詳細的範例，請參閱 詳細範例。Paragraph 還包括以下所示的其他變體：

namespace ftxui {
    Element paragraph(std::string text);
    Element paragraphAlignLeft(std::string text);
    Element paragraphAlignRight(std::string text);
    Element paragraphAlignCenter(std::string text);
    Element paragraphAlignJustify(std::string text);
}

border

為元素添加邊框。

Code:

border(text("The element"))

Terminal output:

┌───────────┐
│The element│
└───────────┘

Note

您可以使用 pipe 運算符實現相同的行為。

程式碼：

text("The element") | border

Border 也支援多種樣式，如下所示：

namespace ftxui {
    Element border(Element);
    Element borderLight(Element);
    Element borderHeavy(Element);
    Element borderDouble(Element);
    Element borderRounded(Element);
    Element borderEmpty(Element);
    Decorator borderStyled(BorderStyle);
    Decorator borderWith(Pixel);
}

window

ftxui::window 是一個 ftxui::border，但帶有額外的標頭。要為元素添加視窗，請將其包裹並指定一個字串作為標頭。 程式碼：

window("The window", text("The element"))

Terminal output:

┌The window─┐
│The element│
└───────────┘

separator

顯示垂直/水平線，以視覺上將容器的內容一分為二。

Code:

border(
  hbox({
    text("Left"), 
    separator(),
    text("Right")
  })
)

Terminal output:

┌────┬─────┐
│left│right│
└────┴─────┘

分隔線有多種樣式，如下所示：

namespace ftxui {
    Element separator(void);
    Element separatorLight();
    Element separatorHeavy();
    Element separatorDouble();
    Element separatorEmpty();
    Element separatorStyled(BorderStyle);
    Element separator(Pixel);
    Element separatorCharacter(std::string);
    Element separatorHSelector(float left,
                               float right,
                               Color background,
                               Color foreground);
    Element separatorVSelector(float up,
                               float down,
                               Color background,
                               Color foreground);
}

gauge

這是一個表示進度比例的視覺元素。

Code:

border(gauge(0.5))

Terminal output:

┌────────────────────────────────────────────────────────────────────────────┐
│██████████████████████████████████████                                      │
└────────────────────────────────────────────────────────────────────────────┘

量規可以以多種方向顯示，如下所示：

namespace {
    Element gauge(float ratio);
    Element gaugeLeft(float ratio);
    Element gaugeRight(float ratio);
    Element gaugeUp(float ratio);
    Element gaugeDown(float ratio);
    Element gaugeDirection(float ratio, GaugeDirection);
}

graph

詳見：

Element graph(GraphFunction);

顏色

大多數終端控制台都可以顯示彩色文本和彩色背景。FTXUI 支援所有調色板：

Decorator color(Color);
Decorator bgcolor(Color);

Color gallery:

16色調色板

大多數終端都支援以下顏色：

• Default
• Black
• GrayDark
• GrayLight
• White
• Blue
• BlueLight
• Cyan
• CyanLight
• Green
• GreenLight
• Magenta
• MagentaLight
• Red
• RedLight
• Yellow
• YellowLight

Example use of the above colors using the pipe operator:

text("Blue foreground") | color(Color::Blue);
text("Blue background") | bgcolor(Color::Blue);
text("Black on white") | color(Color::Black) | bgcolor(Color::White);

256色調色板

在支援 256 種顏色的終端上。

text("HotPink") | color(Color::HotPink);

TrueColor (真彩色)

在支援 TrueColor 的終端上，您可以直接使用 24 位 RGB 顏色空間：

使用以下構造函數來指定顏色的 RGB 或 HSV 值：

有兩個構造函數：

ftxui::Color::RGB(uint8_t red, uint8_t green, uint8_t blue);
ftxui::Color::HSV(uint8_t hue, uint8_t saturation, uint8_t value);

線性漸層

FTXUI 支援線性漸層。無論是在前景還是背景上。

Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);

ftxui::LinearGradient 由角度（以度為單位）和顏色停止點列表定義。

auto gradient = LinearGradient()
  .Angle(45)
  .AddStop(0.0, Color::Red)
  .AddStop(0.5, Color::Green)
  .AddStop(1.0, Color::Blue);

您也可以使用簡化的構造函數：

LinearGradient(Color::Red, Color::Blue);

LinearGradient(45, Color::Red, Color::Blue);

See demo.

樣式

除了彩色文本和彩色背景之外。許多終端還支援文本效果，例如：bold（粗體）、italic（斜體）、dim（變暗）、underlined（底線）、inverted（反轉）、blink（閃爍）。

Element bold(Element);
Element italic(Element);
Element dim(Element);
Element inverted(Element);
Element underlined(Element);
Element underlinedDouble(Element);
Element strikethrough(Element);
Element blink(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Decorator colorgrad(LinearGradient);
Decorator bgcolorgrad(LinearGradient);

Example

要使用這些效果，只需將您的元素包裹在您想要的效果中：

underlined(bold(text("This text is bold and underlined")))

或者，使用 pipe 運算符將其鏈接到您的元素上：

text("This text is bold") | bold | underlined

佈局

使元素可以透過以下方式排列：

• 水平 使用 ftxui::hbox
• 垂直 使用 ftxui::vbox
• 在網格內部 使用 ftxui::gridbox
• 沿一個方向換行 使用 ftxui::flexbox。

Example using ftxui::hbox, ftxui::vbox and ftxui::filler.

Example using ftxui::gridbox:

Example using flexbox:

Checkout this example and the associated demo.

元素也可以使用 ftxui::flex 裝飾器變得靈活。

Code:

hbox({
  text("left") | border ,
  text("middle") | border | flex,
  text("right") | border,
});

Terminal output:

┌────┐┌─────────────────────────────────────────────────────┐┌─────┐
│left││middle                                               ││right│
└────┘└─────────────────────────────────────────────────────┘└─────┘

Code:

hbox({
  text("left") | border ,
  text("middle") | border | flex,
  text("right") | border | flex,
});

Terminal output:

┌────┐┌───────────────────────────────┐┌───────────────────────────────┐
│left││middle                         ││right                          │
└────┘└───────────────────────────────┘└───────────────────────────────┘

表格

能夠輕鬆將資料格式化為整齊的表格狀視覺形式。

Code example:

畫布

詳見 API <ftxui/dom/canvas.hpp>

auto c = Canvas(100, 100);
c.DrawPointLine(10, 10, 80, 10, Color::Red);
auto element = canvas(c);

繪圖可以在 ftxui::Canvas 上執行，使用盲文、區塊或簡單字元：

Simple example:

Complex example: