FTXUI/doc/mainpage.md

503 lines
13 KiB
Markdown
Raw Normal View History

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
#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,
});
2020-08-09 20:53:56 +08:00
auto screen = Screen::Create(
Dimension::Full(), // Width
Dimension::Fit(document) // Height
);
2020-05-25 07:34:13 +08:00
Render(screen, document);
2021-05-10 02:32:27 +08:00
screen.Print();
2020-05-25 07:34:13 +08:00
return EXIT_SUCCESS;
}
```
2020-05-25 07:34:13 +08:00
**output**
```bash
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
│left││middle ││right│
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
```
2021-05-15 02:56:37 +08:00
# Build
## Using CMake
CMakeLists.txt
~~~cmake
2020-05-25 07:34:13 +08:00
cmake_minimum_required (VERSION 3.11)
2021-05-15 02:56:37 +08:00
# --- Fetch FTXUI --------------------------------------------------------------
2020-05-25 07:34:13 +08:00
include(FetchContent)
2021-05-15 02:56:37 +08:00
set(FETCHCONTENT_UPDATES_DISCONNECTED TRUE)
2020-05-25 07:34:13 +08:00
FetchContent_Declare(ftxui
GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
2021-05-15 02:56:37 +08:00
# Specify a GIT_TAG here.
2020-05-25 07:34:13 +08:00
)
2021-05-15 02:56:37 +08:00
2020-05-25 07:34:13 +08:00
FetchContent_GetProperties(ftxui)
if(NOT ftxui_POPULATED)
FetchContent_Populate(ftxui)
add_subdirectory(${ftxui_SOURCE_DIR} ${ftxui_BINARY_DIR} EXCLUDE_FROM_ALL)
endif()
2021-05-15 02:56:37 +08:00
# ------------------------------------------------------------------------------
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
2020-05-25 07:34:13 +08:00
PRIVATE ftxui::screen
PRIVATE ftxui::dom
PRIVATE ftxui::component # Not needed for this example.
)
2021-05-15 02:56:37 +08:00
# C++17 is used. We requires fold expressions at least.
set_target_properties(ftxui-starter PROPERTIES CXX_STANDARD 17)
~~~
Build
~~~
mkdir build && cd build
cmake ..
make
./main
~~~
## Using NXXM
**.nxxm/deps**
~~~json
{
"ArthurSonzogni/FTXUI": {}
}
~~~
Build:
~~~
nxxm . -t clang-cxx17
~~~
2020-05-25 07:34:13 +08:00
2020-08-09 20:53:56 +08:00
# List of modules.
2020-05-25 07:34:13 +08:00
The project is split into 3 modules:
2020-08-09 20:53:56 +08:00
1. **ftxui/screen** defines a ftxui::Screen, this is a grid of ftxui::Pixel.
2020-05-25 07:34:13 +08:00
2020-08-09 20:53:56 +08:00
2. **ftxui/dom** is the main module. It defines a hierarchical set of ftxui::Element.
2020-05-25 07:34:13 +08:00
An element draws something on the ftxui::Screen. It is responsive to the size of
its container.
2020-08-09 20:53:56 +08:00
3. **ftxui/component** The part is only needed if you need to respond to the User
2020-05-25 07:34:13 +08:00
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.
2021-05-15 02:56:37 +08:00
# screen
2020-05-25 07:34:13 +08:00
It defines a ftxui::Screen. This is a grid of ftxui::Pixel. A Pixel represent a
2020-08-09 20:53:56 +08:00
unicode character and its associated style (bold, colors, etc...).
The screen can be printed as a string using ftxui::Screen::ToString().
2020-05-25 07:34:13 +08:00
2018-10-21 20:14:46 +08:00
~~~cpp
2020-05-25 07:34:13 +08:00
#include <ftxui/screen/screen.hpp>
#include <iostream>
2020-05-25 07:34:13 +08:00
int main(void) {
using namespace ftxui;
auto screen = Screen::Create(Dimension::Fixed(32), Dimension::Fixed(10));
2020-05-25 07:34:13 +08:00
auto& pixel = screen.PixelAt(9,9);
2020-05-25 07:34:13 +08:00
pixel.character = U'A';
pixel.bold = true;
2020-08-09 20:53:56 +08:00
pixel.foreground_color = Color::Blue;
2020-05-25 07:34:13 +08:00
std::cout << screen.ToString();
return EXIT_SUCCESS;
}
2018-10-21 20:14:46 +08:00
~~~
2021-05-15 02:56:37 +08:00
# dom
2020-05-25 07:34:13 +08:00
This module defines a hierachical set of Element. An element manages layout and can be responsive to the terminal dimensions.
2020-08-09 20:53:56 +08:00
**Example:**
```cpp
// Define the document
Element document = vbox({
text(L"The window") | bold | color(Color::Blue),
gauge(0.5)
text(L"The footer")
});
// Add a border.
document = border(document);
```
**List of elements**
You only need one header: ftxui/dom/elements.hpp
\include ftxui/dom/elements.hpp
## text
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
text(L"I am a piece of text");
2018-10-21 20:14:46 +08:00
~~~
~~~bash
I am a piece of text.
2018-10-21 20:14:46 +08:00
~~~
2020-08-09 20:53:56 +08:00
## border
2020-05-25 07:34:13 +08:00
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-21 20:14:46 +08:00
~~~bash
┌───────────┐
│The element│
└───────────┘
2018-10-21 20:14:46 +08:00
~~~
2020-08-09 20:53:56 +08:00
## window
A ftxui::window is a ftxui::border, but with some text on top of the border.
Add a border around an element
~~~cpp
window(L"The window", text(L"The element"))
~~~
~~~bash
┌The window─┐
│The element│
└───────────┘
~~~
## separator
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
border(
hbox({
2020-05-25 07:34:13 +08:00
text(L"Left"),
separator(),
2020-05-25 07:34:13 +08:00
text(L"Right")
})
2020-05-25 07:34:13 +08:00
)
2018-10-21 20:14:46 +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
~~~
2020-08-09 20:53:56 +08:00
## gauge
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-21 20:14:46 +08:00
~~~bash
┌────────────────────────────────────────────────────────────────────────────┐
│██████████████████████████████████████ │
└────────────────────────────────────────────────────────────────────────────┘
2018-10-21 20:14:46 +08:00
~~~
2020-08-09 20:53:56 +08:00
## graph
2021-05-15 02:56:37 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223726" src="https://asciinema.org/a/223726.js" async></script>
@endhtmlonly
## Colors
A terminal console can usually display colored text and colored background.
~~~cpp
Decorator color(Color);
Decorator bgcolor(Color);
~~~
2020-09-06 19:43:24 +08:00
### Palette16
On most terminal the following colors are supported:
2020-08-09 20:53:56 +08:00
- Default
- Black
- GrayDark
- GrayLight
- White
2019-01-27 23:56:37 +08:00
2020-08-09 20:53:56 +08:00
- Blue
- BlueLight
2019-01-06 08:37:26 +08:00
2020-08-09 20:53:56 +08:00
- Cyan
- CyanLight
- Green
- GreenLight
- Magenta
- MagentaLight
- Red
- RedLight
- Yellow
- YellowLight
Example:
```cpp
text(L"Blue foreground") | color(Color::Blue);
text(L"Blue backgrond") | bgcolor(Color::Blue);
text(L"Black on white") | color(Color::Black) | bgcolor(Color::White);
```
2020-09-06 19:43:24 +08:00
### Palette256
On terminal supporting 256 colors.
@htmlonly
<script id="asciicast-OAUc3n6QrkmrLt7XEEb8AzbLt" src="https://asciinema.org/a/OAUc3n6QrkmrLt7XEEb8AzbLt.js" async></script>
@endhtmlonly
```cpp
text(L"HotPink") | color(Color::HotPink);
```
### TrueColor
On terminal supporting trueColor, you can directly chose the 24bit RGB color:
There are two constructors:
```cpp
ftxui::Color::RGB(uint8_t red, uint8_t green, uint8_t blue);
ftxui::Color::HSV(uint8_t hue, uint8_t saturation, uint8_t value);
```
@htmlonly
<script id="asciicast-dk5r8IcCH0aFIIgWG0keSEHMG" src="https://asciinema.org/a/dk5r8IcCH0aFIIgWG0keSEHMG.js" async></script>
<script id="asciicast-xwzzghmqcqzIuyLwCpQFEqbEu" src="https://asciinema.org/a/xwzzghmqcqzIuyLwCpQFEqbEu.js" async></script>
@endhtmlonly
2020-08-09 20:53:56 +08:00
## Style
2020-04-11 21:13:08 +08:00
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-08-09 20:53:56 +08:00
## Layout
2020-04-11 21:13:08 +08:00
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
hbox({
2020-04-11 21:13:08 +08:00
text(L"left") | border ,
text(L"middle") | border | flex,
text(L"right") | border,
});
2020-04-11 21:13:08 +08:00
~~~
~~~bash
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
│left││middle ││right│
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
~~~
~~~cpp
hbox({
2020-04-11 21:13:08 +08:00
text(L"left") | border ,
text(L"middle") | border | flex,
text(L"right") | border | flex,
});
2020-04-11 21:13:08 +08:00
~~~
~~~bash
┌────┐┌───────────────────────────────────┐┌───────────────────────────────────┐
│left││middle ││right │
└────┘└───────────────────────────────────┘└───────────────────────────────────┘
~~~
2021-05-15 02:56:37 +08:00
# component
The `ftxui/component` directory defines the logic to get produce
interactive component responding to user's events (keyboard, mouse, etc...)
A ftxui::ScreenInteractive defines a main loop to render a component.
A ftxui::Component is a shared pointer to a ftxui::ComponentBase. The later
defines
- ftxui::ComponentBase::Render(): How to render the interface.
- ftxui::ComponentBase::OnEvent(): How to react to events.
- ftxui::ComponentBase::Add(): Give a parent/child relation ship in between
two component. This defines a tree a components, which help properly define
how keyboard navigation works.
Predefined components are available in `ftxui/dom/component.hpp`:
\include ftxui/component/component.hpp
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.
2020-08-09 20:53:56 +08:00
## Input
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Input() from "ftxui/component/component.hpp"
2020-08-16 08:24:50 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223719" src="https://asciinema.org/a/223719.js" async></script>
@endhtmlonly
## Menu
2020-08-16 08:24:50 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Menu() from "ftxui/component/component.hpp"
2020-08-16 08:24:50 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223720" src="https://asciinema.org/a/223720.js" async></script>
@endhtmlonly
## Toggle.
2020-08-16 08:24:50 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Toggle() from "ftxui/component/component.hpp"
2020-08-16 08:24:50 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223722" src="https://asciinema.org/a/223722.js" async></script>
@endhtmlonly
2019-01-27 23:56:37 +08:00
2020-08-09 20:53:56 +08:00
## CheckBox
2020-08-16 08:24:50 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Checkbox() from "ftxui/component/component.hpp"
2020-08-16 08:24:50 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223724" src="https://asciinema.org/a/223724.js" async></script>
@endhtmlonly
2019-01-27 23:56:37 +08:00
2020-08-09 20:53:56 +08:00
## RadioBox
2020-08-16 08:24:50 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Radiobox() from "ftxui/component/component.hpp"
2020-08-16 08:24:50 +08:00
2020-08-09 20:53:56 +08:00
@htmlonly
<script id="asciicast-223725" src="https://asciinema.org/a/223725.js" async></script>
@endhtmlonly
2019-01-27 23:56:37 +08:00
2021-05-15 02:56:37 +08:00
## Renderer
2019-01-27 23:56:37 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Renderer() from \ref "ftxui/component/component.hpp". This
component decorate another one by using a different function to render an
interface.
2020-08-09 20:53:56 +08:00
2021-05-27 21:46:23 +08:00
## CatchEvent
Produced by: ftxui::CatchEvent() from \ref "ftxui/component/component.hpp". This
component decorate another one and catch the events before the underlying
component.
2021-05-15 02:56:37 +08:00
## Container::Horizontal
2020-08-09 20:53:56 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Container::Horizontal() from
"ftxui/component/component.hpp". It displays a list of components horizontally
and handle keyboard/mouse navigation.
2020-08-09 20:53:56 +08:00
2021-05-15 02:56:37 +08:00
## Container::Vertial
2020-08-09 20:53:56 +08:00
2021-05-15 02:56:37 +08:00
Produced by: ftxui::Container::Vertical() from
"ftxui/component/component.hpp". It displays a list of components vertically
and handles keyboard/mouse navigation.
2020-08-09 20:53:56 +08:00
2021-05-15 02:56:37 +08:00
## Container::Tab
2020-08-09 20:53:56 +08:00
2021-05-15 02:56:37 +08:00
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.
2021-05-27 21:46:23 +08:00
## ResizableSplit::{Left, Right, Top, Bottom}
Produced by:
- ftxui::ResizableSplitLeft()
- ftxui::ResizableSplitRight()
- ftxui::ResizableSplitTop()
- ftxui::ResizableSplitBottom()
from "ftxui/component/component.hpp"
It defines an horizontal or vertical separation in between two chilren
component. The position of the split is variable and controlable using the
mouse.
@htmlonly
<script id="asciicast-tprMH2EdkUoMb7D2YxgMGgpzx" src="https://asciinema.org/a/tprMH2EdkUoMb7D2YxgMGgpzx.js" async></script>
@endhtmlonly