ftxui / dom

Table of Contents

• text
• vtext
• paragraph
• border
• window
• separator
• gauge
• graph
• 色
  • Palette16
  • Palette256
  • トゥルーカラー
• 線形グラデーション
• Style
• レイアウト
• テーブル
  • • 選択とスタイリング
    • 色付きの枠線
• キャンバス

このモジュールは、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 <cstdint>
#include <functional>
#include <memory>
 
#include <string_view>
#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/export.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 : uint8_t {
  LIGHT,
  DASHED,
  HEAVY,
  DOUBLE,
  ROUNDED,
  EMPTY,
};
 
// デコレータと共に要素をパイプします。
// 例えば、次の行は同等です:
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))
FTXUI_EXPORT(DOM) Element operator|(Element, Decorator);
FTXUI_EXPORT(DOM) Element& operator|=(Element&, Decorator);
FTXUI_EXPORT(DOM) Elements operator|(Elements, Decorator);
FTXUI_EXPORT(DOM) Decorator operator|(Decorator, Decorator);
 
// --- ウィジェット ---
FTXUI_EXPORT(DOM) Element text(std::string_view text);
FTXUI_EXPORT(DOM) Element vtext(std::string_view text);
FTXUI_EXPORT(DOM) Element separator();
FTXUI_EXPORT(DOM) Element separatorLight();
FTXUI_EXPORT(DOM) Element separatorDashed();
FTXUI_EXPORT(DOM) Element separatorHeavy();
FTXUI_EXPORT(DOM) Element separatorDouble();
FTXUI_EXPORT(DOM) Element separatorEmpty();
FTXUI_EXPORT(DOM) Element separatorStyled(BorderStyle);
FTXUI_EXPORT(DOM) Element separator(Cell);
FTXUI_EXPORT(DOM) Element separatorCharacter(std::string_view);
FTXUI_EXPORT(DOM)
Element separatorHSelector(float left,
                           float right,
                           Color unselected_color,
                           Color selected_color);
FTXUI_EXPORT(DOM)
Element separatorVSelector(float up,
                           float down,
                           Color unselected_color,
                           Color selected_color);
FTXUI_EXPORT(DOM) Element gauge(float progress);
FTXUI_EXPORT(DOM) Element gaugeLeft(float progress);
FTXUI_EXPORT(DOM) Element gaugeRight(float progress);
FTXUI_EXPORT(DOM) Element gaugeUp(float progress);
FTXUI_EXPORT(DOM) Element gaugeDown(float progress);
FTXUI_EXPORT(DOM) Element gaugeDirection(float progress, Direction direction);
 
// charset[0]は"空"のグリフで、charset.back()は"満杯"です。間にある
// エントリは境界セルを陰影付けします。
FTXUI_EXPORT(DOM)
Element gaugeCharset(float progress,
                      std::vector<std::string> charset,
                      Direction direction = Direction::Right);
FTXUI_EXPORT(DOM) Element border(Element);
FTXUI_EXPORT(DOM) Element borderLight(Element);
FTXUI_EXPORT(DOM) Element borderDashed(Element);
FTXUI_EXPORT(DOM) Element borderHeavy(Element);
FTXUI_EXPORT(DOM) Element borderDouble(Element);
FTXUI_EXPORT(DOM) Element borderRounded(Element);
FTXUI_EXPORT(DOM) Element borderEmpty(Element);
FTXUI_EXPORT(DOM) Decorator borderStyled(BorderStyle);
FTXUI_EXPORT(DOM) Decorator borderStyled(BorderStyle, Color);
FTXUI_EXPORT(DOM) Decorator borderStyled(Color);
FTXUI_EXPORT(DOM) Decorator borderWith(const Cell&);
FTXUI_EXPORT(DOM)
Element window(Element title, Element content, BorderStyle border = ROUNDED);
FTXUI_EXPORT(DOM) Element spinner(int charset_index, size_t image_index);
FTXUI_EXPORT(DOM) Element paragraph(std::string_view text);
FTXUI_EXPORT(DOM) Element paragraphAlignLeft(std::string_view text);
FTXUI_EXPORT(DOM) Element paragraphAlignRight(std::string_view text);
FTXUI_EXPORT(DOM) Element paragraphAlignCenter(std::string_view text);
FTXUI_EXPORT(DOM) Element paragraphAlignJustify(std::string_view text);
FTXUI_EXPORT(DOM) Element graph(GraphFunction);
FTXUI_EXPORT(DOM) Element emptyElement();
FTXUI_EXPORT(DOM) Element canvas(ConstRef<Canvas>);
FTXUI_EXPORT(DOM)
Element canvas(int width, int height, std::function<void(Canvas&)>);
FTXUI_EXPORT(DOM) Element canvas(std::function<void(Canvas&)>);
 
// -- デコレータ ---
FTXUI_EXPORT(DOM) Element bold(Element);
FTXUI_EXPORT(DOM) Element dim(Element);
FTXUI_EXPORT(DOM) Element italic(Element);
FTXUI_EXPORT(DOM) Element inverted(Element);
FTXUI_EXPORT(DOM) Element underlined(Element);
FTXUI_EXPORT(DOM) Element underlinedDouble(Element);
FTXUI_EXPORT(DOM) Element blink(Element);
FTXUI_EXPORT(DOM) Element strikethrough(Element);
FTXUI_EXPORT(DOM) Decorator color(Color);
FTXUI_EXPORT(DOM) Decorator bgcolor(Color);
FTXUI_EXPORT(DOM) Decorator color(const LinearGradient&);
FTXUI_EXPORT(DOM) Decorator bgcolor(const LinearGradient&);
FTXUI_EXPORT(DOM) Element color(Color, Element);
FTXUI_EXPORT(DOM) Element bgcolor(Color, Element);
FTXUI_EXPORT(DOM) Element color(const LinearGradient&, Element);
FTXUI_EXPORT(DOM) Element bgcolor(const LinearGradient&, Element);
FTXUI_EXPORT(DOM) Decorator focusPosition(int x, int y);
FTXUI_EXPORT(DOM) Decorator focusPositionRelative(float x, float y);
FTXUI_EXPORT(DOM) Element automerge(Element child);
FTXUI_EXPORT(DOM) Decorator hyperlink(std::string_view link);
FTXUI_EXPORT(DOM) Element hyperlink(std::string_view link, Element child);
FTXUI_EXPORT(DOM) Element selectionStyleReset(Element);
FTXUI_EXPORT(DOM) Decorator selectionColor(Color foreground);
FTXUI_EXPORT(DOM) Decorator selectionBackgroundColor(Color foreground);
FTXUI_EXPORT(DOM) Decorator selectionForegroundColor(Color foreground);
FTXUI_EXPORT(DOM) Decorator selectionStyle(std::function<void(Cell&)> style);
 
// --- レイアウトは
// 水平、垂直、またはスタックされた要素のセットです。
FTXUI_EXPORT(DOM) Element hbox(Elements);
FTXUI_EXPORT(DOM) Element vbox(Elements);
FTXUI_EXPORT(DOM) Element dbox(Elements);
FTXUI_EXPORT(DOM)
Element flexbox(Elements, FlexboxConfig config = FlexboxConfig());
FTXUI_EXPORT(DOM) Element gridbox(std::vector<Elements> lines);
 
FTXUI_EXPORT(DOM)
Element hflow(Elements);  // ヘルパー: 行方向のデフォルトflexbox。
FTXUI_EXPORT(DOM)
Element vflow(Elements);  // ヘルパー: 列方向のデフォルトflexbox。
 
// -- 柔軟性 ---
// コンテナ内ですべてが使用されていない残りのスペースを
// どのように共有するかを定義します。
FTXUI_EXPORT(DOM) Element flex(Element);  // 可能/必要な場合に拡大/最小化します。
FTXUI_EXPORT(DOM) Element flex_grow(Element);    // 可能な場合に要素を拡大します。
FTXUI_EXPORT(DOM) Element flex_shrink(Element);  // 必要な場合に要素を最小化します。
FTXUI_EXPORT(DOM) Decorator flex_factor(int grow, int shrink);
FTXUI_EXPORT(DOM) Decorator flex_grow_factor(int grow);
FTXUI_EXPORT(DOM) Decorator flex_shrink_factor(int shrink);
 
FTXUI_EXPORT(DOM)
Element xflex(Element);  // X軸で可能/必要な場合に拡大/最小化します。
FTXUI_EXPORT(DOM)
Element xflex_grow(Element);  // X軸で可能な場合に要素を拡大します。
FTXUI_EXPORT(DOM)
Element xflex_shrink(Element);  // X軸で必要な場合に要素を最小化します。
FTXUI_EXPORT(DOM) Decorator xflex_factor(int grow, int shrink);
FTXUI_EXPORT(DOM) Decorator xflex_grow_factor(int grow);
FTXUI_EXPORT(DOM) Decorator xflex_shrink_factor(int shrink);
 
FTXUI_EXPORT(DOM)
Element yflex(Element);  // Y軸で可能/必要な場合に拡大/最小化します。
FTXUI_EXPORT(DOM)
Element yflex_grow(Element);  // Y軸で可能な場合に要素を拡大します。
FTXUI_EXPORT(DOM)
Element yflex_shrink(Element);  // Y軸で必要な場合に要素を最小化します。
FTXUI_EXPORT(DOM) Decorator yflex_factor(int grow, int shrink);
FTXUI_EXPORT(DOM) Decorator yflex_grow_factor(int grow);
FTXUI_EXPORT(DOM) Decorator yflex_shrink_factor(int shrink);
 
FTXUI_EXPORT(DOM) Element notflex(Element);  // flex属性をリセットします。
FTXUI_EXPORT(DOM) Element filler();          // 空白の拡大可能な要素。
 
// -- サイズのオーバーライド;
enum WidthOrHeight : uint8_t { WIDTH, HEIGHT };
enum Constraint : uint8_t { LESS_THAN, EQUAL, GREATER_THAN };
FTXUI_EXPORT(DOM) Decorator size(WidthOrHeight, Constraint, int value);
 
// --- フレーム ---
// フレームはスクロール可能な領域です。内部領域は外部領域よりも
// 大きい可能性があります。内部領域は、フォーカスされた要素を
// 表示させるためにスクロールされます。
FTXUI_EXPORT(DOM) Element frame(Element);
FTXUI_EXPORT(DOM) Element xframe(Element);
FTXUI_EXPORT(DOM) Element yframe(Element);
FTXUI_EXPORT(DOM) Element focus(Element);
FTXUI_EXPORT(DOM) Element select(Element e);  // 非推奨 - focusのエイリアス。
 
// --- カーソル ---
// これらは`focus`に似ていますが、カーソルの形状も変更します。
FTXUI_EXPORT(DOM) Element focusCursorBlock(Element);
FTXUI_EXPORT(DOM) Element focusCursorBlockBlinking(Element);
FTXUI_EXPORT(DOM) Element focusCursorBar(Element);
FTXUI_EXPORT(DOM) Element focusCursorBarBlinking(Element);
FTXUI_EXPORT(DOM) Element focusCursorUnderline(Element);
FTXUI_EXPORT(DOM) Element focusCursorUnderlineBlinking(Element);
 
// --- その他 ---
FTXUI_EXPORT(DOM) Element vscroll_indicator(Element);
FTXUI_EXPORT(DOM) Element hscroll_indicator(Element);
FTXUI_EXPORT(DOM) Decorator reflect(Box& box);
// |element|を描画する前に、下のピクセルをクリアします。これはdboxと
// 組み合わせて使用すると便利です。
FTXUI_EXPORT(DOM) Element clear_under(Element element);
 
// --- ユーティリティ --------------------------------------------------------------------
FTXUI_EXPORT(DOM) Element hcenter(Element);
FTXUI_EXPORT(DOM) Element vcenter(Element);
FTXUI_EXPORT(DOM) Element center(Element);
FTXUI_EXPORT(DOM) Element align_right(Element);
FTXUI_EXPORT(DOM) Element nothing(Element element);
 
namespace Dimension {
FTXUI_EXPORT(DOM) 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と同じですが、垂直に表示されます。

コード:

vtext("HELLO");

ターミナルの出力:

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

要素の周りに枠線を追加します。

コード:

border(text("The element"))

ターミナルの出力:

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

Note

パイプ演算子を使用しても同じ動作を実現できます。

コード:

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(Cell);
}

window

ftxui::windowはftxui::borderですが、追加のヘッダーがあります。要素の周囲にウィンドウを追加するには、それをラップし、ヘッダーとして文字列を指定します。 コード:

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

ターミナルの出力:

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

separator

コンテナの内容を視覚的に2つに分割するために、垂直/水平の線を 表示します。

コード:

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

ターミナルの出力:

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

Separatorsには、以下に示すさまざまなフレーバーがあります。

namespace ftxui {
    Element separator(void);
    Element separatorLight();
    Element separatorHeavy();
    Element separatorDouble();
    Element separatorEmpty();
    Element separatorStyled(BorderStyle);
    Element separator(Cell);
    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

これは進捗の割合を表す視覚要素です。

コード:

border(gauge(0.5))

ターミナルの出力:

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

ゲージは以下に示すように様々な向きで表示できます:

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

カラーギャラリー:

Palette16

ほとんどのターミナルでは、以下の色がサポートされています。

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

パイプ演算子を使った上記の色の使用例:

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をサポートするターミナルでは、24ビットRGB色空間を直接使用できます。

以下のコンストラクタを使用して、色の**RGB**または**HSV**値を指定します。

コンストラクタは2つあります:

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

デモを参照してください。

Style

色付きのテキストと色付きの背景に加えて、多くのターミナルは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);

例

これらの効果を使用するには、要素を目的の効果でラップするだけです:

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

あるいは、パイプ演算子を使って要素にチェーンすることもできます:

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

レイアウト

要素を次の方法で配置できます。

• ftxui::hboxで**水平に**
• ftxui::vboxで**垂直に**
• ftxui::gridboxで**グリッド内に**
• ftxui::flexboxを使用して**一方向に折り返し**

ftxui::hbox、ftxui::vbox、ftxui::fillerを使用した例。

ftxui::gridboxを使用した例。

flexboxを使用した例。

この例と関連するデモを確認してください。

要素はftxui::flexデコレータを使用して柔軟にすることもできます。

コード:

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

ターミナルの出力:

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

コード:

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

ターミナルの出力:

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

テーブル

データを整然としたテーブル形式に簡単に整形できます。

基本的な例:

auto table = Table({
  {"Planet", "Radius", "Mass"},
  {"Mercury", "2440", "0.330"},
  {"Venus", "6052", "4.87"},
  {"Earth", "6371", "5.97"},
  {"Mars", "3390", "0.642"},
});
 
table.SelectAll().Border(LIGHT);
table.SelectRow(0).Decorate(bold);
table.SelectRow(0).SeparatorVertical(LIGHT);
table.SelectRow(0).Border(DOUBLE);
 
auto document = table.Render();

コード例:

選択とスタイリング

テーブルの一部を選択し、デコレーターや枠線を適用できます。選択方法には以下が含まれます:

ftxui::TableSelection::SelectAll();
ftxui::TableSelection::SelectCell(column, row);
ftxui::TableSelection::SelectRow(row_index);
ftxui::TableSelection::SelectRows(row_min, row_max);
ftxui::TableSelection::SelectColumn(column_index);
ftxui::TableSelection::SelectColumns(column_min, column_max);
ftxui::TableSelection::SelectRectangle(column_min, column_max, row_min, row_max);

選択が行われたら、以下を適用できます:

ftxui::TableSelection::Decorate(Decorator); // Apply a decorator to the whole selection (cells and borders).
ftxui::TableSelection::DecorateCells(Decorator); // Apply a decorator only to the cells.
ftxui::TableSelection::Border(BorderStyle); // Add a border around the selection.
ftxui::TableSelection::Separator(BorderStyle); // 

色付きの枠線

枠線や区切り線にのみ特化してデコレーターを適用することもできます:

// Apply a red border to the whole table.
table.SelectAll().Border(LIGHT, color(Color::Red));
 
// Apply a blue separator to the first row.
table.SelectRow(0).SeparatorVertical(LIGHT, color(Color::Blue));

枠線を細かく装飾するために、以下のメソッドが利用可能です:

ftxui::TableSelection::DecorateBorder(Decorator); // Apply a decorator to all borders of the selection.
ftxui::TableSelection::DecorateBorderLeft(Decorator); // Apply a decorator to the left border of the selection.
ftxui::TableSelection::DecorateBorderRight(Decorator); // Apply a decorator to the right border of the selection.
ftxui::TableSelection::DecorateBorderTop(Decorator); // Apply a decorator to the top border of the selection.
ftxui::TableSelection::DecorateBorderBottom(Decorator); // Apply a decorator to the bottom border of the selection.
ftxui::TableSelection::DecorateSeparator(Decorator); // Apply a decorator to all separators of the selection.
ftxui::TableSelection::DecorateSeparatorVertical(Decorator); // Apply a decorator to all vertical separators of the selection.
ftxui::TableSelection::DecorateSeparatorHorizontal(Decorator); // Apply a decorator to all horizontal separators of the selection.

キャンバス

API <ftxui/dom/canvas.hpp>を参照してください。

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

描画はftxui::Canvasで、点字、ブロック、または単純な文字を使用して実行できます。

単純な例:

複雑な例: