FTXUI/doc/module-component.md

@page module-component ftxui / component @tableofcontents

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

The @subpage module-component-examples section provides a collection of examples.

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

\include ftxui/component/component.hpp

Input

Example:

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

@htmlonly

@endhtmlonly

Filtered input

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

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"

@htmlonly

@endhtmlonly

Toggle 

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

Example:

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

@htmlonly

@endhtmlonly

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"

@htmlonly

@endhtmlonly

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"

@htmlonly

@endhtmlonly

Dropdown

A drop-down menu is a component that, when opened, displays a list of elements for the user to select from.

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 \ref 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 \ref 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 toggled on or off by the user. Essentially, this is the combination of the ftxui::Checkbox() and ftxui::Maybe() components.

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

Maybe

Produced by: ftxui::Maybe() from \ref 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 handles 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 takes a list of components and displays 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:

@htmlonly

@endhtmlonly

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

If you don't need to process a new Event, you can use:

screen->RequestAnimationFrame();

instead.