# FTXUI: ftxui / component

Loading...
Searching...
No Matches
ftxui / component

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

The Example 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"

// 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/util/warn_windows_macro.hpp>
#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
elements.hpp
main
int main()
Definition examples/component/button.cpp:33
ftxui::CheckboxOption::Simple
static CheckboxOption Simple()
Option for standard Checkbox.
Definition component_options.cpp:244
ftxui::ButtonOption::Simple
static ButtonOption Simple()
Create a ButtonOption, inverted when focused.
Definition component_options.cpp:165
ftxui::MenuOption::Vertical
static MenuOption Vertical()
Standard options for a vertical menu. This can be useful to implement a list of selectable items.
Definition component_options.cpp:102
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::Maybe
Component Maybe(Component, const bool *show)
Decorate a component |child|. It is shown only when |show| is true.
Definition src/ftxui/component/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 src/ftxui/component/resizable_split.cpp:283
ftxui::Menu
Component Menu(MenuOption options)
A list of text. The focused element is selected.
Definition src/ftxui/component/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 src/ftxui/component/menu.cpp:614
ftxui::Toggle
Component Toggle(ConstStringListRef entries, int *selected)
An horizontal list of elements. The user can navigate through them.
Definition src/ftxui/component/menu.cpp:554
ftxui::Radiobox
Component Radiobox(RadioboxOption options)
A list of element, where only one can be selected.
Definition src/ftxui/component/radiobox.cpp:204
ftxui::Button
Component Button(ButtonOption options)
Draw a button. Execute a function when clicked.
Definition src/ftxui/component/button.cpp:175
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 src/ftxui/component/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::Window
Component Window(WindowOptions option)
A draggeable / resizeable window. To use multiple of them, they must be stacked using Container::Stac...
Definition src/ftxui/component/window.cpp:312
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::Input
Component Input(InputOption options={})
An input box for editing text.
Definition src/ftxui/component/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 src/ftxui/component/resizable_split.cpp:249
ftxui::Dropdown
Component Dropdown(ConstStringListRef entries, int *selected)
A dropdown menu.
Definition src/ftxui/component/dropdown.cpp:22
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::ResizableSplitBottom
Component ResizableSplitBottom(Component main, Component back, int *main_size)
An vertical split in between two components, configurable using the mouse.
Definition src/ftxui/component/resizable_split.cpp:317
ftxui::Checkbox
Component Checkbox(CheckboxOption options)
Draw checkable element.
Definition src/ftxui/component/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 src/ftxui/component/resizable_split.cpp:215
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
The FTXUI ftxui:: namespace.
Definition animation.hpp:10
ftxui::Make
std::shared_ptr< T > Make(Args &&... args)
Definition component.hpp:27
ftxui::Element
std::shared_ptr< Node > Element
Definition elements.hpp:22
ftxui::ElementDecorator
std::function< Element(Element)> ElementDecorator
Definition component.hpp:33
ftxui::Components
std::vector< Component > Components
Definition component_base.hpp:25
ftxui::ResizableSplit
Component ResizableSplit(ResizableSplitOption options)
A split in between two components.
Definition src/ftxui/component/resizable_split.cpp:186
ftxui::operator|
Component operator|(Component component, ComponentDecorator decorator)
Definition component/util.cpp:12
ftxui::Collapsible
Component Collapsible(ConstStringRef label, Component child, Ref< bool > show=false)
A collapsible component. It displays a checkbox with an arrow. Once activated, the child is displayed...
Definition src/ftxui/component/collapsible.cpp:33
ftxui::Slider
Component Slider(SliderOption< T > options)
A slider in any direction.
Definition src/ftxui/component/slider.cpp:316
ftxui::operator|=
Component & operator|=(Component &component, ComponentDecorator decorator)
Definition component/util.cpp:22
ftxui::ComponentDecorator
std::function< Component(Component)> ComponentDecorator
Definition component.hpp:32
ftxui::Component
std::shared_ptr< ComponentBase > Component
Definition component_base.hpp:24
ftxui::CatchEvent
Component CatchEvent(Component child, std::function< bool(Event)>)
ref.hpp
warn_windows_macro.hpp

# Input

Example:

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

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

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

# 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.