2020-04-11 21:13:08 +08:00
|
|
|
|
Table of content:
|
|
|
|
|
=================
|
|
|
|
|
|
2019-01-19 07:20:29 +08:00
|
|
|
|
- [Introduction](#introduction)
|
2018-10-21 20:32:25 +08:00
|
|
|
|
- [DOM](#dom)
|
|
|
|
|
* [Widget.](#widget)
|
|
|
|
|
+ [text](#text)
|
2019-01-20 05:06:05 +08:00
|
|
|
|
+ [border](#border)
|
2019-02-02 08:59:48 +08:00
|
|
|
|
+ [separator](#separator) [gauge](#gauge)
|
2020-04-11 21:13:08 +08:00
|
|
|
|
* [Style](#style)
|
|
|
|
|
* [Layout](#layout)
|
|
|
|
|
+ [Examples](#examples)
|
2018-10-21 20:32:25 +08:00
|
|
|
|
- [Components.](#components)
|
|
|
|
|
* [Input](#input)
|
|
|
|
|
* [Menu](#menu)
|
|
|
|
|
* [Toggle.](#toggle)
|
|
|
|
|
|
2019-01-19 07:20:29 +08:00
|
|
|
|
## Introduction
|
2020-04-11 21:13:08 +08:00
|
|
|
|
I recommand not to take too much time reading the tutorial. Instead,
|
|
|
|
|
you should try to read the examples (in [./examples/](../examples)).
|
|
|
|
|
|
|
|
|
|
The library is split in 3 parts:
|
|
|
|
|
- [ftxui/screen/](../include/ftxui/screen/)
|
|
|
|
|
|
|
|
|
|
It defines a ftxui::Screen. A Screen is a grid of ftxui::Pixel. A Pixel contains a character and its associated style.
|
|
|
|
|
Once the screen is ready, you can display it on the terminal.
|
|
|
|
|
|
|
|
|
|
- [ftuix/dom/](../include/ftxui/dom/)
|
|
|
|
|
|
|
|
|
|
These are a set of hierachical ftxui::Element declared in [ftxui/dom/elements.hpp](../ftxui/dom/elements.hpp).
|
|
|
|
|
An element can render itself on the the Screen. It manage layout and is responsive to the Screen dimensions.
|
|
|
|
|
|
|
|
|
|
- [ftuix/component/](../include/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.
|
2019-01-19 07:20:29 +08:00
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
## DOM
|
2018-10-10 01:06:03 +08:00
|
|
|
|
All the dom element are declared in one header:
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~cpp
|
2018-10-10 01:06:03 +08:00
|
|
|
|
#include <ftxui/dom/elements.hpp>
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
|
|
|
|
It declares the following set of elements:
|
|
|
|
|
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~cpp
|
2019-01-20 05:06:05 +08:00
|
|
|
|
// --- Widget ---
|
2018-10-10 01:06:03 +08:00
|
|
|
|
Element text(std::wstring text);
|
|
|
|
|
Element separator();
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Element separator(Pixel);
|
2018-10-10 01:06:03 +08:00
|
|
|
|
Element gauge(float ratio);
|
2019-01-20 05:06:05 +08:00
|
|
|
|
Element border(Element);
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Decorator borderWith(Pixel);
|
2019-01-19 07:20:29 +08:00
|
|
|
|
Element window(Element title, Element content);
|
|
|
|
|
Element spinner(int charset_index, size_t image_index);
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Elements paragraph(std::wstring text); // Use inside hflow(). Split by space.
|
|
|
|
|
Element graph(GraphFunction);
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2019-01-06 08:37:26 +08:00
|
|
|
|
// -- Decorator ---
|
2018-10-10 01:06:03 +08:00
|
|
|
|
Element bold(Element);
|
|
|
|
|
Element dim(Element);
|
|
|
|
|
Element inverted(Element);
|
|
|
|
|
Element underlined(Element);
|
2019-01-03 05:33:59 +08:00
|
|
|
|
Element blink(Element);
|
2019-01-06 08:37:26 +08:00
|
|
|
|
Decorator color(Color);
|
|
|
|
|
Decorator bgcolor(Color);
|
2019-01-19 07:20:29 +08:00
|
|
|
|
Element color(Color, Element);
|
|
|
|
|
Element bgcolor(Color, Element);
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2019-01-20 05:06:05 +08:00
|
|
|
|
// --- Layout ---
|
|
|
|
|
// Horizontal, Vertical or stacked set of elements.
|
|
|
|
|
Element hbox(Elements);
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Element vbox(Elements);
|
2019-01-20 05:06:05 +08:00
|
|
|
|
Element dbox(Elements);
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Element hflow(Elements);
|
2019-01-20 05:06:05 +08:00
|
|
|
|
|
|
|
|
|
// -- Flexibility ---
|
|
|
|
|
// Define how to share the remaining space when not all of it is used inside a
|
|
|
|
|
// container.
|
|
|
|
|
Element filler();
|
|
|
|
|
Element flex(Element);
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Element notflex(Element);
|
|
|
|
|
|
|
|
|
|
// -- Size override;
|
|
|
|
|
enum Direction { WIDTH, HEIGHT };
|
|
|
|
|
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
|
|
|
|
|
Decorator size(Direction, Constraint, int value);
|
2019-01-20 05:06:05 +08:00
|
|
|
|
|
|
|
|
|
// --- 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 focus(Element);
|
|
|
|
|
Element select(Element);
|
|
|
|
|
|
|
|
|
|
// --- Util --------------------------------------------------------------------
|
2018-10-10 01:06:03 +08:00
|
|
|
|
Element hcenter(Element);
|
|
|
|
|
Element vcenter(Element);
|
|
|
|
|
Element center(Element);
|
2019-01-19 07:20:29 +08:00
|
|
|
|
Element align_right(Element);
|
2019-01-03 05:33:59 +08:00
|
|
|
|
Element nothing(Element element);
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
### Widget.
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
#### text
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2019-01-27 23:56:37 +08:00
|
|
|
|
The most simple widget. It displays a text.
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~cpp
|
2018-10-10 01:06:03 +08:00
|
|
|
|
text(L"I am a piece of text");
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
|
|
|
|
~~~bash
|
2018-10-10 01:06:03 +08:00
|
|
|
|
I am a piece of text.
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2019-01-20 05:06:05 +08:00
|
|
|
|
#### border
|
2019-01-27 23:56:37 +08:00
|
|
|
|
Add a border around an element
|
2019-01-06 08:37:26 +08:00
|
|
|
|
~~~cpp
|
2019-01-20 05:06:05 +08:00
|
|
|
|
border(text(L"The element"))
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~bash
|
2018-10-10 01:06:03 +08:00
|
|
|
|
┌───────────┐
|
|
|
|
|
│The element│
|
|
|
|
|
└───────────┘
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
#### separator
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
|
|
|
|
Display a vertical or horizontal line to visually split the content of a
|
|
|
|
|
container in two.
|
|
|
|
|
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~cpp
|
2019-01-20 05:06:05 +08:00
|
|
|
|
border(hbox(
|
2018-10-21 20:32:25 +08:00
|
|
|
|
vbox(
|
|
|
|
|
text(L"left top"),
|
|
|
|
|
text(L"left bottom")
|
|
|
|
|
),
|
|
|
|
|
separator(),
|
|
|
|
|
vbox(
|
|
|
|
|
text(L"right top"),
|
|
|
|
|
text(L"right bottom")
|
|
|
|
|
)
|
2018-10-10 01:06:03 +08:00
|
|
|
|
));
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~bash
|
2018-10-10 01:06:03 +08:00
|
|
|
|
┌───────────┬────────────┐
|
|
|
|
|
│left top │right top │
|
|
|
|
|
│left bottom│right bottom│
|
|
|
|
|
└───────────┴────────────┘
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
#### gauge
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
|
|
|
|
A gauge. It can be used to represent a progress bar.
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~c+
|
2019-01-20 05:06:05 +08:00
|
|
|
|
border(gauge(0.5))
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~bash
|
2018-10-10 01:06:03 +08:00
|
|
|
|
┌────────────────────────────────────────────────────────────────────────────┐
|
|
|
|
|
│██████████████████████████████████████ │
|
|
|
|
|
└────────────────────────────────────────────────────────────────────────────┘
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-04-11 21:13:08 +08:00
|
|
|
|
#### graph
|
2019-01-27 23:56:37 +08:00
|
|
|
|
[![asciicast](https://asciinema.org/a/223726.svg)](https://asciinema.org/a/223726)
|
|
|
|
|
|
2019-01-06 08:37:26 +08:00
|
|
|
|
|
2020-04-11 21:13:08 +08:00
|
|
|
|
### Style
|
|
|
|
|
A terminal console can usually display colored text and colored background.
|
|
|
|
|
The text can also have different effects: bold, dim, underlined, inverted,
|
|
|
|
|
blink.
|
|
|
|
|
|
|
|
|
|
~~~cpp
|
|
|
|
|
Element bold(Element);
|
|
|
|
|
Element dim(Element);
|
|
|
|
|
Element inverted(Element);
|
|
|
|
|
Element underlined(Element);
|
|
|
|
|
Element blink(Element);
|
|
|
|
|
Decorator color(Color);
|
|
|
|
|
Decorator bgcolor(Color);
|
|
|
|
|
~~~
|
2019-01-06 08:37:26 +08:00
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
~~~cpp
|
|
|
|
|
underlined(bold(text(L"This text is bold and underlined")))
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
Tips: The pipe operator can be used to chain Decorator:
|
|
|
|
|
~~~cpp
|
|
|
|
|
text(L"This text is bold")) | bold | underlined
|
|
|
|
|
~~~
|
|
|
|
|
|
2020-04-11 21:13:08 +08:00
|
|
|
|
### 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
|
|
|
|
|
~~~cpp
|
|
|
|
|
hbox(
|
|
|
|
|
text(L"left") | border ,
|
|
|
|
|
text(L"middle") | border | flex,
|
|
|
|
|
text(L"right") | border
|
|
|
|
|
);
|
|
|
|
|
~~~
|
|
|
|
|
~~~bash
|
|
|
|
|
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
|
|
|
|
|
│left││middle ││right│
|
|
|
|
|
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
~~~cpp
|
|
|
|
|
hbox(
|
|
|
|
|
text(L"left") | border ,
|
|
|
|
|
text(L"middle") | border | flex,
|
|
|
|
|
text(L"right") | border | flex
|
|
|
|
|
);
|
|
|
|
|
~~~
|
|
|
|
|
~~~bash
|
|
|
|
|
┌────┐┌───────────────────────────────────┐┌───────────────────────────────────┐
|
|
|
|
|
│left││middle ││right │
|
|
|
|
|
└────┘└───────────────────────────────────┘└───────────────────────────────────┘
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
## Components.
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2019-01-27 23:56:37 +08:00
|
|
|
|
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.
|
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
### Input
|
2019-01-27 23:56:37 +08:00
|
|
|
|
[![asciicast](https://asciinema.org/a/223719.svg)](https://asciinema.org/a/223719)
|
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
### Menu
|
2019-01-27 23:56:37 +08:00
|
|
|
|
[![asciicast](https://asciinema.org/a/223720.svg)](https://asciinema.org/a/223720)
|
|
|
|
|
|
2018-10-21 20:32:25 +08:00
|
|
|
|
### Toggle.
|
2019-01-27 23:56:37 +08:00
|
|
|
|
[![asciicast](https://asciinema.org/a/223722.svg)](https://asciinema.org/a/223722)
|
|
|
|
|
|
|
|
|
|
### CheckBox
|
|
|
|
|
[![asciicast](https://asciinema.org/a/223724.svg)](https://asciinema.org/a/223724)
|
|
|
|
|
|
|
|
|
|
### RadioBox
|
|
|
|
|
[![asciicast](https://asciinema.org/a/223725.svg)](https://asciinema.org/a/223725)
|