zhangyiss/FTXUI
1
0
Fork 0
mirror of https://github.com/ArthurSonzogni/FTXUI.git synced 2025-09-15 07:28:16 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update document WIP.

Browse Source
This commit is contained in:
ArthurSonzogni
2020-05-25 01:34:13 +02:00
committed by Arthur Sonzogni
parent 177df31d41
commit 75c424cea9
55 changed files with 3244 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
doc/CMakeLists.txt Normal file
View File

@@ -0,0 +1,18 @@
find_package(Doxygen)
if (DOXYGEN_FOUND)
configure_file(
${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
@ONLY
)
# note the option ALL which allows to build the docs together with the application
add_custom_target(doc
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
COMMENT "Generating API documentation with Doxygen"
VERBATIM
)
else (DOXYGEN_FOUND)
message("Doxygen need to be installed to generate the doxygen documentation")
endif (DOXYGEN_FOUND)

2502
doc/Doxyfile.in Normal file
View File

File diff suppressed because it is too large Load Diff

52
doc/build-with-cmake.md Normal file
View File

@@ -0,0 +1,52 @@
# Build ftxui and install
~~~bash
mkdir build && cd build
cmake ..
make
sudo make install
~~~
# Example project
main.cpp
~~~cpp
#include "ftxui/screen/screen.hpp"
#include "ftxui/dom/elements.hpp"
#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;
}
~~~
# Add dependency
CMakeLists.txt
~~~cmake
cmake_minimum_required(VERSION 3.0)
find_package(ftxui REQUIRED)
add_executable(main main.cpp)
target_link_libraries(main PUBLIC ftxui::dom)
~~~
# Build
~~~
mkdir build && cd build
cmake ..
make
./main
~~~

39
doc/build-with-nxxm.md Normal file
View File

@@ -0,0 +1,39 @@
# Add dependency
.nxxm/deps
~~~json
{
"ArthurSonzogni/FTXUI": {}
}
~~~
# Example project
main.cpp
~~~cpp
#include "ftxui/screen/screen.hpp"
#include "ftxui/dom/elements.hpp"
#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;
}
~~~
# Build
~~~
nxxm . -t clang-cxx17
~~~

35
doc/example_list.md Normal file
View File

@@ -0,0 +1,35 @@
# Examples
@example ./examples/util/print_key_press.cpp
@example ./examples/dom/dbox.cpp
@example ./examples/dom/separator.cpp
@example ./examples/dom/style_color.cpp
@example ./examples/dom/paragraph.cpp
@example ./examples/dom/style_blink.cpp
@example ./examples/dom/style_dim.cpp
@example ./examples/dom/style_inverted.cpp
@example ./examples/dom/graph.cpp
@example ./examples/dom/package_manager.cpp
@example ./examples/dom/window.cpp
@example ./examples/dom/html_like.cpp
@example ./examples/dom/border.cpp
@example ./examples/dom/style_underlined.cpp
@example ./examples/dom/gauge.cpp
@example ./examples/dom/style_bold.cpp
@example ./examples/dom/spinner.cpp
@example ./examples/dom/style_gallery.cpp
@example ./examples/dom/vbox_hbox.cpp
@example ./examples/dom/size.cpp
@example ./examples/dom/hflow.cpp
@example ./examples/component/tab_vertical.cpp
@example ./examples/component/gallery.cpp
@example ./examples/component/checkbox.cpp
@example ./examples/component/checkbox_in_frame.cpp
@example ./examples/component/menu2.cpp
@example ./examples/component/tab_horizontal.cpp
@example ./examples/component/input.cpp
@example ./examples/component/homescreen.cpp
@example ./examples/component/radiobox.cpp
@example ./examples/component/menu.cpp
@example ./examples/component/menu_style.cpp
@example ./examples/component/radiobox_in_frame.cpp
@example ./examples/component/toggle.cpp

BIN
doc/logo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.7 KiB

268
doc/mainpage.md Normal file
View File

@@ -0,0 +1,268 @@
\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(), Dimension::Fit(document));
Render(screen, document);
std::cout << screen.ToString() << std::endl;
return EXIT_SUCCESS;
}
```
**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:
~~~cpp
#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;
}
~~~
## dom
This module defines a hierachical set of Element. An element manages layout and can be responsive to the terminal dimensions.
They are declared in ftxui/dom/elements.hpp>
\include ftxui/dom/elements.hpp
### text
The most simple widget. It displays a text.
~~~cpp
using namespace ftxui;
text(L"I am a piece of text");
~~~
~~~bash
I am a piece of text.
~~~
### border
Add a border around an element
~~~cpp
using namespace ftxui;
border(text(L"The element"))
~~~
~~~bash
┌───────────┐
│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
[![asciicast](https://asciinema.org/a/223726.svg)](https://asciinema.org/a/223726)
### 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 │
└────┘└───────────────────────────────────┘└───────────────────────────────────┘
~~~
## Components.
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
[![asciicast](https://asciinema.org/a/223719.svg)](https://asciinema.org/a/223719)
### Menu
[![asciicast](https://asciinema.org/a/223720.svg)](https://asciinema.org/a/223720)
### Toggle.
[![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)

289
doc/tutorial.md Normal file
View File

@@ -0,0 +1,289 @@
## Introduction
The library is split in 3 parts:
1. ftxui/screen/
2. ftxui/dom/
3. ftxui/component/
# ftxui/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:
~~~cpp
#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;
}
~~~
2. [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.
3. [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.
~~~cpp
using namespace ftxui;
auto document = text(L"Hello world");
auto screen = Screen::Create(Dimension::Fit(document));
Render(screen, document);
std::cout << screen.ToString();
~~~
I recommand not to take too much time reading the tutorial. Instead,
you should try to read the examples (in [../examples/](../examples)).
## DOM
All the dom element are declared in one header:
\include ./ftxui/dom/elements.hpp
It declares the following set of elements:
~~~cpp
// --- Widget ---
Element text(std::wstring text);
Element separator();
Element separator(Pixel);
Element gauge(float ratio);
Element border(Element);
Decorator borderWith(Pixel);
Element window(Element title, Element content);
Element spinner(int charset_index, size_t image_index);
Elements paragraph(std::wstring text); // Use inside hflow(). Split by space.
Element graph(GraphFunction);
// -- Decorator ---
Element bold(Element);
Element dim(Element);
Element inverted(Element);
Element underlined(Element);
Element blink(Element);
Decorator color(Color);
Decorator bgcolor(Color);
Element color(Color, Element);
Element bgcolor(Color, Element);
// --- Layout ---
// Horizontal, Vertical or stacked set of elements.
Element hbox(Elements);
Element vbox(Elements);
Element dbox(Elements);
Element hflow(Elements);
// -- Flexibility ---
// Define how to share the remaining space when not all of it is used inside a
// container.
Element filler();
Element flex(Element);
Element notflex(Element);
// -- Size override;
enum Direction { WIDTH, HEIGHT };
enum Constraint { LESS_THAN, EQUAL, GREATER_THAN };
Decorator size(Direction, Constraint, int value);
// --- 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 --------------------------------------------------------------------
Element hcenter(Element);
Element vcenter(Element);
Element center(Element);
Element align_right(Element);
Element nothing(Element element);
~~~
### Widget.
#### text
The most simple widget. It displays a text.
~~~cpp
using namespace ftxui;
text(L"I am a piece of text");
~~~
~~~bash
I am a piece of text.
~~~
#### border
Add a border around an element
~~~cpp
using namespace ftxui;
border(text(L"The element"))
~~~
~~~bash
┌───────────┐
│The element│
└───────────┘
~~~
#### separator
Display a vertical or horizontal line to visually split the content of a
container in two.
~~~cpp
border(
hbox({
vbox({
text(L"left top"),
text(L"left bottom"),
}),
separator(),
vbox({
text(L"right top"),
text(L"right bottom"),
}),
})
);
~~~
~~~bash
┌───────────┬────────────┐
│left top │right top │
│left bottom│right bottom│
└───────────┴────────────┘
~~~
#### gauge
A gauge. It can be used to represent a progress bar.
~~~cpp
border(gauge(0.5))
~~~
~~~bash
┌────────────────────────────────────────────────────────────────────────────┐
│██████████████████████████████████████ │
└────────────────────────────────────────────────────────────────────────────┘
~~~
#### graph
[![asciicast](https://asciinema.org/a/223726.svg)](https://asciinema.org/a/223726)
### 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 │
└────┘└───────────────────────────────────┘└───────────────────────────────────┘
~~~
## Components.
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
[![asciicast](https://asciinema.org/a/223719.svg)](https://asciinema.org/a/223719)
![asciicast](https://asciinema.org/a/223719.svg)
### Menu
[![asciicast](https://asciinema.org/a/223720.svg)](https://asciinema.org/a/223720)
### Toggle.
[![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)