FTXUI  4.0.0
C++ functional terminal UI.
FTXUI Documentation

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 <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:409
Dimensions Fit(Element &)
Definition: util.cpp:92
Dimensions Full()
Definition: screen.cpp:397
Element flex(Element)
Make a child element to expand proportionnally to the space left in a container.
Definition: flex.cpp:120
std::shared_ptr< Node > Element
Definition: elements.hpp:20
Element hbox(Elements)
A container displaying elements horizontally one by one.
Definition: hbox.cpp:77
Element text(std::wstring text)
Display a piece of unicode text.
Definition: text.cpp:114
void Render(Screen &screen, const Element &element)
Display an element on a ftxui::Screen.
Definition: node.cpp:44
Element border(Element)
Draw a border around the element.
Definition: border.cpp:222

output

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

Build

Using CMake

This is an example configuration for your CMakeLists.txt

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
# Important: Specify a GIT_TAG XXXXX 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.
)

Subsequently, you build the project in the standard fashion as follows:

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, colors, etc.). The screen can be printed as a string using ftxui::Screen::ToString(). The following example highlights this process:

#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:390

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
Element bold(Element)
Use a bold font, for elements with more emphasis.
Definition: bold.cpp:28
Element gauge(float progress)
Draw a high definition progress bar.
Definition: gauge.cpp:287
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:78

List of elements

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

#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);
float right,
Color unselected_color,
Color selected_color);
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);
Decorator borderWith(const Pixel&);
Element window(Element title, Element content);
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 canvas(ConstRef<Canvas>);
Element canvas(int width, int height, std::function<void(Canvas&)>);
Element canvas(std::function<void(Canvas&)>);
// -- Decorator ---
Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);
Element color(const LinearGradient&, Element);
Element bgcolor(const LinearGradient&, Element);
Decorator focusPosition(int x, int y);
Decorator focusPositionRelative(float x, float y);
Decorator hyperlink(std::string link);
Element hyperlink(std::string link, Element child);
// --- Layout is
// Horizontal, Vertical or stacked set of 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;
// --- 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.
// --- Cursor ---
// Those are similar to `focus`, but also change the shape of the cursor.
// --- Misc ---
Decorator reflect(Box& box);
// Before drawing the |element| clear the pixel below. This is useful in
// combinaison with dbox.
// --- Util --------------------------------------------------------------------
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 // 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 vflow(Elements)
WidthOrHeight
Definition: elements.hpp:145
@ HEIGHT
Definition: elements.hpp:145
@ WIDTH
Definition: elements.hpp:145
Element borderDouble(Element)
Draw a double border around the element.
Definition: border.cpp:400
Element xflex(Element)
Expand/Minimize if possible/needed on the X axis.
Definition: flex.cpp:126
Element gaugeDirection(float progress, Direction direction)
Draw a high definition progress bar progressing in specified direction.
Definition: gauge.cpp:163
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:28
Element separatorStyled(BorderStyle)
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:168
Element xflex_grow(Element)
Expand if possible on the X axis.
Definition: flex.cpp:144
std::function< Element(Element)> Decorator
Definition: elements.hpp:22
Element underlinedDouble(Element)
Apply a underlinedDouble to text.
Element clear_under(Element element)
Before drawing |child|, clear the pixels below. This is useful in.
Definition: clear_under.cpp:32
Element borderDashed(Element)
Draw a light border around the element.
Definition: border.cpp:295
Element separatorEmpty()
Draw a vertical or horizontal separation in between two other elements, using the EMPTY style.
Definition: separator.cpp:353
Element vscroll_indicator(Element)
Add a filter that will invert the foreground and the background colors.
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:508
Element nothing(Element element)
A decoration doing absolutely nothing.
Definition: util.cpp:27
Decorator size(WidthOrHeight, Constraint, int value)
Apply a constraint on the size of an element.
Definition: size.cpp:85
Direction
Definition: direction.hpp:5
Element xframe(Element)
Definition: frame.cpp:146
Element paragraphAlignRight(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the right.
Definition: paragraph.cpp:42
Element gaugeRight(float progress)
Draw a high definition progress bar progressing from left to right.
Definition: gauge.cpp:185
Element separatorLight()
Draw a vertical or horizontal separation in between two other elements, using the LIGHT style.
Definition: separator.cpp:205
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:280
Element borderRounded(Element)
Draw a rounded border around the element.
Definition: border.cpp:435
Element emptyElement()
Definition: util.cpp:132
Element yflex(Element)
Expand/Minimize if possible/needed on the Y axis.
Definition: flex.cpp:132
Element window(Element title, Element content)
Draw window with a title and a border around the element.
Definition: border.cpp:495
Element flex_shrink(Element)
Minimize if needed.
Definition: flex.cpp:156
Element focusCursorBlock(Element)
Definition: frame.cpp:171
Element focusCursorUnderlineBlinking(Element)
Definition: frame.cpp:191
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:438
Element focus(Element)
Definition: frame.cpp:83
Element focusCursorBar(Element)
Definition: frame.cpp:179
Element canvas(ConstRef< Canvas >)
Produce an element from a Canvas, or a reference to a Canvas.
Definition: canvas.cpp:848
Element underlined(Element)
Make the underlined element to be underlined.
Definition: underlined.cpp:28
Element center(Element)
Center an element horizontally and vertically.
Component operator|(Component component, ComponentDecorator decorator)
Definition: util.cpp:9
Element borderHeavy(Element)
Draw a heavy border around the element.
Definition: border.cpp:365
Element inverted(Element)
Add a filter that will invert the foreground and the background colors.
Definition: inverted.cpp:29
Elements paragraph(std::wstring text)
Element paragraphAlignCenter(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the center.
Definition: paragraph.cpp:52
Element gaugeUp(float progress)
Draw a high definition progress bar progressing from bottom to top.
Definition: gauge.cpp:236
Element focusCursorBlockBlinking(Element)
Definition: frame.cpp:175
Element align_right(Element)
Align an element on the right side.
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:67
std::vector< Element > Elements
Definition: elements.hpp:21
Element yflex_grow(Element)
Expand if possible on the Y axis.
Definition: flex.cpp:150
Element flex_grow(Element)
Expand if possible.
Definition: flex.cpp:138
Element separatorDashed()
Draw a vertical or horizontal separation in between two other elements, using the DASHED style.
Definition: separator.cpp:242
Element yframe(Element)
Definition: frame.cpp:150
Element notflex(Element)
Make the element not flexible.
Definition: flex.cpp:174
Element strikethrough(Element)
Apply a strikethrough to text.
Element dbox(Elements)
Stack several element on top of each other.
Definition: dbox.cpp:52
Element xflex_shrink(Element)
Minimize if needed on the X axis.
Definition: flex.cpp:162
Element gaugeLeft(float progress)
Draw a high definition progress bar progressing from right to left.
Definition: gauge.cpp:207
Element separatorCharacter(std::string)
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:391
Element vtext(std::wstring text)
Display a piece unicode text vertically.
Definition: text.cpp:174
Element borderLight(Element)
Draw a dashed border around the element.
Definition: border.cpp:330
Element paragraphAlignLeft(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned on the left.
Definition: paragraph.cpp:33
Decorator borderWith(const Pixel &)
Same as border but with a constant Pixel around the element.
Definition: border.cpp:229
Decorator reflect(Box &box)
Definition: reflect.cpp:39
std::function< std::vector< int >(int, int)> GraphFunction
Definition: elements.hpp:23
Element flexbox(Elements, FlexboxConfig config=FlexboxConfig())
Decorator borderStyled(BorderStyle)
Same as border but with different styles.
Definition: border.cpp:238
Element gridbox(std::vector< Elements > lines)
A container displaying a grid of elements.
Definition: gridbox.cpp:180
Element separator()
Draw a vertical or horizontal separation in between two other elements.
Definition: separator.cpp:130
Element filler()
An element that will take expand proportionnally to the space left in a container.
Definition: flex.cpp:95
Element focusCursorUnderline(Element)
Definition: frame.cpp:187
Element dim(Element)
Use a light font, for elements with less emphasis.
Definition: dim.cpp:28
Element automerge(Element child)
Enable character to be automatically merged with others nearby.
Definition: automerge.cpp:14
Element frame(Element)
Allow an element to be displayed inside a 'virtual' area. It size can be larger than its container....
Definition: frame.cpp:142
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:64
Element blink(Element)
The text drawn alternates in between visible and hidden.
Definition: blink.cpp:28
Element vcenter(Element)
Center an element vertically.
Element separatorDouble()
Draw a vertical or horizontal separation in between two other elements, using the DOUBLE style.
Definition: separator.cpp:316
Element hflow(Elements)
Component & operator|=(Component &component, ComponentDecorator decorator)
Definition: util.cpp:19
Constraint
Definition: elements.hpp:146
@ LESS_THAN
Definition: elements.hpp:146
@ EQUAL
Definition: elements.hpp:146
@ GREATER_THAN
Definition: elements.hpp:146
Element paragraphAlignJustify(const std::string &text)
Return an element drawing the paragraph on multiple lines, aligned using a justified alignment....
Definition: paragraph.cpp:63
Element graph(GraphFunction)
Draw a graph using a GraphFunction.
Definition: graph.cpp:65
Element separatorHeavy()
Draw a vertical or horizontal separation in between two other elements, using the HEAVY style.
Definition: separator.cpp:279
Element select(Element)
Definition: frame.cpp:38
Element borderEmpty(Element)
Draw an empty border around the element.
Definition: border.cpp:470
Element focusCursorBarBlinking(Element)
Definition: frame.cpp:183
Element yflex_shrink(Element)
Minimize if needed on the Y axis.
Definition: flex.cpp:168
Element hcenter(Element)
Center an element horizontally.
BorderStyle
Definition: elements.hpp:25
@ EMPTY
Definition: elements.hpp:31
@ DOUBLE
Definition: elements.hpp:29
@ HEAVY
Definition: elements.hpp:28
@ ROUNDED
Definition: elements.hpp:30
@ DASHED
Definition: elements.hpp:27
@ LIGHT
Definition: elements.hpp:26
Element gaugeDown(float progress)
Draw a high definition progress bar progressing from top to bottom.
Definition: gauge.cpp:265

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

ezgif com-gif-maker (4)

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

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:

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:

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

Terminal output:

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

Separators come in a variety of flavors as shown below:

float right,
Color background,
Color foreground);
float down,
Color background,
Color foreground);

gauge

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

Code:

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:

Colors

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

Color gallery: image

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);
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:147
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:135

LinearGradient

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

Decorator color(const LinearGradient&);
Decorator bgcolor(const LinearGradient&);

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

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, dim, underlined, inverted, blink.

Example

image

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:

Example using ftxui::hbox, ftxui::vbox and ftxui::filler.

image

Example using ftxui::gridbox:

image

Example using flexbox:

image

Checkout this example and the associated demo.

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

Code:

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

Terminal output:

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

Code:

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:

image

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

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

Simple example:

image

Complex example:

ezgif com-gif-maker (3)

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

image

All 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 <utility> // for forward
#include <vector> // for vector
#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)>;
namespace Container {
Component Vertical(Components children, int* selector);
Component Horizontal(Components children, int* selector);
Component Tab(Components children, int* selector);
} // namespace Container
Component Button(ConstStringRef label,
std::function<void()> on_click,
Ref<ButtonOption> = ButtonOption::Simple());
Component Checkbox(ConstStringRef label,
bool* checked,
Ref<CheckboxOption> option = CheckboxOption::Simple());
Component Input(StringRef content, Ref<InputOption> option = {});
Component Input(StringRef content,
StringRef placeholder,
Ref<InputOption> option = {});
Component Menu(ConstStringListRef entries,
int* selected_,
Ref<MenuOption> = MenuOption::Vertical());
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);
// 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 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 ResizableSplit(ResizableSplitOption options);
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)>);
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);
std::function<void()> on_enter,
std::function<void()> on_leave);
std::function<void(bool)> on_change);
ComponentDecorator Hoverable(std::function<void()> on_enter,
std::function<void()> on_leave);
ComponentDecorator Hoverable(std::function<void(bool)> on_change);
} // namespace ftxui
#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:299
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:256
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:344
Component Checkbox(ConstStringRef label, bool *checked, Ref< CheckboxOption > option=CheckboxOption::Simple())
Draw checkable element.
Definition: checkbox.cpp:112
Component Radiobox(ConstStringListRef entries, int *selected_, Ref< RadioboxOption > option={})
A list of element, where only one can be selected.
Definition: radiobox.cpp:212
Component Maybe(Component, const bool *show)
Decorate a component |child|. It is shown only when |show| is true.
Definition: maybe.cpp:67
Component ResizableSplitTop(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
std::function< Element(Element)> ElementDecorator
Definition: component.hpp:31
std::shared_ptr< ComponentBase > Component
Component Toggle(ConstStringListRef entries, int *selected)
An horizontal list of elements. The user can navigate through them.
Definition: menu.cpp:527
std::vector< Component > Components
Component Collapsible(ConstStringRef label, Component child, Ref< bool > show=false)
Component MenuEntry(ConstStringRef label, Ref< MenuEntryOption >={})
A specific menu entry. They can be put into a Container::Vertical to form a menu.
Definition: menu.cpp:557
Component Modal(Component main, Component modal, const bool *show_modal)
Definition: modal.cpp:15
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:60
Component Hoverable(Component component, bool *hover)
Wrap a component. Gives the ability to know if it is hovered by the mouse.
Definition: hoverable.cpp:41
std::shared_ptr< T > Make(Args &&... args)
Definition: component.hpp:25
Component ResizableSplit(ResizableSplitOption options)
A split in between two components.
Component Button(ConstStringRef label, std::function< void()> on_click, Ref< ButtonOption >=ButtonOption::Simple())
Draw a button. Execute a function when clicked.
Definition: button.cpp:59
Component Menu(ConstStringListRef entries, int *selected_, Ref< MenuOption >=MenuOption::Vertical())
A list of text. The focused element is selected.
Definition: menu.cpp:516
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:15
Component Slider(SliderOption< T > options={})
A slider in any direction.
Definition: slider.cpp:327
Component ResizableSplitBottom(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Component ResizableSplitLeft(Component main, Component back, int *main_size)
An horizontal split in between two components, configurable using the mouse.
std::function< Component(Component)> ComponentDecorator
Definition: component.hpp:30
Component Input(StringRef content, Ref< InputOption > option={})
An input box for editing text.
Definition: input.cpp:557
static ButtonOption Simple()
Create a ButtonOption, inverted when focused.
static CheckboxOption Simple()
Option for standard Checkbox.
static MenuOption Vertical()

Input

Example:

image

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

Menu

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

Example:

image

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

Toggle 

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

Example:

image

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:

image

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:

image

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:

youtube-video-gif (3)

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:

image

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

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:

ezgif com-gif-maker (1)

Horizontal:

ezgif com-gif-maker (2)

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:

Example:

ezgif com-gif-maker

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