ftxui / dom

目录

• text
• vtext
• window
• separator
• graph
• Colors
  • Palette16 
  • Palette256 
  • TrueColor
• LinearGradient
• Style
• Layout
• Table
• Canvas

该模块定义了一组分层的 ftxui::Element。元素管理布局，并且可以响应终端尺寸变化。请注意以下示例，其中此模块用于创建具有多个运算符的简单布局：

Example 部分提供了一个示例集合。

示例：

namespace ftxui {
    ...
 
// Define the document
Element document = vbox({
  text("The window") | bold | color(Color::Blue),
  gauge(0.5)
  text("The footer")
});
 
// Add a border, by calling the `ftxui::border` decorator function.
document = border(document);
 
// Add another border, using the pipe operator.
document = document | border.
 
// Add another border, using the |= operator.
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 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);  // 助手：默认flexbox，行方向。
Element vflow(Elements);  // 助手：默认flexbox，列方向。
 
// -- 弹性 ---
// 定义当容器内并非所有空间都使用时如何共享剩余空间。
Element flex(Element);         // 如果可能/需要，展开/最小化。
Element flex_grow(Element);    // 如果可能，展开元素。
Element flex_shrink(Element);  // 如果需要，最小化元素。
 
Element xflex(Element);         // 如果可能/需要，在 X 轴上展开/最小化。
Element xflex_grow(Element);    // 如果可能，在 X 轴上展开元素。
Element xflex_shrink(Element);  // 如果需要，在 X 轴上最小化元素。
 
Element yflex(Element);         // 如果可能/需要，在 Y 轴上展开/最小化。
Element yflex_grow(Element);    // 如果可能，在 Y 轴上展开元素。
Element yflex_shrink(Element);  // 如果需要，在 Y 轴上最小化元素。
 
Element notflex(Element);  // 重置弹性属性。
Element filler();          // 一个空白的可扩展元素。
 
// -- 大小覆盖；
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);  // 已弃用 - 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 相同，但垂直显示。

代码：

终端输出：

bash H E L L O

# paragraph {#dom-paragraph}
 
类似于 `ftxui::text`，但单个单词会根据其容器的宽度在多行上换行。
 
示例代码：

cpp paragraph("A very long text")

![ezgif com-gif-maker (4)](https://user-images.githubusercontent.com/4759106/147251370-983a06e7-6f41-4113-92b8-942f43d34d06.gif)
 
有关更详细的示例，请参阅[详细示例](https://arthursonzogni.github.io/FTXUI/examples_2dom_2paragraph_8cpp-example.html)。Paragraph 还包括许多其他变体，如下所示：

cpp 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 {#dom-border}
 
在元素周围添加边框。
 
代码：

cpp 终端输出：```bash ┌───────────┐ │The element│ └───────────┘

> [!note]
> 你可以使用管道操作符实现相同的行为。
>
> 代码：
> 

cpp

‍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

window

ftxui::window 是一个 ftxui::border，但带有一个额外的标题。要在一个元素周围添加一个窗口，请将其包装并指定一个字符串作为标题。 代码：

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

Terminal output:

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

separator

显示垂直/水平线以在视觉上将容器的内容分成两部分。

代码：

border(
  hbox({
    text("Left"), 
    separator(),
    text("Right")
终端输出：

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

分隔符有多种样式，如下所示：

cpp 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 {#dom-gauge}
 
这是一个表示进度比率的视觉元素。
 
代码：

cpp 终端输出：

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

量规可以多种方向显示，如下所示：

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);

Colors

大多数终端控制台可以显示彩色文本和彩色背景。FTXUI 支持所有调色板：

颜色[画廊]：

Palette16 

在大多数终端上支持以下颜色：

• 默认
• 黑色
• 深灰色
• 浅灰色
• 白色
• 蓝色
• 浅蓝色
• 青色
• 浅青色
• 绿色
• 浅绿色
• 品红色
• 浅品红色
• 红色
• 浅红色
• 黄色
• 浅黄色

使用管道操作符使用上述颜色的示例：

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

Palette256 

在支持 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);

LinearGradient

FTXUI 支持线性渐变。可以在前景或背景上实现。

ftxui::LinearGradient 由一个角度（度）和颜色停止列表定义。

你还可以使用简化的构造函数：

参见 演示。

Style

除了彩色文本和彩色背景。许多终端支持文本效果，例如：bold、italic、dim、underlined、inverted、blink。

示例

要使用这些效果，只需用所需的效果包装你的元素：

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

或者，使用管道操作符将其链接到你的元素上：

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

Layout

使元素能够以以下方式排列：

• **水平**使用 ftxui::hbox
• **垂直**使用 ftxui::vbox
• **在网格内**使用 ftxui::gridbox
• **沿一个方向换行**使用 ftxui::flexbox。

示例使用 ftxui::hbox、ftxui::vbox 和 ftxui::filler。

示例使用 ftxui::gridbox：

示例使用 flexbox：

查看此示例和相关的演示。

元素也可以使用 ftxui::flex 装饰器变得灵活。

Code:

hbox({
  text("left") | border ,
  text("middle") | border | flex,
  终端输出：

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

Code:

cpp hbox({ text("left") | border , text("middle") | border | flex, 终端输出：

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

Table

使数据能够轻松格式化为整洁的表格状视觉形式。

代码示例：

Canvas

请参阅 API <ftxui/dom/canvas.hpp>

绘图可以在 ftxui::Canvas 上执行，使用盲文、块或简单字符：

简单示例：

复杂示例：