FTXUI

Table of Contents

• Introduction
• Build
  • Using CMake
• List of modules.
• screen
• dom
  • text
  • border
  • window
  • separator
  • gauge
  • graph
  • Colors
    • Palette16
    • Palette256
    • TrueColor
  • Style
  • Layout
• component
  • Input
  • Menu
  • Toggle.
  • CheckBox
  • RadioBox
  • Renderer
  • CatchEvent
  • Container::Horizontal
  • Container::Vertial
  • Container::Tab
  • ResizableSplit::{Left, Right, Top, Bottom}
  • Force a frame redraw.

Introduction

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

Short example

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

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

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>
 
#include "ftxui/dom/node.hpp"
#include "ftxui/screen/box.hpp"
#include "ftxui/screen/color.hpp"
#include "ftxui/screen/screen.hpp"
#include "ftxui/screen/terminal.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, 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);
Elements operator|(Elements, Decorator);
Decorator operator|(Decorator, Decorator);
 
// --- Widget ---
Element text(std::string text);
Element vtext(std::string text);
Element separator(void);
Element separatorLight();
Element separatorHeavy();
Element separatorDouble();
Element separatorEmpty();
Element separatorStyled(BorderStyle);
Element separator(Pixel);
Element separatorCharacter(std::string);
Element gauge(float ratio);
Element border(Element);
Element borderLight(Element);
Element borderHeavy(Element);
Element borderDouble(Element);
Element borderRounded(Element);
Element borderEmpty(Element);
Decorator borderStyled(BorderStyle);
Decorator borderWith(Pixel);
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.
Element graph(GraphFunction);
Element emptyElement();
 
// -- Decorator ---
Element bold(Element);
Element dim(Element);
Element inverted(Element);
Element underlined(Element);
Element blink(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Element color(Color, Element);
Element bgcolor(Color, Element);
 
// --- Layout is
// Horizontal, Vertical or stacked set of elements.
Element hbox(Elements);
Element vbox(Elements);
Element dbox(Elements);
Element gridbox(std::vector<Elements> lines);
Element hflow(Elements);
 
// -- 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 Direction { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(Direction, Constraint, int value);
 
// --
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.
Element frame(Element);
Element xframe(Element);
Element yframe(Element);
Element focus(Element);
Element select(Element);
 
Element vscroll_indicator(Element);
 
// --- Util --------------------------------------------------------------------
Element hcenter(Element);
Element vcenter(Element);
Element center(Element);
Element align_right(Element);
Element nothing(Element element);
 
// Before drawing the |element| clear the pixel below. This is useful in
// combinaison with dbox.
Element clear_under(Element element);
 
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.
#include "ftxui/dom/deprecated.hpp"
#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.

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.

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

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

gauge

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

border(gauge(0.5))

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

graph

Colors

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

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

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

Style

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

Element bold(Element);
Element dim(Element);
Element inverted(Element);
Element underlined(Element);
Element blink(Element);
Decorator color(Color);
Decorator bgcolor(Color);

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

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

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

• ftxui::ComponentBase::Render(): How to render the interface.
• ftxui::ComponentBase::OnEvent(): How to react to events.
• ftxui::ComponentBase::Add(): Give a parent/child relation ship in between two component. This defines a tree a components, which help properly define how keyboard navigation works.

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);
Component Vertical(Components children, int* selector);
Component Horizontal(Components children);
Component Horizontal(Components children, int* selector);
Component Tab(Components children, int* selector);
 
}  // namespace Container
 
}  // namespace ftxui
 
// Include component using the old deprecated wstring.
#include "ftxui/component/deprecated.hpp"
 
#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.

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:

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

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.