FTXUI  0.11.376
C++ functional terminal UI.
FTXUI Documentation

Introduction

Welcome to the FTXUI documentation. Here, you will find the detail of every functions and classes.

Short example

main.cpp

#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;
}
static Screen Create(Dimensions dimension)
Create a screen with the given dimension.
Definition: screen.cpp:344
Dimensions Fit(Element &)
Definition: util.cpp:71
Dimensions Full()
Definition: screen.cpp:332
Element flex(Element)
Make a child element to expand proportionnally to the space left in a container.
Definition: flex.cpp:119
std::shared_ptr< Node > Element
Definition: elements.hpp:15
Element hbox(Elements)
A container displaying elements horizontally one by one.
Definition: hbox.cpp:76
Element text(std::wstring text)
Display a piece of unicode text.
Definition: text.cpp:106
void Render(Screen &screen, const Element &node)
Display an element on a ftxui::Screen.
Definition: node.cpp:34
Element border(Element)
Draw a border around the element.
Definition: border.cpp:150

output

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

Build

Using CMake

CMakeLists.txt

cmake_minimum_required (VERSION 3.11)
# --- Fetch FTXUI --------------------------------------------------------------
include(FetchContent)
set(FETCHCONTENT_UPDATES_DISCONNECTED TRUE)
FetchContent_Declare(ftxui
GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
# Specify a GIT_TAG here.
)
FetchContent_GetProperties(ftxui)
if(NOT ftxui_POPULATED)
FetchContent_Populate(ftxui)
add_subdirectory(${ftxui_SOURCE_DIR} ${ftxui_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
# ------------------------------------------------------------------------------
project(ftxui-starter
LANGUAGES CXX
VERSION 1.0.0
)
add_executable(ftxui-starter src/main.cpp)
target_include_directories(ftxui-starter PRIVATE src)
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 split into 3 modules:

  1. ftxui/screen defines a ftxui::Screen, this is 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 part is only needed if you need to respond to the User input. It defines a set of ftxui::Component. The use can navigates using the arrow keys and interact with widgets like checkbox/inputbox/... You can make you own components.

screen

It defines a ftxui::Screen. This is a grid of ftxui::Pixel. A Pixel represent a Unicode character and its associated style (bold, colors, etc...). The screen can be printed as a string using ftxui::Screen::ToString().

#include <iostream>
int main(void) {
using namespace ftxui;
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;
}
Dimensions Fixed(int)
Definition: screen.cpp:325

dom

This module defines a hierarchical set of Element. An element manages layout and can be responsive to the terminal dimensions.

Example:

// Define the document
Element document = vbox({
text("The window") | bold | color(Color::Blue),
gauge(0.5)
text("The footer")
});
// Add a border.
document = border(document);
Element bold(Element)
Use a bold font, for elements with more emphasis.
Definition: bold.cpp:28
Element gauge(float ratio)
Draw a high definition progress bar.
Definition: gauge.cpp:75
Decorator color(Color)
Decorate using a foreground color.
Definition: color.cpp:86
Element vbox(Elements)
A container displaying elements vertically one by one.
Definition: vbox.cpp:77

List of elements

You only need one header: ftxui/dom/elements.hpp

#ifndef FTXUI_DOM_ELEMENTS_HPP
#define FTXUI_DOM_ELEMENTS_HPP
#include <functional>
#include <memory>
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)>;
// Pipe elements into decorator togethers.
// For instance the next lines are equivalents:
// -> text("ftxui") | bold | underlined
// -> underlined(bold(text("FTXUI")))
// --- Widget ---
Element text(std::string text);
Element vtext(std::string text);
Element gauge(float ratio);
Element window(Element title, Element content);
Element spinner(int charset_index, size_t image_index);
Elements paragraph(std::string text); // Use inside hflow(). Split by space.
// -- Decorator ---
// --- Layout is
// Horizontal, Vertical or stacked set of elements.
Element gridbox(std::vector<Elements> lines);
// -- 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;
// --
Decorator reflect(Box& box);
// --- 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.
// --- Util --------------------------------------------------------------------
// Before drawing the |element| clear the pixel below. This is useful in
// combinaison with dbox.
namespace Dimension {
Dimensions Fit(Element&);
} // 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.
#endif /* end of include guard: 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.
Decorator bgcolor(Color)
Decorate using a background color.
Definition: color.cpp:100
Element borderDouble(Element)
Draw a double border around the element.
Definition: border.cpp:270
Element xflex(Element)
Expand/Minimize if possible/needed on the X axis.
Definition: flex.cpp:125
Element separatorStyled(BorderStyle)
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:151
Element xflex_grow(Element)
Expand if possible on the X axis.
Definition: flex.cpp:143
std::function< Element(Element)> Decorator
Definition: elements.hpp:17
Element separatorEmpty()
Draw a vertical or horizontal separation in between two other elements, using the EMPTY style.
Definition: separator.cpp:295
Element vscroll_indicator(Element)
Add a filter that will invert the foreground and the background colors.
Element nothing(Element element)
A decoration doing absolutely nothing.
Definition: util.cpp:25
Direction
Definition: elements.hpp:94
@ HEIGHT
Definition: elements.hpp:94
@ WIDTH
Definition: elements.hpp:94
Element clear_under(Element element)
Before drawing |child|, clear the pixels below. This is useful in.
Definition: clear_under.cpp:32
Element xframe(Element)
Definition: frame.cpp:142
Element hflow(Elements)
A container displaying elements horizontally one by one.
Definition: hflow.cpp:75
Decorator borderWith(Pixel)
Same as border but with a constant Pixel around the element.
Definition: border.cpp:157
Element separatorLight()
Draw a vertical or horizontal separation in between two other elements, using the LIGHT style.
Definition: separator.cpp:187
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:255
Elements paragraph(std::wstring text)
Return a vector of ftxui::text for every word of the string. This is useful combined with ftxui::hflo...
Definition: paragraph.cpp:14
Element borderRounded(Element)
Draw a rounded border around the element.
Definition: border.cpp:304
Element emptyElement()
Definition: util.cpp:80
Element yflex(Element)
Expand/Minimize if possible/needed on the Y axis.
Definition: flex.cpp:131
Element window(Element title, Element content)
Draw window with a title and a border around the element.
Definition: border.cpp:363
Element flex_shrink(Element)
Minimize if needed.
Definition: flex.cpp:155
Element focus(Element)
Definition: frame.cpp:79
Element underlined(Element)
Make the underlined element to be underlined.
Definition: underlined.cpp:28
Element center(Element)
Center an element horizontally and vertically.
Element borderHeavy(Element)
Draw a heavy border around the element.
Definition: border.cpp:236
Element inverted(Element)
Add a filter that will invert the foreground and the background colors.
Definition: inverted.cpp:29
Element align_right(Element)
Align an element on the right side.
std::vector< Element > Elements
Definition: elements.hpp:16
Element operator|(Element, Decorator)
From an element, apply a decorator.
Definition: util.cpp:64
Element yflex_grow(Element)
Expand if possible on the Y axis.
Definition: flex.cpp:149
Element flex_grow(Element)
Expand if possible.
Definition: flex.cpp:137
Element yframe(Element)
Definition: frame.cpp:146
Element notflex(Element)
Make the element not flexible.
Definition: flex.cpp:173
Element dbox(Elements)
Stack several element on top of each other.
Definition: dbox.cpp:50
Element xflex_shrink(Element)
Minimize if needed on the X axis.
Definition: flex.cpp:161
Element separatorCharacter(std::string)
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:332
Element vtext(std::wstring text)
Display a piece unicode text vertically.
Definition: text.cpp:166
Element borderLight(Element)
Draw a light border around the element.
Definition: border.cpp:202
Decorator reflect(Box &box)
Definition: reflect.cpp:39
std::function< std::vector< int >(int, int)> GraphFunction
Definition: elements.hpp:18
Decorator borderStyled(BorderStyle)
Same as border but with different styles.
Definition: border.cpp:166
Element gridbox(std::vector< Elements > lines)
A container displaying a grid of elements.
Definition: gridbox.cpp:154
Element separator(void)
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:114
Element filler()
An element that will take expand proportionnally to the space left in a container.
Definition: flex.cpp:94
Element dim(Element)
Use a light font, for elements with less emphasis.
Definition: dim.cpp:28
Element frame(Element)
Allow an element to be displayed inside a 'virtual' area. It size can be larger than its container....
Definition: frame.cpp:138
Element blink(Element)
The text drawn alternates in between visible and hidden.
Definition: blink.cpp:28
Element vcenter(Element)
Center an element vertically.
Decorator size(Direction, Constraint, int value)
Apply a constraint on the size of an element.
Definition: size.cpp:86
Element separatorDouble()
Draw a vertical or horizontal separation in between two other elements, using the DOUBLE style.
Definition: separator.cpp:259
Constraint
Definition: elements.hpp:95
@ LESS_THAN
Definition: elements.hpp:95
@ EQUAL
Definition: elements.hpp:95
@ GREATER_THAN
Definition: elements.hpp:95
Element graph(GraphFunction)
Draw a graph using a GraphFunction.
Definition: graph.cpp:59
Element separatorHeavy()
Draw a vertical or horizontal separation in between two other elements, using the HEAVY style.
Definition: separator.cpp:223
Element select(Element)
Definition: frame.cpp:38
Element borderEmpty(Element)
Draw an empty border around the element.
Definition: border.cpp:338
Element yflex_shrink(Element)
Minimize if needed on the Y axis.
Definition: flex.cpp:167
Element hcenter(Element)
Center an element horizontally.
BorderStyle
Definition: elements.hpp:20
@ EMPTY
Definition: elements.hpp:20
@ DOUBLE
Definition: elements.hpp:20
@ HEAVY
Definition: elements.hpp:20
@ ROUNDED
Definition: elements.hpp:20
@ LIGHT
Definition: elements.hpp:20

text

The most simple widget. It displays a text.

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

border

Add a border around an element

border(text("The element"))
┌───────────┐
│The element│
└───────────┘

window

A ftxui::window is a ftxui::border, but with some text on top of the border. Add a border around an element

window("The window", text("The element"))
┌The window─┐
│The element│
└───────────┘

separator

Display a vertical or horizontal line to visually split the content of a container in two.

hbox({
text("Left"),
text("Right")
})
)
┌────┬─────┐
│left│right│
└────┴─────┘

gauge

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

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

graph

Colors

A terminal console can usually display colored text and colored background.

Palette16

On most terminal the following colors are supported:

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

Example:

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 chose the 24bit RGB 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);
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:124
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:112

Style

A terminal console can usually display colored text and colored background. The text can also have different effects: bold, dim, underlined, inverted, blink.

Example:

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

Tips: The pipe operator can be used to chain Decorator:

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

Layout

These layout are similar to the HTML flexbox:

  • vbox (Vertical-box)
  • hbox (Horizontal-box)
  • dbox (Z-axis-box) They are used to compose all the elements together. Each children are put side by side. If the container is flexible, the extra space available will be shared among the remaining flexible children.

flex(element) can be used to make a non-flexible element flexible. filler() is a flexible empty element. You can use it align children on one side of the container.

An horizontal flow layout is implemented by:

  • hflow (Horizontal flow)

Examples

text("left") | border ,
text("middle") | border | flex,
text("right") | border,
});
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
│left││middle ││right│
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
text("left") | border ,
text("middle") | border | flex,
text("right") | border | flex,
});
┌────┐┌───────────────────────────────────┐┌───────────────────────────────────┐
│left││middle ││right │
└────┘└───────────────────────────────────┘└───────────────────────────────────┘

component

The ftxui/component directory defines the logic to get produce interactive component responding to user's events (keyboard, mouse, etc...)

A ftxui::ScreenInteractive defines a main loop to render a component.

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

Predefined components are available in ftxui/dom/component.hpp:

#ifndef FTXUI_COMPONENT_HPP
#define FTXUI_COMPONENT_HPP
#include <functional> // for function
#include <memory> // for make_shared, shared_ptr
#include <string> // for wstring
#include <vector> // for vector
#include "ftxui/component/component_base.hpp" // for Component, Components
#include "ftxui/component/component_options.hpp" // for ButtonOption, CheckboxOption, InputOption, MenuOption, RadioboxOption, ToggleOption
#include "ftxui/dom/elements.hpp" // for Element
#include "ftxui/util/ref.hpp" // for Ref, ConstStringRef, ConstStringListRef, StringRef
namespace ftxui {
struct ButtonOption;
struct CheckboxOption;
struct Event;
struct InputOption;
struct MenuOption;
struct RadioboxOption;
struct ToggleOption;
struct MenuEntryOption;
template <class T, class... Args>
std::shared_ptr<T> Make(Args&&... args) {
return std::make_shared<T>(args...);
}
Component Button(ConstStringRef label,
std::function<void()> on_click,
Ref<ButtonOption> = {});
Component Checkbox(ConstStringRef label,
bool* checked,
Ref<CheckboxOption> option = {});
Component Input(StringRef content,
ConstStringRef placeholder,
Ref<InputOption> option = {});
Component Menu(ConstStringListRef entries,
int* selected_,
Ref<MenuOption> = {});
Component MenuEntry(ConstStringRef label, Ref<MenuEntryOption> = {});
Component Dropdown(ConstStringListRef entries, int* selected);
Component Radiobox(ConstStringListRef entries,
int* selected_,
Ref<RadioboxOption> option = {});
Component Toggle(ConstStringListRef entries,
int* selected,
Ref<ToggleOption> option = {});
template <class T> // T = {int, float, long}
Component Slider(ConstStringRef label, T* value, T min, T max, T increment);
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 */)>);
Component CatchEvent(Component child, std::function<bool(Event)>);
Component Maybe(Component, bool* show);
namespace Container {
Component Vertical(Components children, int* selector);
Component Horizontal(Components children, int* selector);
Component Tab(Components children, int* selector);
} // namespace Container
} // namespace ftxui
// Include component using the old deprecated wstring.
#endif /* end of include guard: FTXUI_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.
Component Horizontal(Components children)
A list of components, drawn one by one horizontally and navigated horizontally using left/right arrow...
Definition: container.cpp:259
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:216
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:304
Component Checkbox(ConstStringRef label, bool *checked, Ref< CheckboxOption > option={})
Draw checkable element.
Definition: checkbox.cpp:117
Component Radiobox(ConstStringListRef entries, int *selected_, Ref< RadioboxOption > option={})
A list of element, where only one can be selected.
Definition: radiobox.cpp:198
Component Toggle(ConstStringListRef entries, int *selected, Ref< ToggleOption > option={})
An horizontal list of elements. The user can navigate through them.
Definition: toggle.cpp:126
Component ResizableSplitTop(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Component Input(StringRef content, ConstStringRef placeholder, Ref< InputOption > option={})
An input box for editing text.
Definition: input.cpp:241
std::shared_ptr< ComponentBase > Component
std::vector< Component > Components
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:59
std::shared_ptr< T > Make(Args &&... args)
Definition: component.hpp:25
Component Button(ConstStringRef label, std::function< void()> on_click, Ref< ButtonOption >={})
Draw a button. Execute a function when clicked.
Definition: button.cpp:90
Component Menu(ConstStringListRef entries, int *selected_, Ref< MenuOption >={})
A list of text. The focused element is selected.
Definition: menu.cpp:181
Component ResizableSplitRight(Component main, Component back, int *main_size)
An horizontal split in between two components, configurable using the mouse.
Component CatchEvent(Component child, std::function< bool(Event)>)
Component Dropdown(ConstStringListRef entries, int *selected)
Definition: dropdown.cpp:13
Component MenuEntry(ConstStringRef label, Ref< MenuEntryOption >={})
Definition: menu.cpp:187
Component Maybe(Component, bool *show)
Definition: maybe.cpp:12
Component ResizableSplitBottom(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Component Slider(ConstStringRef label, T *value, T min, T max, T increment)
An horizontal slider.
Definition: slider.cpp:123
Component ResizableSplitLeft(Component main, Component back, int *main_size)
An horizontal split in between two components, configurable using the mouse.

Element are stateless object. On the other side, components are used when an internal state is needed. Components are used to interact with the user with its keyboard. They handle keyboard navigation, including component focus.

Input

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

Menu

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

Toggle.

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

CheckBox

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

RadioBox

Produced by: ftxui::Radiobox() 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.

CatchEvent

Produced by: ftxui::CatchEvent() from "ftxui/component/component.hpp". This component decorate another one and catch the events before the underlying component.

Container::Horizontal

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

Container::Vertial

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

Container::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.

ResizableSplit::{Left, Right, Top, Bottom}

Produced by:

It defines an horizontal or vertical separation in between two children component. The position of the split is variable and controllable using the mouse.

Force a frame redraw.

Whenever a new group of events have been processed: keyboard, mouse, window resize, etc..., the ftxui::ScreenInteractive::Loop() is responsible for drawing a new frame.

You might want to react to arbitrary events that are unknown to FTXUI. This can be achieve by posting events via ftxui::ScreenInteractive::PostEvent, via a thread. You can post the eventftxui::Event::Custom.

screen->PostEvent(Event::Custom);

ftxui::ScreenInteractive::PostEvent is thread safe.