Loading...
Searching...
No Matches
FTXUI

# Introduction

Welcome to the FTXUI documentation!

This is a brief tutorial. You are also encouraged to self-learn by reading the examples.

Short example

To build a single frame, you need create an `ftxui::Element`, and display it on a `ftxui::Screen`.

main.cpp

#include <ftxui/dom/elements.hpp>
#include <ftxui/screen/screen.hpp>
#include <iostream>
int main(void) {
using namespace ftxui;
// Define the document
Element document =
hbox({
text("left") | border,
text("middle") | border | flex,
text("right") | border,
});
auto screen = Screen::Create(
Dimension::Full(), // Width
Dimension::Fit(document) // Height
);
Render(screen, document);
screen.Print();
return EXIT_SUCCESS;
}
elements.hpp
ftxui
Definition animation.hpp:10
ftxui::Element
std::shared_ptr< Node > Element
Definition elements.hpp:22
screen.hpp

output

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

## Configure

### Using CMake and find_package

Assuming FTXUI is available or installed on the system.

CMakeLists.txt

cmake_minimum_required (VERSION 3.11)
find_package(ftxui 5 REQUIRED)
project(ftxui-starter LANGUAGES CXX VERSION 1.0.0)
add_executable(ftxui-starter src/main.cpp)
target_link_libraries(ftxui-starter
PRIVATE ftxui::screen
PRIVATE ftxui::dom
PRIVATE ftxui::component # Not needed for this example.
)

### Using CMake and FetchContent

If you want to fetch FTXUI using cmake:

CMakeLists.txt

cmake_minimum_required (VERSION 3.11)
include(FetchContent)
set(FETCHCONTENT_UPDATES_DISCONNECTED TRUE)
FetchContent_Declare(ftxui
GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
GIT_TAG main # Important: Specify a version or a commit hash here.
)
FetchContent_MakeAvailable(ftxui)
project(ftxui-starter LANGUAGES CXX VERSION 1.0.0)
add_executable(ftxui-starter src/main.cpp)
target_link_libraries(ftxui-starter
PRIVATE ftxui::screen
PRIVATE ftxui::dom
PRIVATE ftxui::component # Not needed for this example.
)

## Build

mkdir build && cd build
cmake ..
make
./main

# List of modules.

The project is comprised of 3 modules:

1. ftxui/screen defines a `ftxui::Screen`, a grid of `ftxui::Pixel`.
2. ftxui/dom is the main module. It defines a hierarchical set of `ftxui::Element`. An element draws something on the `ftxui::Screen`. It is responsive to the size of its container.
3. ftxui/component The module is required if your program needs to respond to user input. It defines a set of `ftxui::Component`. These components can be utilized to navigate using the arrow keys and/or cursor. There are several builtin widgets like checkbox/inputbox/etc to interact with. You can combine them, or even define your own custom components.

# screen

This is the visual element of the program. It defines a `ftxui::Screen`, which is a grid of `ftxui::Pixel`. A Pixel represents a Unicode character and its associated style (bold, italic, colors, etc.). The screen can be printed as a string using `ftxui::Screen::ToString()`. The following example highlights this process:

#include <ftxui/screen/screen.hpp>
#include <iostream>
int main(void) {
using namespace ftxui;
auto screen = Screen::Create(Dimension::Fixed(32), Dimension::Fixed(10));
auto& pixel = screen.PixelAt(9,9);
pixel.character = U'A';
pixel.bold = true;
pixel.foreground_color = Color::Blue;
std::cout << screen.ToString();
return EXIT_SUCCESS;
}

# dom

This module defines a hierarchical set of `ftxui::Element`. An element manages the layout and can be responsive to the terminal dimension changes. Note the following example where this module is used to create a simple layout with a number of operators:

Example:

// 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

List of elements

The list of all elements are included and can be accessed by including the corresponding header file:

#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)>;
enum BorderStyle {
LIGHT,
DASHED,
HEAVY,
DOUBLE,
ROUNDED,
EMPTY,
};
// Pipe elements into decorator togethers.
// For instance the next lines are equivalents:
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))
Element operator|(Element, Decorator);
Element& operator|=(Element&, Decorator);
Elements operator|(Elements, Decorator);
Decorator operator|(Decorator, Decorator);
// --- Widget ---
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&)>);
// -- Decorator ---
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);
// --- Layout is
// Horizontal, Vertical or stacked set of elements.
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.
// -- Flexibility ---
// Define how to share the remaining space when not all of it is used inside a
// container.
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.
// -- Size override;
enum WidthOrHeight { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(WidthOrHeight, Constraint, int value);
// --- Frame ---
// A frame is a scrollable area. The internal area is potentially larger than
// the external one. The internal area is scrolled in order to make visible the
// focused element.
Element frame(Element);
Element xframe(Element);
Element yframe(Element);
Element focus(Element);
Element select(Element e); // Deprecated - Alias for focus.
// --- Cursor ---
// Those are similar to `focus`, but also change the shape of the cursor.
Element focusCursorBlock(Element);
Element focusCursorBlockBlinking(Element);
Element focusCursorBar(Element);
Element focusCursorBarBlinking(Element);
Element focusCursorUnderline(Element);
Element focusCursorUnderlineBlinking(Element);
// --- Misc ---
Element vscroll_indicator(Element);
Element hscroll_indicator(Element);
Decorator reflect(Box& box);
// Before drawing the |element| clear the pixel below. This is useful in
// combinaison with dbox.
Element clear_under(Element element);
// --- Util --------------------------------------------------------------------
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
// Make container able to take any number of children as input.
#include "ftxui/dom/take_any_args.hpp"
// Include old definitions using wstring.
#include "ftxui/dom/deprecated.hpp"
#endif // FTXUI_DOM_ELEMENTS_HPP
box.hpp
canvas.hpp
color.hpp
direction.hpp
deprecated.hpp
flexbox_config.hpp
linear_gradient.hpp
ftxui::Dimension::Fit
Dimensions Fit(Element &, bool extend_beyond_screen=false)
Definition util.cpp:93
ftxui::bgcolor
Decorator bgcolor(Color)
Decorate using a background color.
Definition color.cpp:124
ftxui::window
Element window(Element title, Element content, BorderStyle border=ROUNDED)
Draw window with a title and a border around the element.
Definition border.cpp:507
ftxui::WidthOrHeight
WidthOrHeight
Definition elements.hpp:153
ftxui::HEIGHT
@ HEIGHT
Definition elements.hpp:153
ftxui::WIDTH
@ WIDTH
Definition elements.hpp:153
ftxui::borderDouble
Element borderDouble(Element)
Draw a double border around the element.
Definition border.cpp:405
ftxui::focusCursorBarBlinking
Element focusCursorBarBlinking(Element)
Same as focus, but set the cursor shape to be a blinking bar.
Definition frame.cpp:189
ftxui::xflex
Element xflex(Element)
Expand/Minimize if possible/needed on the X axis.
Definition flex.cpp:129
ftxui::gaugeDirection
Element gaugeDirection(float progress, Direction direction)
Draw a high definition progress bar progressing in specified direction.
Definition gauge.cpp:169
ftxui::focusPositionRelative
Decorator focusPositionRelative(float x, float y)
Used inside a frame, this force the view to be scrolled toward a a given position....
Definition focus.cpp:31
ftxui::separatorStyled
Element separatorStyled(BorderStyle)
Draw a vertical or horizontal separation in between two other elements.
Definition separator.cpp:172
ftxui::xflex_grow
Element xflex_grow(Element)
Expand if possible on the X axis.
Definition flex.cpp:147
ftxui::Decorator
std::function< Element(Element)> Decorator
Definition elements.hpp:24
ftxui::underlinedDouble
Element underlinedDouble(Element)
Apply a underlinedDouble to text.
Definition underlined_double.cpp:17
ftxui::clear_under
Element clear_under(Element element)
Before drawing |child|, clear the pixels below. This is useful in.
Definition clear_under.cpp:38
ftxui::borderDashed
Element borderDashed(Element)
Draw a dashed border around the element.
Definition border.cpp:300
ftxui::separatorEmpty
Element separatorEmpty()
Draw a vertical or horizontal separation in between two other elements, using the EMPTY style.
Definition separator.cpp:357
ftxui::vscroll_indicator
Element vscroll_indicator(Element)
Display a vertical scrollbar to the right. colors.
Definition scroll_indicator.cpp:21
ftxui::separatorVSelector
Element separatorVSelector(float up, float down, Color unselected_color, Color selected_color)
Draw an vertical bar, with the area in between up/downcolored differently.
Definition separator.cpp:512
ftxui::flexbox
Element flexbox(Elements, FlexboxConfig config=FlexboxConfig())
ftxui::nothing
Element nothing(Element element)
A decoration doing absolutely nothing.
Definition util.cpp:28
ftxui::size
Decorator size(WidthOrHeight, Constraint, int value)
Apply a constraint on the size of an element.
Definition size.cpp:89
ftxui::Direction
Direction
Definition direction.hpp:8
ftxui::flex
Element flex(Element)
Make a child element to expand proportionally to the space left in a container.
Definition flex.cpp:123
ftxui::paragraphAlignRight
Element paragraphAlignRight(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the right.
Definition paragraph.cpp:60
ftxui::Make
std::shared_ptr< T > Make(Args &&... args)
Definition component.hpp:26
ftxui::xframe
Element xframe(Element)
Same as frame, but only on the x-axis.
Definition frame.cpp:126
ftxui::gaugeRight
Element gaugeRight(float progress)
Draw a high definition progress bar progressing from left to right.
Definition gauge.cpp:191
ftxui::focusCursorUnderlineBlinking
Element focusCursorUnderlineBlinking(Element)
Same as focus, but set the cursor shape to be a blinking underline.
Definition frame.cpp:217
ftxui::bold
Element bold(Element)
Use a bold font, for elements with more emphasis.
Definition bold.cpp:33
ftxui::separatorLight
Element separatorLight()
Draw a vertical or horizontal separation in between two other elements, using the LIGHT style.
Definition separator.cpp:209
ftxui::spinner
Element spinner(int charset_index, size_t image_index)
Useful to represent the effect of time and/or events. This display an ASCII art "video".
Definition spinner.cpp:282
ftxui::borderRounded
Element borderRounded(Element)
Draw a rounded border around the element.
Definition border.cpp:440
ftxui::emptyElement
Element emptyElement()
Definition util.cpp:140
ftxui::selectionStyle
Decorator selectionStyle(std::function< void(Pixel &)> style)
Set the style of an element when selected.
Definition selection_style.cpp:86
ftxui::yflex
Element yflex(Element)
Expand/Minimize if possible/needed on the Y axis.
Definition flex.cpp:135
ftxui::flex_shrink
Element flex_shrink(Element)
Minimize if needed.
Definition flex.cpp:159
ftxui::hflow
Element hflow(Elements)
ftxui::focusCursorBar
Element focusCursorBar(Element)
Same as focus, but set the cursor shape to be a still block.
Definition frame.cpp:175
ftxui::separatorHSelector
Element separatorHSelector(float left, float right, Color unselected_color, Color selected_color)
Draw an horizontal bar, with the area in between left/right colored differently.
Definition separator.cpp:442
ftxui::focusCursorBlock
Element focusCursorBlock(Element)
Same as focus, but set the cursor shape to be a still block.
Definition frame.cpp:147
ftxui::hbox
Element hbox(Elements)
A container displaying elements horizontally one by one.
Definition hbox.cpp:94
ftxui::canvas
Element canvas(ConstRef< Canvas >)
Produce an element from a Canvas, or a reference to a Canvas.
Definition canvas.cpp:891
ftxui::underlined
Element underlined(Element)
Make the underlined element to be underlined.
Definition underlined.cpp:33
ftxui::center
Element center(Element)
Center an element horizontally and vertically.
Definition composite_decorator.cpp:31
ftxui::selectionForegroundColor
Decorator selectionForegroundColor(Color foreground)
Set the foreground color of an element when selected. Note that the style is applied on top of the ex...
Definition selection_style.cpp:69
ftxui::focusCursorUnderline
Element focusCursorUnderline(Element)
Same as focus, but set the cursor shape to be a still underline.
Definition frame.cpp:203
ftxui::operator|
Component operator|(Component component, ComponentDecorator decorator)
Definition util.cpp:12
ftxui::borderHeavy
Element borderHeavy(Element)
Draw a heavy border around the element.
Definition border.cpp:370
ftxui::inverted
Element inverted(Element)
Add a filter that will invert the foreground and the background colors.
Definition inverted.cpp:34
ftxui::paragraphAlignCenter
Element paragraphAlignCenter(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the center.
Definition paragraph.cpp:72
ftxui::selectionBackgroundColor
Decorator selectionBackgroundColor(Color foreground)
Set the background color of an element when selected. Note that the style is applied on top of the ex...
Definition selection_style.cpp:61
ftxui::gaugeUp
Element gaugeUp(float progress)
Draw a high definition progress bar progressing from bottom to top.
Definition gauge.cpp:242
ftxui::text
Element text(std::wstring text)
Display a piece of unicode text.
Definition text.cpp:160
ftxui::align_right
Element align_right(Element)
Align an element on the right side.
Definition composite_decorator.cpp:39
ftxui::focusPosition
Decorator focusPosition(int x, int y)
Used inside a frame, this force the view to be scrolled toward a a given position....
Definition focus.cpp:69
ftxui::Elements
std::vector< Element > Elements
Definition elements.hpp:23
ftxui::yframe
Element yframe(Element)
Same as frame, but only on the y-axis.
Definition frame.cpp:134
ftxui::yflex_grow
Element yflex_grow(Element)
Expand if possible on the Y axis.
Definition flex.cpp:153
ftxui::hscroll_indicator
Element hscroll_indicator(Element)
Display an horizontal scrollbar to the bottom. colors.
Definition scroll_indicator.cpp:76
ftxui::flex_grow
Element flex_grow(Element)
Expand if possible.
Definition flex.cpp:141
ftxui::separatorDashed
Element separatorDashed()
Draw a vertical or horizontal separation in between two other elements, using the DASHED style.
Definition separator.cpp:246
ftxui::notflex
Element notflex(Element)
Make the element not flexible.
Definition flex.cpp:177
ftxui::strikethrough
Element strikethrough(Element)
Apply a strikethrough to text.
Definition strikethrough.cpp:17
ftxui::italic
Element italic(Element)
Apply a underlinedDouble to text.
Definition italic.cpp:17
ftxui::dbox
Element dbox(Elements)
Stack several element on top of each other.
Definition dbox.cpp:108
ftxui::selectionColor
Decorator selectionColor(Color foreground)
Set the color of an element when selected.
Definition selection_style.cpp:78
ftxui::xflex_shrink
Element xflex_shrink(Element)
Minimize if needed on the X axis.
Definition flex.cpp:165
ftxui::gaugeLeft
Element gaugeLeft(float progress)
Draw a high definition progress bar progressing from right to left.
Definition gauge.cpp:213
ftxui::separatorCharacter
Element separatorCharacter(std::string)
Draw a vertical or horizontal separation in between two other elements.
Definition separator.cpp:395
ftxui::vflow
Element vflow(Elements)
ftxui::select
Element select(Element e)
Set the child to be the one focused among its siblings.
Definition frame.cpp:108
ftxui::vtext
Element vtext(std::wstring text)
Display a piece unicode text vertically.
Definition text.cpp:220
ftxui::borderLight
Element borderLight(Element)
Draw a light border around the element.
Definition border.cpp:335
ftxui::focus
Element focus(Element)
Set the child to be the one focused among its siblings.
Definition frame.cpp:101
ftxui::paragraphAlignLeft
Element paragraphAlignLeft(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the left.
Definition paragraph.cpp:49
ftxui::selectionStyleReset
Element selectionStyleReset(Element)
Reset the selection style of an element.
Definition selection_style.cpp:55
ftxui::borderWith
Decorator borderWith(const Pixel &)
Same as border but with a constant Pixel around the element.
Definition border.cpp:234
ftxui::reflect
Decorator reflect(Box &box)
Definition reflect.cpp:43
ftxui::GraphFunction
std::function< std::vector< int >(int, int)> GraphFunction
Definition elements.hpp:25
ftxui::borderStyled
Decorator borderStyled(BorderStyle)
Same as border but with different styles.
Definition border.cpp:243
ftxui::gridbox
Element gridbox(std::vector< Elements > lines)
A container displaying a grid of elements.
Definition gridbox.cpp:173
ftxui::separator
Element separator()
Draw a vertical or horizontal separation in between two other elements.
Definition separator.cpp:134
ftxui::filler
Element filler()
An element that will take expand proportionally to the space left in a container.
Definition flex.cpp:98
ftxui::paragraph
Elements paragraph(std::wstring text)
ftxui::dim
Element dim(Element)
Use a light font, for elements with less emphasis.
Definition dim.cpp:33
ftxui::automerge
Element automerge(Element child)
Enable character to be automatically merged with others nearby.
Definition automerge.cpp:17
ftxui::frame
Element frame(Element)
Allow an element to be displayed inside a 'virtual' area. It size can be larger than its container....
Definition frame.cpp:118
ftxui::hyperlink
Decorator hyperlink(std::string link)
Decorate using an hyperlink. The link will be opened when the user click on it. This is supported onl...
Definition hyperlink.cpp:70
ftxui::blink
Element blink(Element)
The text drawn alternates in between visible and hidden.
Definition blink.cpp:33
ftxui::vcenter
Element vcenter(Element)
Center an element vertically.
Definition composite_decorator.cpp:23
ftxui::separatorDouble
Element separatorDouble()
Draw a vertical or horizontal separation in between two other elements, using the DOUBLE style.
Definition separator.cpp:320
ftxui::focusCursorBlockBlinking
Element focusCursorBlockBlinking(Element)
Same as focus, but set the cursor shape to be a blinking block.
Definition frame.cpp:161
ftxui::operator|=
Component & operator|=(Component &component, ComponentDecorator decorator)
Definition util.cpp:22
ftxui::Constraint
Constraint
Definition elements.hpp:154
ftxui::LESS_THAN
@ LESS_THAN
Definition elements.hpp:154
ftxui::EQUAL
@ EQUAL
Definition elements.hpp:154
ftxui::GREATER_THAN
@ GREATER_THAN
Definition elements.hpp:154
ftxui::gauge
Element gauge(float progress)
Draw a high definition progress bar.
Definition gauge.cpp:293
ftxui::paragraphAlignJustify
Element paragraphAlignJustify(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned using a justified alignment....
Definition paragraph.cpp:85
ftxui::graph
Element graph(GraphFunction)
Draw a graph using a GraphFunction.
Definition graph.cpp:71
ftxui::border
Element border(Element)
Draw a border around the element.
Definition border.cpp:227
ftxui::separatorHeavy
Element separatorHeavy()
Draw a vertical or horizontal separation in between two other elements, using the HEAVY style.
Definition separator.cpp:283
ftxui::borderEmpty
Element borderEmpty(Element)
Draw an empty border around the element.
Definition border.cpp:475
ftxui::color
Decorator color(Color)
Decorate using a foreground color.
Definition color.cpp:110
ftxui::yflex_shrink
Element yflex_shrink(Element)
Minimize if needed on the Y axis.
Definition flex.cpp:171
ftxui::hcenter
Element hcenter(Element)
Center an element horizontally.
Definition composite_decorator.cpp:15
ftxui::vbox
Element vbox(Elements)
A container displaying elements vertically one by one.
Definition vbox.cpp:96
ftxui::BorderStyle
BorderStyle
Definition elements.hpp:27
ftxui::EMPTY
@ EMPTY
Definition elements.hpp:33
ftxui::DOUBLE
@ DOUBLE
Definition elements.hpp:31
ftxui::HEAVY
@ HEAVY
Definition elements.hpp:30
ftxui::ROUNDED
@ ROUNDED
Definition elements.hpp:32
ftxui::DASHED
@ DASHED
Definition elements.hpp:29
ftxui::LIGHT
@ LIGHT
Definition elements.hpp:28
ftxui::gaugeDown
Element gaugeDown(float progress)
Draw a high definition progress bar progressing from top to bottom.
Definition gauge.cpp:271
node.hpp
ref.hpp
terminal.hpp

## text

The most simple widget. It displays a text.

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

## vtext

Identical to `ftxui::text`, but displayed vertically.

Code:

vtext("HELLO");

Terminal output:

H
E
L
L
O

## paragraph

Similar to `ftxui::text`, but the individual word are wrapped along multiple lines, depending on the width of its container.

Sample Code:

paragraph("A very long text")

For a more detailed example refer to detailed example. Paragraph also includes a number of other variants as shown below:

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

Adds a border around an element.

Code:

border(text("The element"))

Terminal output:

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

You can achieve the same behavior by using the pipe operator.

Code:

text("The element") | border

Border also comes in a variety of styles as shown below:

Element border(Element);
Element borderLight(Element);
Element borderHeavy(Element);
Element borderDouble(Element);
Element borderRounded(Element);
Element borderEmpty(Element);
Decorator borderStyled(BorderStyle);
Decorator borderWith(Pixel);
ftxui::Pixel
A Unicode character and its associated style.
Definition pixel.hpp:15

## window

A `ftxui::window` is a `ftxui::border`, but with an additional header. To add a window around an element, wrap it and specify a string as the header. Code:

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

Terminal output:

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

## separator

Displays a vertical/horizontal line to visually split the content of a container in two.

Code:

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

Terminal output:

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

Separators come in a variety of flavors as shown below:

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);
ftxui::Color
A class representing terminal colors.
Definition color.hpp:20

## gauge

It constitutes a gauge. It can be used to represent a progress bar.

Code:

border(gauge(0.5))

Teminal output:

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

Gauges can be displayed in many orientations as shown below:

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

See:

Element graph(GraphFunction);

## Colors

Most terminal consoles can display colored text and colored backgrounds. FTXUI supports every color palette:

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

Color gallery:

### Palette16

On most terminals the following colors are supported:

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

### Palette256

On terminal supporting 256 colors.

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

### TrueColor

On terminal supporting trueColor, you can directly use the 24bit RGB color space:

Use the constructors below to specify the RGB or HSV values for your color:

There are two constructors:

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::Color::HSV
static Color HSV(uint8_t hue, uint8_t saturation, uint8_t value)
Build a Color from its HSV representation. https://en.wikipedia.org/wiki/HSL_and_HSV.
Definition color.cpp:207
ftxui::Color::RGB
static Color RGB(uint8_t red, uint8_t green, uint8_t blue)
Build a Color from its RGB representation. https://en.wikipedia.org/wiki/RGB_color_model.
Definition color.cpp:153

## LinearGradient

FTXUI supports linear gradient. Either on the foreground or the background.

Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);
ftxui::LinearGradient
A class representing the settings for linear-gradient color effect.
Definition linear_gradient.hpp:30

A `ftxui::LinearGradient` is defined by an angle in degree, and a list of color stops.

auto gradient = LinearGradient()
.Angle(45)
.AddStop(0.0, Color::Red)
.AddStop(0.5, Color::Green)
.AddStop(1.0, Color::Blue);
ftxui::LinearGradient::Angle
LinearGradient & Angle(float angle)
Set the angle of the gradient.
Definition linear_gradient.cpp:216

You can also use simplified constructors:

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

See demo.

## Style

In addition to colored text and colored backgrounds. Many terminals support text effects such as: `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

To use these effects, simply wrap your elements with your desired effect:

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

Alternatively, use the pipe operator to chain it on your element:

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

## Layout

Enables elements to be arranged in the following ways:

- Horizontally with `ftxui::hbox`
- Vertically with `ftxui::vbox`
- Inside a grid with `ftxui::gridbox`
- Wrapped along one direction using the `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.

Element can also become flexible using the the `ftxui::flex` decorator.

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 │
└────┘└───────────────────────────────┘└───────────────────────────────┘

## Table

Enables easy formatting of data into a neat table like visual form.

Code example:

## Canvas

See the API <ftxui/dom/canvas.hpp>

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

Drawing can be performed on a `ftxui::Canvas`, using braille, block, or simple characters:

Simple example:

Complex example:

# component

The `ftxui::component` module defines the logic that produces interactive components that respond to user events (keyboard, mouse, etc.).

A `ftxui::ScreenInteractive` defines a main loop that renders a component.

A `ftxui::Component` is a shared pointer to a `ftxui::ComponentBase`. The latter defines:

- `ftxui::ComponentBase::Render()`: How to render the interface.
- `ftxui::ComponentBase::OnEvent()`: How to react to events.
- `ftxui::ComponentBase::Add()`: Construct a parent/child relationship between two components. The tree of component is used to define how to navigate using the keyboard.

`ftxui::Element` are used to render a single frame.

`ftxui::Component` are used to render dynamic user interface, producing multiple frame, and updating its state on events.

Gallery of multiple components. (demo)

All predefined components are available in "ftxui/dom/component.hpp"

// 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/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)...);
}
// Pipe operator to decorate components.
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 */
component_base.hpp
component_options.hpp
ftxui::Container::Horizontal
Component Horizontal(Components children)
A list of components, drawn one by one horizontally and navigated horizontally using left/right arrow...
Definition container.cpp:360
ftxui::Container::Vertical
Component Vertical(Components children)
A list of components, drawn one by one vertically and navigated vertically using up/down arrow key or...
Definition container.cpp:317
ftxui::Container::Stacked
Component Stacked(Components children)
A list of components to be stacked on top of each other. Events are propagated to the first component...
Definition container.cpp:432
ftxui::Container::Tab
Component Tab(Components children, int *selector)
A list of components, where only one is drawn and interacted with at a time. The |selector| gives the...
Definition container.cpp:405
ftxui::Maybe
Component Maybe(Component, const bool *show)
Decorate a component |child|. It is shown only when |show| is true.
Definition maybe.cpp:74
ftxui::ResizableSplitTop
Component ResizableSplitTop(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Definition resizable_split.cpp:283
ftxui::Menu
Component Menu(MenuOption options)
A list of text. The focused element is selected.
Definition menu.cpp:512
ftxui::MenuEntry
Component MenuEntry(MenuEntryOption options)
A specific menu entry. They can be put into a Container::Vertical to form a menu.
Definition menu.cpp:614
ftxui::ElementDecorator
std::function< Element(Element)> ElementDecorator
Definition component.hpp:32
ftxui::Component
std::shared_ptr< ComponentBase > Component
Definition component_base.hpp:24
ftxui::Toggle
Component Toggle(ConstStringListRef entries, int *selected)
An horizontal list of elements. The user can navigate through them.
Definition menu.cpp:554
ftxui::Components
std::vector< Component > Components
Definition component_base.hpp:25
ftxui::Radiobox
Component Radiobox(RadioboxOption options)
A list of element, where only one can be selected.
Definition radiobox.cpp:204
ftxui::Button
Component Button(ButtonOption options)
Draw a button. Execute a function when clicked.
Definition button.cpp:176
ftxui::Modal
Component Modal(Component main, Component modal, const bool *show_modal)
Definition modal.cpp:18
ftxui::Renderer
Component Renderer(Component child, std::function< Element()>)
Return a new Component, similar to |child|, but using |render| as the Component::Render() event.
Definition renderer.cpp:61
ftxui::Hoverable
Component Hoverable(Component component, bool *hover)
Wrap a component. Gives the ability to know if it is hovered by the mouse.
Definition hoverable.cpp:43
ftxui::ResizableSplit
Component ResizableSplit(ResizableSplitOption options)
A split in between two components.
Definition resizable_split.cpp:186
ftxui::Window
Component Window(WindowOptions option)
A draggeable / resizeable window. To use multiple of them, they must be stacked using Container::Stac...
Definition window.cpp:312
ftxui::Input
Component Input(InputOption options={})
An input box for editing text.
Definition input.cpp:571
ftxui::ResizableSplitRight
Component ResizableSplitRight(Component main, Component back, int *main_size)
An horizontal split in between two components, configurable using the mouse.
Definition resizable_split.cpp:249
ftxui::Dropdown
Component Dropdown(ConstStringListRef entries, int *selected)
A dropdown menu.
Definition dropdown.cpp:22
ftxui::Slider
Component Slider(SliderOption< T > options)
A slider in any direction.
Definition slider.cpp:346
ftxui::ResizableSplitBottom
Component ResizableSplitBottom(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Definition resizable_split.cpp:317
ftxui::Checkbox
Component Checkbox(CheckboxOption options)
Draw checkable element.
Definition checkbox.cpp:108
ftxui::ResizableSplitLeft
Component ResizableSplitLeft(Component main, Component back, int *main_size)
An horizontal split in between two components, configurable using the mouse.
Definition resizable_split.cpp:215
ftxui::ComponentDecorator
std::function< Component(Component)> ComponentDecorator
Definition component.hpp:31
ftxui::Collapsible
Component Collapsible(ConstStringRef label, Component child, Ref< bool > show=false)
ftxui::CatchEvent
Component CatchEvent(Component child, std::function< bool(Event)>)
ftxui::ButtonOption::Simple
static ButtonOption Simple()
Create a ButtonOption, inverted when focused.
Definition component_options.cpp:177
ftxui::CheckboxOption::Simple
static CheckboxOption Simple()
Option for standard Checkbox.
Definition component_options.cpp:262

## Input

Example:

Produced by: `ftxui::Input()` from "ftxui/component/component.hpp"

### Filtered input

On can filter out the characters received by the input component, using `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::Event
Represent an event. It can be key press event, a terminal resize, or more ...
Definition event.hpp:27
ftxui::Event::character
std::string character() const
Definition event.hpp:105

## Menu

Defines a menu object. It contains a list of entries, one of them is selected.

Example:

Produced by: `ftxui::Menu()` from "ftxui/component/component.hpp"

## Toggle

A special kind of menu. The entries are displayed horizontally.

Example:

Produced by: `ftxui::Toggle()` from "ftxui/component/component.hpp"

## CheckBox

This component defines a checkbox. It is a single entry that can be turned on/off.

Example:

Produced by: `ftxui::Checkbox()` from "ftxui/component/component.hpp"

## RadioBox

A radiobutton component. This is a list of entries, where one can be turned on.

Example:

Produced by: `ftxui::Radiobox()` from "ftxui/component/component.hpp"

## Dropdown

A drop down menu is a component that when checked display a list of element for the user to select one.

Example:

Produced by: `ftxui::Dropdown()` from "ftxui/component/component.hpp"

## Slider

Represents a slider object that consists of a range with binned intermediate intervals. It can be created by `ftxui::Slider()`.

Example:

Produced by: `ftxui::Slider()` from "ftxui/component/component.hpp"

## Renderer

Produced by: `ftxui::Renderer()` from ftxui/component/component.hpp. This component decorate another one by using a different function to render an interface.

Example:

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

`ftxui::Renderer` also supports the component decorator pattern:

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

As a short hand, you can also compose a component with an element decorator:

auto component = [...]
component = component | border | bold;

## CatchEvent

Produced by: `ftxui::CatchEvent()` from ftxui/component/component.hpp. This component decorate others, catching events before the underlying component.

Examples:

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

The `ftxui::CatchEvent` can also be used as a decorator:

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

## Collapsible

Useful for visual elements whose visibility can be toggle on/off by the user. Essentially, this the combination of the `ftxui::Checkbox()` and `ftxui::Maybe()` components.

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

## Maybe

Produced by: `ftxui::Maybe()` from ftxui/component/component.hpp. This component can be utilized to show/hide any other component via a boolean or a predicate.

Example with a boolean:

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

Example with a predicate:

auto component = Renderer([]{ return "Hello World!"; });
auto maybe_component = Maybe(component, [&] { return time > 10; })

As usual, `ftxui::Maybe` can also be used as a decorator:

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

## Container

### Horizontal

Produced by: `ftxui::Container::Horizontal()` from "ftxui/component/component.hpp". It displays a list of components horizontally and handle keyboard/mouse navigation.

### Vertical

Produced by: `ftxui::Container::Vertical()` from "ftxui/component/component.hpp". It displays a list of components vertically and handles keyboard/mouse navigation.

### Tab

Produced by: `ftxui::Container::Tab()` from "ftxui/component/component.hpp". It take a list of component and display only one of them. This is useful for implementing a tab bar.

Vertical:

Horizontal:

## ResizableSplit

It defines a horizontal or vertical separation between two children components. The position of the split is variable and controllable using the mouse. There are four possible splits:

- `ftxui::ResizableSplitLeft()`
- `ftxui::ResizableSplitRight()`
- `ftxui::ResizableSplitTop()`
- `ftxui::ResizableSplitBottom()` from "ftxui/component/component.hpp"

Example:

## Force a frame redraw.

Typically, `ftxui::ScreenInteractive::Loop()` is responsible for drawing a new frame whenever a new group of events (e.g keyboard, mouse, window resize, etc.) has been processed. However, you might want to react to arbitrary events that are unknown to FTXUI. To accomplish this, you must post events using `ftxui::ScreenInteractive::PostEvent` (this is thread safe) via a thread. You will have to post the event `ftxui::Event::Custom`.

Example:

screen->PostEvent(Event::Custom);