mirror of
https://github.com/ArthurSonzogni/FTXUI.git
synced 2024-11-30 07:26:51 +08:00
472 lines
11 KiB
Markdown
472 lines
11 KiB
Markdown
\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>
|
||
#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(), // Width
|
||
Dimension::Fit(document) // Height
|
||
);
|
||
Render(screen, document);
|
||
std::cout << screen.ToString() << std::endl;
|
||
|
||
return EXIT_SUCCESS;
|
||
}
|
||
```
|
||
|
||
**output**
|
||
```bash
|
||
┌────┐┌─────────────────────────────────────────────────────────────────┐┌─────┐
|
||
│left││middle ││right│
|
||
└────┘└─────────────────────────────────────────────────────────────────┘└─────┘
|
||
```
|
||
|
||
**cmake**
|
||
```c
|
||
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)
|
||
```
|
||
|
||
# List of modules.
|
||
|
||
The project is split into 3 modules:
|
||
|
||
1. **ftxui/screen** defines a ftxui::Screen, this is a grid of ftxui::Pixel.
|
||
|
||
2. **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.
|
||
|
||
3. **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 associated style (bold, colors, etc...).
|
||
The screen can be printed as a string using ftxui::Screen::ToString().
|
||
|
||
~~~cpp
|
||
#include <ftxui/screen/screen.hpp>
|
||
|
||
int main(void) {
|
||
using namespace ftxui;
|
||
auto screen = Screen(Dimension::Fixed(32), Dimension::Fixed(10));
|
||
|
||
auto& pixel = screen.PixelAt(10,10);
|
||
pixel.character = U'A';
|
||
pixel.bold = true;
|
||
pixel.foreground_color = Color::Blue;
|
||
|
||
std::cout << screen.ToString();
|
||
return EXIT_SUCCESS;
|
||
}
|
||
~~~
|
||
|
||
## dom
|
||
|
||
This module defines a hierachical set of Element. An element manages layout and can be responsive to the terminal dimensions.
|
||
|
||
|
||
**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
|
||
|
||
## component
|
||
|
||
Finally, the ftxui/component directory defines the logic to get interactivity.
|
||
|
||
Please take a look at ./examples/component
|
||
|
||
This provides:
|
||
1. A main loop.
|
||
2. Get events and respond to them.
|
||
3. A predefined implementation of "keyboard navigation".
|
||
4. A set of predefined widget: CheckBox, RadioBox, Input, Menu, Toggle.
|
||
|
||
# ftxui/dom
|
||
|
||
Every elements of the dom are declared from:
|
||
\ref ftxui/dom/elements.hpp
|
||
|
||
## text
|
||
|
||
The most simple widget. It displays a text.
|
||
~~~cpp
|
||
text(L"I am a piece of text");
|
||
~~~
|
||
~~~bash
|
||
I am a piece of text.
|
||
~~~
|
||
|
||
## border
|
||
|
||
Add a border around an element
|
||
~~~cpp
|
||
border(text(L"The element"))
|
||
~~~
|
||
|
||
~~~bash
|
||
┌───────────┐
|
||
│The element│
|
||
└───────────┘
|
||
~~~
|
||
|
||
## 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.
|
||
|
||
~~~cpp
|
||
border(
|
||
hbox({
|
||
text(L"Left"),
|
||
separator(),
|
||
text(L"Right")
|
||
})
|
||
)
|
||
~~~
|
||
|
||
~~~bash
|
||
┌────┬─────┐
|
||
│left│right│
|
||
└────┴─────┘
|
||
~~~
|
||
|
||
## gauge
|
||
|
||
A gauge. It can be used to represent a progress bar.
|
||
~~~cpp
|
||
border(gauge(0.5))
|
||
~~~
|
||
|
||
~~~bash
|
||
┌────────────────────────────────────────────────────────────────────────────┐
|
||
│██████████████████████████████████████ │
|
||
└────────────────────────────────────────────────────────────────────────────┘
|
||
~~~
|
||
|
||
## graph
|
||
@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);
|
||
~~~
|
||
|
||
The following colors are available:
|
||
- Default
|
||
|
||
- Black
|
||
- GrayDark
|
||
- GrayLight
|
||
|
||
- White
|
||
|
||
- Blue
|
||
- BlueLight
|
||
|
||
- 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);
|
||
```
|
||
|
||
## 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);
|
||
~~~
|
||
|
||
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
|
||
~~~
|
||
|
||
## 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 │
|
||
└────┘└───────────────────────────────────┘└───────────────────────────────────┘
|
||
~~~
|
||
|
||
# ftxui/component
|
||
|
||
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.
|
||
|
||
## Input
|
||
|
||
The component: \ref ftxui::Input
|
||
|
||
@htmlonly
|
||
<script id="asciicast-223719" src="https://asciinema.org/a/223719.js" async></script>
|
||
@endhtmlonly
|
||
|
||
## Menu
|
||
|
||
The component: \ref ftxui::Menu
|
||
|
||
@htmlonly
|
||
<script id="asciicast-223720" src="https://asciinema.org/a/223720.js" async></script>
|
||
@endhtmlonly
|
||
|
||
## Toggle.
|
||
|
||
The component: \ref ftxui::Toggle
|
||
|
||
@htmlonly
|
||
<script id="asciicast-223722" src="https://asciinema.org/a/223722.js" async></script>
|
||
@endhtmlonly
|
||
|
||
## CheckBox
|
||
|
||
The component: \ref ftxui::CheckBox
|
||
|
||
@htmlonly
|
||
<script id="asciicast-223724" src="https://asciinema.org/a/223724.js" async></script>
|
||
@endhtmlonly
|
||
|
||
## RadioBox
|
||
|
||
The component: \ref ftxui::RadioBox
|
||
|
||
@htmlonly
|
||
<script id="asciicast-223725" src="https://asciinema.org/a/223725.js" async></script>
|
||
@endhtmlonly
|
||
|
||
# Build
|
||
|
||
Assuming this example example.cpp file.
|
||
|
||
**main.cpp**
|
||
~~~cpp
|
||
#include "ftxui/screen/screen.c
|
||
#include "ftxui/dom/elements.c
|
||
#include <iostream>
|
||
|
||
int main(int argc, const char *argv[]) {
|
||
using namespace ftxui;
|
||
auto document =
|
||
hbox({
|
||
text(L"left") | bold | border,
|
||
text(L"middle") | flex | border,
|
||
text(L"right") | border,
|
||
});
|
||
auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
|
||
Render(screen, document);
|
||
|
||
std::cout << screen.ToString();
|
||
|
||
return 0;
|
||
}
|
||
~~~
|
||
|
||
## Using CMake
|
||
|
||
CMakeLists.txt
|
||
~~~cmake
|
||
cmake_minimum_required (VERSION 3.11)
|
||
|
||
# --- Fetch FTXUI --------------------------------------------------------------
|
||
include(FetchContent)
|
||
|
||
set(FETCHCONTENT_UPDATES_DISCONNECTED TRUE)
|
||
FetchContent_Declare(ftxui
|
||
GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
|
||
# Specify a GIT TAG here.
|
||
)
|
||
|
||
FetchContent_GetProperties(ftxui)
|
||
if(NOT ftxui_POPULATED)
|
||
FetchContent_Populate(ftxui)
|
||
add_subdirectory(${ftxui_SOURCE_DIR} ${ftxui_BINARY_DIR} EXCLUDE_FROM_ALL)
|
||
endif()
|
||
|
||
# ------------------------------------------------------------------------------
|
||
|
||
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
|
||
PRIVATE ftxui::screen
|
||
PRIVATE ftxui::dom
|
||
PRIVATE ftxui::component # Not needed for this example.
|
||
)
|
||
|
||
# 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
|
||
~~~
|