2020-05-25 07:34:13 +08:00
|
|
|
|
\mainpage
|
|
|
|
|
|
|
|
|
|
# Introduction
|
|
|
|
|
|
|
|
|
|
Welcome to the FTXUI documentation. Here, you will find the detail of every
|
|
|
|
|
functions and classes.
|
|
|
|
|
|
|
|
|
|
@tableofcontents
|
|
|
|
|
|
|
|
|
|
**Short example**
|
|
|
|
|
|
|
|
|
|
**main.cpp**
|
|
|
|
|
```cpp
|
2018-10-10 01:06:03 +08:00
|
|
|
|
#include <ftxui/dom/elements.hpp>
|
2020-05-25 07:34:13 +08:00
|
|
|
|
#include <ftxui/screen/screen.hpp>
|
|
|
|
|
#include <iostream>
|
|
|
|
|
|
|
|
|
|
int main(void) {
|
|
|
|
|
using namespace ftxui;
|
|
|
|
|
|
|
|
|
|
// Define the document
|
|
|
|
|
Element document =
|
|
|
|
|
hbox({
|
|
|
|
|
text(L"left") | border,
|
|
|
|
|
text(L"middle") | border | flex,
|
|
|
|
|
text(L"right") | border,
|
|
|
|
|
});
|
|
|
|
|
|
|
|
|
|
auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
|
|
|
|
|
Render(screen, document);
|
|
|
|
|
std::cout << screen.ToString() << std::endl;
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
return EXIT_SUCCESS;
|
|
|
|
|
}
|
|
|
|
|
```
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
**output**
|
|
|
|
|
```bash
|
|
|
|
|
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
|
|
|
|
|
│left││middle ││right│
|
|
|
|
|
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**cmake**
|
|
|
|
|
```cpp
|
|
|
|
|
cmake_minimum_required (VERSION 3.11)
|
|
|
|
|
|
|
|
|
|
include(FetchContent)
|
|
|
|
|
FetchContent_Declare(ftxui
|
|
|
|
|
GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
|
|
|
|
|
)
|
|
|
|
|
FetchContent_GetProperties(ftxui)
|
|
|
|
|
if(NOT ftxui_POPULATED)
|
|
|
|
|
FetchContent_Populate(ftxui)
|
|
|
|
|
add_subdirectory(${ftxui_SOURCE_DIR} ${ftxui_BINARY_DIR} EXCLUDE_FROM_ALL)
|
|
|
|
|
endif()
|
|
|
|
|
|
|
|
|
|
add_executable(main src/main.cpp)
|
|
|
|
|
target_link_libraries(main
|
|
|
|
|
PRIVATE ftxui::screen
|
|
|
|
|
PRIVATE ftxui::dom
|
|
|
|
|
PRIVATE ftxui::component # Not needed for this example.
|
|
|
|
|
)
|
|
|
|
|
set_target_properties(main PROPERTIES CXX_STANDARD 17)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
# Modules
|
|
|
|
|
|
|
|
|
|
The project is split into 3 modules:
|
|
|
|
|
1. ftxui/screen
|
|
|
|
|
2. ftxui/dom
|
|
|
|
|
3. ftxui/component
|
|
|
|
|
|
|
|
|
|
ftxui/screen defines a ftxui::Screen, this is a grid of ftxui::Pixel.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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 style. The screen can be printed as a string using ftxui::Screen::ToString().
|
|
|
|
|
|
|
|
|
|
Example:
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~cpp
|
2020-05-25 07:34:13 +08:00
|
|
|
|
#include <ftxui/screen/screen.hpp>
|
|
|
|
|
|
|
|
|
|
int main(void) {
|
|
|
|
|
using namespace ftxui;
|
|
|
|
|
auto screen = ftxui::Screen(Dimension::Fixed(32), Dimension::Fixed(10));
|
|
|
|
|
|
|
|
|
|
auto& pixel = screen.PixelAt(10,10);
|
|
|
|
|
pixel.character = U'A';
|
|
|
|
|
pixel.bold = true;
|
|
|
|
|
|
|
|
|
|
std::cout << screen.ToString();
|
|
|
|
|
return EXIT_SUCCESS;
|
|
|
|
|
}
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
## dom
|
|
|
|
|
|
|
|
|
|
This module defines a hierachical set of Element. An element manages layout and can be responsive to the terminal dimensions.
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
They are declared in ftxui/dom/elements.hpp>
|
|
|
|
|
|
|
|
|
|
\include ftxui/dom/elements.hpp
|
|
|
|
|
|
|
|
|
|
### 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
|
2020-05-25 07:34:13 +08:00
|
|
|
|
using namespace ftxui;
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
2020-05-25 07:34:13 +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
|
2020-05-25 07:34:13 +08:00
|
|
|
|
using namespace ftxui;
|
|
|
|
|
|
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
|
|
|
|
|
2020-05-25 07:34:13 +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
|
2020-05-21 02:36:47 +08:00
|
|
|
|
border(
|
|
|
|
|
hbox({
|
2020-05-25 07:34:13 +08:00
|
|
|
|
text(L"Left"),
|
2020-05-21 02:36:47 +08:00
|
|
|
|
separator(),
|
2020-05-25 07:34:13 +08:00
|
|
|
|
text(L"Right")
|
2020-05-21 02:36:47 +08:00
|
|
|
|
})
|
2020-05-25 07:34:13 +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
|
2020-05-25 07:34:13 +08:00
|
|
|
|
┌────┬─────┐
|
|
|
|
|
│left│right│
|
|
|
|
|
└────┴─────┘
|
2018-10-21 20:14:46 +08:00
|
|
|
|
~~~
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
### gauge
|
2018-10-10 01:06:03 +08:00
|
|
|
|
|
|
|
|
|
A gauge. It can be used to represent a progress bar.
|
2020-05-25 07:34:13 +08:00
|
|
|
|
~~~cpp
|
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-05-25 07:34:13 +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)
|
|
|
|
|
|
2020-05-25 07:34:13 +08:00
|
|
|
|
**Examples**
|
2020-04-11 21:13:08 +08:00
|
|
|
|
~~~cpp
|
2020-05-21 02:36:47 +08:00
|
|
|
|
hbox({
|
2020-04-11 21:13:08 +08:00
|
|
|
|
text(L"left") | border ,
|
|
|
|
|
text(L"middle") | border | flex,
|
2020-05-21 02:36:47 +08:00
|
|
|
|
text(L"right") | border,
|
|
|
|
|
});
|
2020-04-11 21:13:08 +08:00
|
|
|
|
~~~
|
|
|
|
|
~~~bash
|
|
|
|
|
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
|
|
|
|
|
│left││middle ││right│
|
|
|
|
|
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
|
|
|
|
|
~~~
|
|
|
|
|
|
|
|
|
|
~~~cpp
|
2020-05-21 02:36:47 +08:00
|
|
|
|
hbox({
|
2020-04-11 21:13:08 +08:00
|
|
|
|
text(L"left") | border ,
|
|
|
|
|
text(L"middle") | border | flex,
|
2020-05-21 02:36:47 +08:00
|
|
|
|
text(L"right") | border | flex,
|
|
|
|
|
});
|
2020-04-11 21:13:08 +08:00
|
|
|
|
~~~
|
|
|
|
|
~~~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)
|