Update document WIP.

CMakeLists.txt

@@ -7,6 +7,7 @@ project(ftxui
 option(FTXUI_BUILD_EXAMPLES "Set to ON to build examples" ON)
 option(FTXUI_ENABLE_INSTALL "Generate the install target" ON)
 option(FTXUI_BUILD_TESTS "Set to ON to build tests" OFF)
+option(FTXUI_BUILD_DOCS "Set to ON to build tests" ON)
 
 enable_testing()
 
@@ -198,3 +199,7 @@ endif()
 if(FTXUI_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()
+
+if(FTXUI_BUILD_DOCS)
+  add_subdirectory(doc)
+endif()

README.md

@@ -58,12 +58,12 @@ A simple C++ library for terminal based user interface.
 
 ## Build
 
-* [CMake](https://cmake.org) →  [Instructions](./tutorial/build-with-cmake.md)
-* [nxxm](https://nxxm.github.io) → [Instructions](./tutorial/build-with-nxxm.md)
+* [CMake](https://cmake.org) →  [Instructions](./doc/build-with-cmake.md)
+* [nxxm](https://nxxm.github.io) → [Instructions](./doc/build-with-nxxm.md)
 
 ## Tutorial
 - [Starter cmake project](https://github.com/ArthurSonzogni/ftxui-starter)
-- [Tutorial](./tutorial/tutorial.md)
+- [Tutorial](./doc/tutorial.md)
 
 ## Project using FTXUI
 

doc/CMakeLists.txt

@@ -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)

doc/example_list.md

@@ -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

doc/mainpage.md

@@ -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)

doc/tutorial.md

@@ -1,45 +1,65 @@
-Table of content:
-=================
-
-- [Introduction](#introduction)
-- [DOM](#dom)
-  * [Widget.](#widget)
-    + [text](#text)
-    + [border](#border)
-    + [separator](#separator) [gauge](#gauge)
-  * [Style](#style)
-  * [Layout](#layout)
-    + [Examples](#examples)
-- [Components.](#components)
-  * [Input](#input)
-  * [Menu](#menu)
-  * [Toggle.](#toggle)
-
 ## Introduction
-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.
+1. ftxui/screen/
+2. ftxui/dom/
+3. ftxui/component/
 
-- [ftuix/dom/](../include/ftxui/dom/)
+# ftxui/screen/
 
-  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.
+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().
 
-- [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
+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:
-~~~cpp
-#include <ftxui/dom/elements.hpp>
-~~~
+
+\include ./ftxui/dom/elements.hpp
 
 It declares the following set of elements:
 
@@ -108,7 +128,9 @@ Element nothing(Element element);
 
 The most simple widget. It displays a text.
 ~~~cpp
-  text(L"I am a piece of text");
+using namespace ftxui;
+
+text(L"I am a piece of text");
 ~~~
 ~~~bash
 I am a piece of text.
@@ -117,6 +139,8 @@ I am a piece of text.
 #### border
 Add a border around an element
 ~~~cpp
+using namespace ftxui;
+
 border(text(L"The element"))
 ~~~
 
@@ -157,7 +181,7 @@ border(
 #### gauge
 
 A gauge. It can be used to represent a progress bar.
-~~~c+
+~~~cpp
 border(gauge(0.5))
 ~~~
 
@@ -250,6 +274,7 @@ 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)

examples/dom/CMakeLists.txt

@@ -23,3 +23,4 @@ example(vbox_hbox)
 example(hflow)
 example(paragraph)
 example(html_like)
+example(window)

examples/dom/border.cpp

@@ -3,40 +3,32 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
-  auto document = hbox({
-      window(text(L" main frame ") | hcenter,
+  auto document =  //
+      hbox({
           vbox({
               text(L"Line 1"),
               text(L"Line 2"),
               text(L"Line 3"),
+          }) | border,
+
           vbox({
               text(L"Line 4"),
               text(L"Line 5"),
               text(L"Line 6"),
           }) | border,
-                 hbox({
-                     window(text(L"frame 2"), vbox({
-                                                  text(L"Line 4"),
-                                                  text(L"Line 5"),
-                                                  text(L"Line 6"),
-                                              })),
-                     window(text(L"frame 3"), vbox({
+
+          vbox({
               text(L"Line 7"),
               text(L"Line 8"),
               text(L"Line 9"),
-                                              })),
-                 }),
-                 text(L"footer footer footer footer footer"),
-             })),
-      filler(),
+          }) | border,
       });
   auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
   Render(screen, document);

examples/dom/dbox.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document = dbox({

examples/dom/gauge.cpp

@@ -3,12 +3,11 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   using namespace std::chrono_literals;

examples/dom/graph.cpp

@@ -4,13 +4,12 @@
 
 #include <chrono>
 #include <cmath>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 class Graph {
  public:
   std::vector<int> operator()(int width, int height) {

examples/dom/hflow.cpp

@@ -2,12 +2,11 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto make_box = [](size_t dimx, size_t dimy) {

examples/dom/html_like.cpp

@@ -3,13 +3,12 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   using namespace std::chrono_literals;

examples/dom/package_manager.cpp

@@ -3,14 +3,15 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 #include <list>
 #include <thread>
 #include <vector>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
+/// @example examples/dom/package_manage.cpp
 
 int main(int argc, const char* argv[]) {
   using namespace ftxui;

examples/dom/paragraph.cpp

@@ -2,12 +2,11 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   std::wstring p =

examples/dom/separator.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document = hbox({

examples/dom/size.cpp

@@ -2,12 +2,11 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto make_box = [](const std::wstring title) {

examples/dom/spinner.cpp

@@ -3,13 +3,12 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-#include "ftxui/screen/string.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   using namespace std::chrono_literals;

examples/dom/style_blink.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document =  //

examples/dom/style_bold.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document =  //

examples/dom/style_color.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   // clang-format off

examples/dom/style_dim.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document =  //

examples/dom/style_gallery.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   // clang-format off

examples/dom/style_inverted.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document = hbox({

examples/dom/style_underlined.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document =  //

examples/dom/vbox_hbox.cpp

@@ -2,11 +2,10 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
 #include <iostream>
 
-#include "ftxui/dom/elements.hpp"
-#include "ftxui/screen/screen.hpp"
-
 int main(int argc, const char* argv[]) {
   using namespace ftxui;
   auto document =  //

examples/dom/window.cpp

@@ -0,0 +1,15 @@
+// Copyright 2020 Arthur Sonzogni. All rights reserved.
+// Use of this source code is governed by the MIT license that can be found in
+// the LICENSE file.
+
+#include <ftxui/dom/elements.hpp>
+#include <ftxui/screen/screen.hpp>
+#include <iostream>
+
+int main(int argc, const char* argv[]) {
+  using namespace ftxui;
+  auto document = window(text(L"Title"), text(L"content"));
+  auto screen = Screen::Create(Dimension::Fixed(30), Dimension::Fixed(6));
+  Render(screen, document);
+  std::cout << screen.ToString() << std::endl;
+}

examples/html/test.html.disabled

@@ -26,8 +26,8 @@
   <script type="text/c++">
     #include <iostream>
 
-    #include "ftxui/screen/screen.hpp"
-    #include "ftxui/dom/elements.hpp"
+    #include <ftxui/screen/screen.hpp>
+    #include <ftxui/dom/elements.hpp>
 
     int main() {
       using namespace ftxui;

examples/util/print_key_press.cpp

@@ -3,13 +3,12 @@
 // the LICENSE file.
 
 #include <chrono>
+#include <ftxui/component/component.hpp>
+#include <ftxui/component/screen_interactive.hpp>
+#include <ftxui/screen/string.hpp>
 #include <iostream>
 #include <thread>
 
-#include "ftxui/component/component.hpp"
-#include "ftxui/component/screen_interactive.hpp"
-#include "ftxui/screen/string.hpp"
-
 using namespace ftxui;
 
 class DrawKey : public Component {

include/ftxui/dom/node.hpp

@@ -14,6 +14,7 @@
 
 namespace ftxui {
 
+class Node;
 using Element = std::shared_ptr<Node>;
 using Elements = std::vector<std::shared_ptr<Node>>;
 

include/ftxui/screen/color.hpp

@@ -9,6 +9,8 @@
 
 namespace ftxui {
 
+/// @brief The set of supported terminal colors.
+/// @ingroup screen
 enum class Color : uint8_t {
   // --- Transparent -----
   Default = 39,

include/ftxui/screen/screen.hpp

@@ -17,7 +17,10 @@ class Node;
 }
 
 namespace ftxui {
+using Element = std::shared_ptr<Node>;
 
+/// @brief A unicode character and its associated style.
+/// @ingroup screen
 struct Pixel {
   wchar_t character = U' ';
   bool blink = false;
@@ -29,18 +32,24 @@ struct Pixel {
   Color foreground_color = Color::Default;
 };
 
+/// @brief Define how the Screen's dimensions should look like.
+/// @ingroup screen
 struct Dimension {
+  /// coucou
   static Dimension Fixed(int);
-  static Dimension Fit(std::shared_ptr<Node>&);
+  /// @brief coucou
+  static Dimension Fit(Element&);
   static Dimension Full();
 
   int dimx;
   int dimy;
 };
 
+/// @brief A rectangular grid of Pixel.
+/// @ingroup screen
 class Screen {
  public:
-  // Constructor.
+  // Constructors:
   Screen(int dimx, int dimy);
   static Screen Create(Dimension dimension);
   static Screen Create(Dimension width, Dimension height);

other/format.sh

@@ -17,3 +17,11 @@ for file in $files
 do
   clang-format -i $file
 done
+
+exampleList="./doc/example_list.md"
+echo "# Examples" > $exampleList
+files=$(find ./examples/ -iname "*.cpp")
+for f in $files
+do
+  echo "@example $f" >> $exampleList
+done

src/ftxui/dom/blink.cpp

@@ -22,6 +22,8 @@ class Blink : public NodeDecorator {
   }
 };
 
+/// @brief The text drawn alternate in between visible and hidden.
+/// @ingroup dom
 Element blink(Element child) {
   return std::make_shared<Blink>(unpack(std::move(child)));
 }

src/ftxui/dom/bold.cpp

@@ -22,6 +22,8 @@ class Bold : public NodeDecorator {
   }
 };
 
+/// @brief Use a bold font, for elements with more emphasis.
+/// @ingroup dom
 Element bold(Element child) {
   return std::make_shared<Bold>(unpack(std::move(child)));
 }

src/ftxui/dom/border.cpp

@@ -1,7 +1,6 @@
 // Copyright 2020 Arthur Sonzogni. All rights reserved.
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
-
 #include <algorithm>
 
 #include "ftxui/dom/elements.hpp"
@@ -104,15 +103,60 @@ class Border : public Node {
     }
   }
 };
-
+/// @brief Draw a border around the element.
+/// @ingroup dom
+///
+/// Add a border around an element
+///
+/// ### Example
+///
+/// ```cpp
+/// // Use 'border' as a function...
+/// Element document = border(text(L"The element"));
+///
+/// // ...Or as a 'pipe'.
+/// Element document = text(L"The element") | border;
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// ┌───────────┐
+/// │The element│
+/// └───────────┘
+/// ```
 Element border(Element child) {
   return std::make_shared<Border>(unpack(std::move(child)));
 }
 
+/// @brief Draw window with a title and a border around the element.
+/// @param title The title of the window.
+/// @param content The element to be wrapped.
+/// @ingroup dom
+/// @seealso border
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = window(text(L"Title"),
+///                           text(L"content")
+///                    );
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// ┌Title──┐
+/// │content│
+/// └───────┘
+/// ```
 Element window(Element title, Element content) {
   return std::make_shared<Border>(unpack(std::move(content), std::move(title)));
 }
 
+/// @brief Same as border but with a constant Pixel around the element.
+/// @ingroup dom
+/// @seealso border
 Decorator borderWith(Pixel pixel) {
   return [pixel](Element child) {
     return std::make_shared<Border>(unpack(std::move(child)), pixel);

src/ftxui/dom/color.cpp

@@ -42,18 +42,60 @@ class FgColor : public NodeDecorator {
   Color color_;
 };
 
-Element color(Color c, Element child) {
-  return std::make_shared<FgColor>(unpack(std::move(child)), c);
+/// @brief Set the foreground color of an element.
+/// @param The color of the output element.
+/// @param The input element.
+/// @return The output element colored.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = color(Color::Green, text(L"Success")),
+/// ```
+Element color(Color color, Element child) {
+  return std::make_shared<FgColor>(unpack(std::move(child)), color);
 }
 
-Element bgcolor(Color c, Element child) {
-  return std::make_shared<BgColor>(unpack(std::move(child)), c);
+/// @brief Set the background color of an element.
+/// @param The color of the output element.
+/// @param The input element.
+/// @return The output element colored.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = bgcolor(Color::Green, text(L"Success")),
+/// ```
+Element bgcolor(Color color, Element child) {
+  return std::make_shared<BgColor>(unpack(std::move(child)), color);
 }
 
+/// @brief Decorate using a foreground color.
+/// @param c The foreground color to be applied.
+/// @return The Decorator applying the color.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = text(L"red") | color(Color::Red);
+/// ```
 Decorator color(Color c) {
   return [c](Element child) { return color(c, std::move(child)); };
 }
 
+/// @brief Decorate using a background color.
+/// @param The background color to be applied.
+/// @return The Decorator applying the color.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = text(L"red") | bgcolor(Color::Red);
+/// ```
 Decorator bgcolor(Color c) {
   return [c](Element child) { return bgcolor(c, std::move(child)); };
 }

src/ftxui/dom/composite_decorator.cpp

@@ -7,18 +7,34 @@
 
 namespace ftxui {
 
+/// @brief Center an element horizontally.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element hcenter(Element child) {
   return hbox(filler(), std::move(child), filler()) | xflex_grow;
 }
 
+/// @brief Center an element vertically.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element vcenter(Element child) {
   return vbox(filler(), std::move(child), filler()) | yflex_grow;
 }
 
+/// @brief Center an element horizontally and vertically.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element center(Element child) {
   return hcenter(vcenter(std::move(child))) | flex_grow;
 }
 
+/// @brief Align an element on the right side.
+/// @param The input element.
+/// @return The right aligned element.
+/// @ingroup dom
 Element align_right(Element child) {
   return hbox(filler(), std::move(child)) | flex_grow;
 }

src/ftxui/dom/dbox.cpp

@@ -43,6 +43,10 @@ class DBox : public Node {
   }
 };
 
+/// @brief Stack several element on top of each other.
+/// @param The input element.
+/// @return The right aligned element.
+/// @ingroup dom
 Element dbox(Elements children) {
   return std::make_shared<DBox>(std::move(children));
 }

src/ftxui/dom/dim.cpp

@@ -24,6 +24,8 @@ class Dim : public NodeDecorator {
   }
 };
 
+/// @brief Use a light font, for elements with less emphasis.
+/// @ingroup dom
 Element dim(Element child) {
   return std::make_shared<Dim>(unpack(std::move(child)));
 }

src/ftxui/dom/flex.cpp

@@ -83,10 +83,33 @@ class Flex : public Node {
   FlexFunction f_;
 };
 
+/// @brief An element that will take expand proportionnally to the space left in
+/// a container.
+/// @ingroup dom
 Element filler() {
   return std::make_shared<Flex>(function_flex);
 }
 
+/// @brief Make a child element to expand proportionnally to the space left in a
+/// container.
+///
+/// #### Examples:
+///
+/// ~~~cpp
+///   hbox({
+///     text(L"left") | border ,
+///     text(L"middle") | border | flex,
+///     text(L"right") | border,
+///   });
+/// ~~~
+///
+/// #### Output:
+///
+/// ~~~bash
+/// ┌────┐┌─────────────────────────────────────────────────────────┐┌─────┐
+/// │left││middle                                                   ││right│
+/// └────┘└─────────────────────────────────────────────────────────┘└─────┘
+/// ~~~
 Element flex(Element child) {
   return std::make_shared<Flex>(function_flex, std::move(child));
 }

src/ftxui/dom/frame.cpp

@@ -63,7 +63,8 @@ Element focus(Element child) {
 
 class Frame : public Node {
  public:
-  Frame(std::vector<Element> children, bool x_frame, bool y_frame) : Node(std::move(children)), x_frame_(x_frame), y_frame_(y_frame) {}
+  Frame(std::vector<Element> children, bool x_frame, bool y_frame)
+      : Node(std::move(children)), x_frame_(x_frame), y_frame_(y_frame) {}
 
   void ComputeRequirement() override {
     Node::ComputeRequirement();
@@ -109,6 +110,10 @@ class Frame : public Node {
   bool y_frame_;
 };
 
+/// @brief Allow an element to be displayed inside a 'virtual' area. It size can
+/// be larger than its container. In this case only a smaller portion is
+/// displayed. The view is scrollable to make the focused element visible.
+/// @seealso focus
 Element frame(Element child) {
   return std::make_shared<Frame>(unpack(std::move(child)), true, true);
 }

src/ftxui/dom/gauge.cpp

@@ -39,6 +39,24 @@ class Gauge : public Node {
   float progress_;
 };
 
+/// @brief Draw a high definition progress bar.
+/// @param progress The proportion of the area to be filled. Belong to [0,1].
+/// @ingroup dom
+///
+/// ### Example
+///
+/// A gauge. It can be used to represent a progress bar.
+/// ~~~cpp
+/// border(gauge(0.5))
+/// ~~~
+///
+/// #### Output
+///
+/// ~~~bash
+/// ┌──────────────────────────────────────────────────────────────────────────┐
+/// │█████████████████████████████████████                                     │
+/// └──────────────────────────────────────────────────────────────────────────┘
+/// ~~~
 Element gauge(float progress) {
   return std::make_shared<Gauge>(progress);
 }

src/ftxui/dom/graph.cpp

@@ -44,6 +44,8 @@ class Graph : public Node {
   GraphFunction graph_function_;
 };
 
+/// @brief Draw a graph using a GraphFunction.
+/// @param graph_function the function to be called to get the data.
 Element graph(GraphFunction graph_function) {
   return std::make_shared<Graph>(graph_function);
 }

src/ftxui/dom/hbox.cpp

@@ -128,6 +128,18 @@ class HBox : public Node {
   }
 };
 
+/// @brief A container displaying elements horizontally one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// hbox({
+///   text(L"Left"),
+///   text(L"Right"),
+/// });
+/// ```
 Element hbox(Elements children) {
   return std::make_shared<HBox>(std::move(children));
 }

src/ftxui/dom/hflow.cpp

@@ -60,6 +60,18 @@ class HFlow : public Node {
   }
 };
 
+/// @brief A container displaying elements horizontally one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// hbox({
+///   text(L"Left"),
+///   text(L"Right"),
+/// });
+/// ```
 Element hflow(Elements children) {
   return std::make_shared<HFlow>(std::move(children));
 }

src/ftxui/dom/text.cpp

@@ -2,9 +2,9 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <algorithm>
 #include "ftxui/dom/node.hpp"
 #include "ftxui/screen/string.hpp"
-#include <algorithm>
 
 namespace ftxui {
 

src/ftxui/dom/vbox.cpp

@@ -129,6 +129,18 @@ class VBox : public Node {
   }
 };
 
+/// @brief A container displaying elements vertically one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// vbox({
+///   text(L"Up"),
+///   text(L"Down"),
+/// });
+/// ```
 Element vbox(Elements children) {
   return std::make_shared<VBox>(std::move(children));
 }

src/ftxui/screen/screen.cpp

@@ -73,28 +73,33 @@ void WindowsEmulateVT100Terminal() {
 
 }  // namespace
 
+/// A fixed dimension.
 Dimension Dimension::Fixed(int v) {
   return Dimension{v, v};
 }
 
-Dimension Dimension::Fit(std::shared_ptr<Node>& e) {
+/// The minimal dimension that will fit the given element.
+Dimension Dimension::Fit(Element& e) {
   e->ComputeRequirement();
   Terminal::Dimensions size = Terminal::Size();
   return Dimension{std::min(e->requirement().min_x, size.dimx),
                    std::min(e->requirement().min_y, size.dimy)};
 }
 
+/// Use the terminal dimensions.
 Dimension Dimension::Full() {
   Terminal::Dimensions size = Terminal::Size();
   return Dimension{size.dimx, size.dimy};
 }
 
 // static
+/// Create a screen with the given dimension along the x-axis and y-axis.
 Screen Screen::Create(Dimension width, Dimension height) {
   return Screen(width.dimx, height.dimy);
 }
 
 // static
+/// Create a screen with the given dimension.
 Screen Screen::Create(Dimension dimension) {
   return Screen(dimension.dimx, dimension.dimy);
 }
@@ -144,6 +149,7 @@ void UpdatePixelStyle(std::wstringstream& ss, Pixel& previous, Pixel& next) {
   previous = next;
 }
 
+/// Produce a std::string that can be used to print the Screen on the terminal.
 std::string Screen::ToString() {
   std::wstringstream ss;
 
@@ -167,14 +173,39 @@ std::string Screen::ToString() {
   return to_string(ss.str());
 }
 
+/// @brief Access a character a given position.
+/// @param x The character position along the x-axis.
+/// @param y The character position along the y-axis.
 wchar_t& Screen::at(int x, int y) {
   return PixelAt(x, y).character;
 }
 
+/// @brief Access a Pixel at a given position.
+/// @param x The pixel position along the x-axis.
+/// @param y The pixel position along the y-axis.
 Pixel& Screen::PixelAt(int x, int y) {
   return In(stencil, x, y) ? pixels_[y][x] : dev_null_pixel;
 }
 
+/// @brief Return a string to be printed in order to reset the cursor position
+///        to the beginning of the screen.
+///
+/// ```cpp
+/// std::string reset_position;
+/// while(true) {
+///   auto document = render();
+///   auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
+///   Render(screen, document);
+///   std::cout << reset_position << screen.ToString() << std::flush;
+///   reset_position = screen.ResetPosition();
+///
+///   using namespace std::chrono_literals;
+///   std::this_thread::sleep_for(0.01s);
+/// }
+/// ```
+///
+/// @return The string to print in order to reset the cursor position to the
+///         beginning.
 std::string Screen::ResetPosition() {
   std::stringstream ss;
   ss << MOVE_LEFT << CLEAR_LINE;
@@ -184,6 +215,7 @@ std::string Screen::ResetPosition() {
   return ss.str();
 }
 
+/// @brief Clear all the pixel from the screen.
 void Screen::Clear() {
   pixels_ = std::vector<std::vector<Pixel>>(dimy_,
                                             std::vector<Pixel>(dimx_, Pixel()));