From a8eda59d9894e31c02c00812e80bd3b79f2ccdfe Mon Sep 17 00:00:00 2001 From: ArthurSonzogni Date: Sat, 31 May 2025 23:19:18 +0200 Subject: [PATCH] Improve/Fix the documentation page. --- doc/CMakeLists.txt | 14 ++- doc/Doxyfile.in | 39 +++--- doc/DoxygenLayout.xml | 271 ++++++++++++++++++++++++++++++++++++++++ doc/header.html | 80 +++++++++--- doc/introduction.md | 13 ++ doc/module-component.md | 42 ++++--- doc/module-dom.md | 38 +++--- doc/module-screen.md | 4 +- doc/module.md | 39 ++++-- doc/stylesheet.css | 2 +- 10 files changed, 459 insertions(+), 83 deletions(-) create mode 100644 doc/DoxygenLayout.xml diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ce0f3ad8..fbbf567e 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -35,16 +35,26 @@ foreach(example IN LISTS EXAMPLES) endforeach() macro(write_example_list file title page examples) - file(APPEND "${file}" "@page ${page} ${title}\n") + file(WRITE "${file}" "@page ${page} ${title}\n") file(APPEND "${file}" "@tableofcontents\n") foreach(example IN LISTS ${examples}) get_filename_component(name "${example}" NAME_WE) file(APPEND "${file}" "# ${name}\n") + + # Add a markdown to the demo. URL example: + # https://arthursonzogni.github.io/FTXUI/examples/?file=component/canvas_animated + file(APPEND "${file}" "[Demo](https://arthursonzogni.github.io/FTXUI/examples/?file=${example})\n") + file(APPEND "${file}" "@include examples/${example}.cpp\n") - file(APPEND "${file}" "@example examples/${example}.cpp\n") + file(APPEND "${file}" "\n") endforeach() + # Reference to the examples + foreach(example IN LISTS ${examples}) + get_filename_component(name "${example}" NAME_WE) + file(APPEND "${file}" "@example examples/${example}.cpp\n") + endforeach() endmacro() write_example_list("${CMAKE_CURRENT_BINARY_DIR}/dom_examples.md" diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 196be529..d51bbbbf 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -157,7 +157,7 @@ ABBREVIATE_BRIEF = "The $name class" \ # description. # The default value is: NO. -ALWAYS_DETAILED_SEC = NO +ALWAYS_DETAILED_SEC = YES # If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all # inherited members of a class in the documentation of that class as if those @@ -285,6 +285,8 @@ TAB_SIZE = 2 # @} or use a double escape (\\{ and \\}) ALIASES = +ALIASES += iframe{1}="
" + # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -292,7 +294,7 @@ ALIASES = # members will be omitted, etc. # The default value is: NO. -OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_FOR_C = NO # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or # Python sources only. Doxygen will then generate output that is more tailored @@ -343,7 +345,8 @@ OPTIMIZE_OUTPUT_SLICE = NO # # Note see also the list of default file extension mappings. -EXTENSION_MAPPING = md=Markdown +EXTENSION_MAPPING = + # If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments # according to the Markdown format, which allows for more readable @@ -362,7 +365,7 @@ MARKDOWN_SUPPORT = YES # Minimum value: 0, maximum value: 99, default value: 5. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -TOC_INCLUDE_HEADINGS = 3 +TOC_INCLUDE_HEADINGS = 5 # The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to # generate identifiers for the Markdown headings. Note: Every identifier is @@ -373,7 +376,7 @@ TOC_INCLUDE_HEADINGS = 3 # The default value is: DOXYGEN. # This tag requires that the tag MARKDOWN_SUPPORT is set to YES. -MARKDOWN_ID_STYLE = DOXYGEN +MARKDOWN_ID_STYLE = GITHUB # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can @@ -397,7 +400,7 @@ BUILTIN_STL_SUPPORT = YES # enable parsing support. # The default value is: NO. -CPP_CLI_SUPPORT = YES +CPP_CLI_SUPPORT = NO # Set the SIP_SUPPORT tag to YES if your project consists of sip (see: # https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen @@ -415,7 +418,7 @@ SIP_SUPPORT = NO # should set this option to NO. # The default value is: YES. -IDL_PROPERTY_SUPPORT = YES +IDL_PROPERTY_SUPPORT = NO # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES then doxygen will reuse the documentation of the first @@ -471,7 +474,7 @@ INLINE_SIMPLE_STRUCTS = NO # types are typedef'ed and only the typedef is referenced, never the tag name. # The default value is: NO. -TYPEDEF_HIDES_STRUCT = NO +TYPEDEF_HIDES_STRUCT = YES # The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This # cache is used to resolve symbols given their name and scope. Since this can be @@ -497,7 +500,7 @@ LOOKUP_CACHE_SIZE = 0 # DOT_NUM_THREADS setting. # Minimum value: 0, maximum value: 32, default value: 1. -NUM_PROC_THREADS = 1 +NUM_PROC_THREADS = 4 # If the TIMESTAMP tag is set different from NO then each generated page will # contain the date or date and time when the page was generated. Setting this to @@ -816,7 +819,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/doxygen_layout.xml +LAYOUT_FILE = @CMAKE_CURRENT_SOURCE_DIR@/DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -949,11 +952,13 @@ INPUT = \ @CMAKE_CURRENT_SOURCE_DIR@/getting-started.md \ @CMAKE_CURRENT_SOURCE_DIR@/installation.md \ @CMAKE_CURRENT_SOURCE_DIR@/module.md \ + @CMAKE_CURRENT_SOURCE_DIR@/module-screen.md \ + @CMAKE_CURRENT_SOURCE_DIR@/module-dom.md \ + @CMAKE_CURRENT_SOURCE_DIR@/module-component.md \ @CMAKE_CURRENT_SOURCE_DIR@ \ @CMAKE_SOURCE_DIR@/include \ @CMAKE_SOURCE_DIR@/src \ @CMAKE_CURRENT_BINARY_DIR@ \ - @CMAKE_SOURCE_DIR@/CHANGELOG.md \ @CMAKE_SOURCE_DIR@/examples \ # This tag can be used to specify the character encoding of the source files @@ -1166,7 +1171,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = introduction.md +USE_MDFILE_AS_MAINPAGE = @CMAKE_CURRENT_SOURCE_DIR@/introduction.md # The Fortran standard specifies that for fixed formatted Fortran code all # characters from position 72 are to be considered as comment. A common @@ -1272,7 +1277,7 @@ VERBATIM_HEADERS = YES # classes, structs, unions or interfaces. # The default value is: YES. -ALPHABETICAL_INDEX = YES +ALPHABETICAL_INDEX = NO # The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) # that should be ignored while generating the index headers. The IGNORE_PREFIX @@ -1725,7 +1730,7 @@ FULL_SIDEBAR = YES # Minimum value: 0, maximum value: 20, default value: 4. # This tag requires that the tag GENERATE_HTML is set to YES. -ENUM_VALUES_PER_LINE = 4 +ENUM_VALUES_PER_LINE = 1 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used # to set the initial width (in pixels) of the frame in which the tree is shown. @@ -2227,7 +2232,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = YES +GENERATE_XML = NO # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -2560,7 +2565,7 @@ CLASS_GRAPH = YES # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -COLLABORATION_GRAPH = YES +COLLABORATION_GRAPH = NO # If the GROUP_GRAPHS tag is set to YES then doxygen will generate a graph for # groups, showing the direct groups dependencies. Explicit enabling a group @@ -2645,7 +2650,7 @@ INCLUDE_GRAPH = NO # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. -INCLUDED_BY_GRAPH = YES +INCLUDED_BY_GRAPH = NO # If the CALL_GRAPH tag is set to YES then doxygen will generate a call # dependency graph for every global function or class method. diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml new file mode 100644 index 00000000..0ab63264 --- /dev/null +++ b/doc/DoxygenLayout.xml @@ -0,0 +1,271 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/header.html b/doc/header.html index 3a7e64d9..5ea4bb59 100644 --- a/doc/header.html +++ b/doc/header.html @@ -20,32 +20,78 @@ - + $treeview $search $mathjax diff --git a/doc/introduction.md b/doc/introduction.md index c3d96bd8..299087c5 100644 --- a/doc/introduction.md +++ b/doc/introduction.md @@ -73,3 +73,16 @@ Expected output: | [Getting Started](getting-started.html) | + +@defgroup screen ftxui/screen + +Please check the [tutorial](module-screen.html) of the `ftxui/screen` module. + +@defgroup dom ftxui/dom + +Please check the [tutorial](module-dom.html) of the `ftxui/dom` module. + +@defgroup component ftxui/component + +Please check the [tutorial](module-component.html) of the `ftxui/component` +module. diff --git a/doc/module-component.md b/doc/module-component.md index 2cd09a9c..a280fbfa 100644 --- a/doc/module-component.md +++ b/doc/module-component.md @@ -1,6 +1,8 @@ -@page module-component Module component +@page module-component ftxui / component @tableofcontents +![title-img](https://nsm09.casimages.com/img/2025/05/31//2505310207423242518595349.png) + The `ftxui::component` module defines the logic that produces interactive components that respond to user events (keyboard, mouse, etc.). @@ -27,9 +29,9 @@ frame, and updating its state on events. All predefined components are available in ["ftxui/dom/component.hpp"](./component_8hpp.html) -\include{strip ftxui/component/component.hpp +\include ftxui/component/component.hpp -## Input {#component-input} +# Input {#component-input} [Example](https://arthursonzogni.github.io/FTXUI/examples_2component_2input_8cpp-example.html): @@ -41,7 +43,7 @@ Produced by: `ftxui::Input()` from "ftxui/component/component.hpp" @endhtmlonly -### Filtered input +## Filtered input On can filter out the characters received by the input component, using `ftxui::CatchEvent`. @@ -61,7 +63,7 @@ input |= CatchEvent([&](Event event) { }); ``` -## Menu {#component-menu} +# Menu {#component-menu} Defines a menu object. It contains a list of entries, one of them is selected. @@ -76,7 +78,7 @@ Produced by: `ftxui::Menu()` from "ftxui/component/component.hpp" @endhtmlonly -## Toggle {#component-toggle} +# Toggle {#component-toggle} A special kind of menu. The entries are displayed horizontally. @@ -90,7 +92,7 @@ Produced by: `ftxui::Toggle()` from "ftxui/component/component.hpp" @endhtmlonly -## CheckBox {#component-checkbox} +# CheckBox {#component-checkbox} This component defines a checkbox. It is a single entry that can be turned on/off. @@ -105,7 +107,7 @@ Produced by: `ftxui::Checkbox()` from "ftxui/component/component.hpp" @endhtmlonly -## RadioBox {#component-radiobox} +# RadioBox {#component-radiobox} A radiobutton component. This is a list of entries, where one can be turned on. @@ -119,7 +121,7 @@ Produced by: `ftxui::Radiobox()` from "ftxui/component/component.hpp" @endhtmlonly -## Dropdown {#component-dropdown} +# Dropdown {#component-dropdown} A drop down menu is a component that when checked display a list of element for the user to select one. @@ -130,7 +132,7 @@ the user to select one. Produced by: `ftxui::Dropdown()` from "ftxui/component/component.hpp" -## Slider {#component-slider} +# Slider {#component-slider} Represents a slider object that consists of a range with binned intermediate intervals. It can be created by `ftxui::Slider()`. @@ -141,7 +143,7 @@ intervals. It can be created by `ftxui::Slider()`. Produced by: `ftxui::Slider()` from "ftxui/component/component.hpp" -## Renderer {#component-renderer} +# Renderer {#component-renderer} Produced by: `ftxui::Renderer()` from \ref ftxui/component/component.hpp. This component decorate another one by using a different function to render an @@ -170,7 +172,7 @@ auto component = [...] component = component | border | bold; ``` -## CatchEvent {#component-catchevent} +# CatchEvent {#component-catchevent} Produced by: `ftxui::CatchEvent()` from \ref ftxui/component/component.hpp. This component decorate others, catching events before the underlying component. @@ -200,7 +202,7 @@ component = component ; ``` -## Collapsible {#component-collapsible} +# Collapsible {#component-collapsible} Useful for visual elements whose visibility can be toggle on/off by the user. Essentially, this the combination of the `ftxui::Checkbox()` and @@ -210,7 +212,7 @@ Essentially, this the combination of the `ftxui::Checkbox()` and auto collabsible = Collapsible("Show more", inner_element); ``` -## Maybe {#component-maybe} +# Maybe {#component-maybe} Produced by: `ftxui::Maybe()` from \ref ftxui/component/component.hpp. This component can be utilized to show/hide any other component via a boolean or @@ -237,21 +239,21 @@ component = component ; ``` -## Container {#component-container} +# Container {#component-container} -### Horizontal {#component-horizontal} +## Horizontal {#component-horizontal} Produced by: `ftxui::Container::Horizontal()` from "ftxui/component/component.hpp". It displays a list of components horizontally and handle keyboard/mouse navigation. -### Vertical {#component-vertical} +## Vertical {#component-vertical} Produced by: `ftxui::Container::Vertical()` from "ftxui/component/component.hpp". It displays a list of components vertically and handles keyboard/mouse navigation. -### Tab {#component-tab} +## Tab {#component-tab} Produced by: `ftxui::Container::Tab()` from "ftxui/component/component.hpp". It take a list of component and display only @@ -266,7 +268,7 @@ one of them. This is useful for implementing a tab bar. ![ezgif com-gif-maker (2)](https://user-images.githubusercontent.com/4759106/147250217-fe447e0f-7a99-4e08-948a-995087d9b40e.gif) -## ResizableSplit {#component-resizable-split} +# ResizableSplit {#component-resizable-split} It defines a horizontal or vertical separation between two children components. The position of the split is variable and controllable using the mouse. @@ -285,7 +287,7 @@ from "ftxui/component/component.hpp" @endhtmlonly -## Force a frame redraw. {#component-force-redraw} +# Force a frame redraw. {#component-force-redraw} Typically, `ftxui::ScreenInteractive::Loop()` is responsible for drawing a new frame whenever a new group of events (e.g keyboard, mouse, window resize, etc.) diff --git a/doc/module-dom.md b/doc/module-dom.md index 4bf8f3ac..a531eadc 100644 --- a/doc/module-dom.md +++ b/doc/module-dom.md @@ -1,6 +1,8 @@ -@page module-dom Module dom +@page module-dom ftxui / dom @tableofcontents +![title-img](https://nsm09.casimages.com/img/2025/05/31//2505310207423242518595347.png) + This module defines a hierarchical set of `ftxui::Element`. An element manages the layout and can be responsive to the terminal dimension changes. Note the following example where this module is used to create a simple layout with a @@ -43,7 +45,7 @@ corresponding header file: \include{strip} "ftxui/dom/elements.hpp" -## text ## {#dom-text} +# text # {#dom-text} The most simple widget. It displays a text. ```cpp @@ -53,7 +55,7 @@ text("I am a piece of text"); I am a piece of text. ``` -## vtext {#dom-vtext} +# vtext {#dom-vtext} Identical to `ftxui::text`, but displayed vertically. @@ -71,7 +73,7 @@ L O ``` -## paragraph {#dom-paragraph} +# paragraph {#dom-paragraph} Similar to `ftxui::text`, but the individual word are wrapped along multiple lines, depending on the width of its container. @@ -95,7 +97,7 @@ namespace ftxui { ``` -## border {#dom-border} +# border {#dom-border} Adds a border around an element. @@ -134,7 +136,7 @@ namespace ftxui { ``` -## window ## {#dom-window} +# window # {#dom-window} A `ftxui::window` is a `ftxui::border`, but with an additional header. To add a window around an element, wrap it and specify a string as the header. @@ -150,7 +152,7 @@ Terminal output: └───────────┘ ``` -## separator {#dom-separator} +# separator {#dom-separator} Displays a vertical/horizontal line to visually split the content of a container in two. @@ -196,7 +198,7 @@ namespace ftxui { } ``` -## gauge {#dom-gauge} +# gauge {#dom-gauge} This is a visual element that represents a ratio of progress. @@ -224,7 +226,7 @@ namespace { } ``` -## graph {#dom-graph} +# graph {#dom-graph} @htmlonly @@ -235,7 +237,7 @@ See: Element graph(GraphFunction); ``` -## Colors {#dom-colors} +# Colors {#dom-colors} Most terminal consoles can display colored text and colored backgrounds. FTXUI supports every color palette: @@ -248,7 +250,7 @@ Decorator bgcolor(Color); Color [gallery](https://arthursonzogni.github.io/FTXUI/examples_2dom_2color_gallery_8cpp-example.html): ![image](https://user-images.githubusercontent.com/4759106/147248595-04c7245a-5b85-4544-809d-a5984fc6f9e7.png) -### Palette16 #{#dom-colors-palette-16} +## Palette16 #{#dom-colors-palette-16} On most terminals the following colors are supported: - Default @@ -284,7 +286,7 @@ text("Blue background") | bgcolor(Color::Blue); text("Black on white") | color(Color::Black) | bgcolor(Color::White); ``` -### Palette256 #{#dom-colors-palette-256} +## Palette256 #{#dom-colors-palette-256} On terminal supporting 256 colors. @htmlonly @@ -295,7 +297,7 @@ On terminal supporting 256 colors. text("HotPink") | color(Color::HotPink); ``` -### TrueColor #{#dom-colors-true-color} +## TrueColor #{#dom-colors-true-color} On terminal supporting trueColor, you can directly use the 24bit RGB color space: @@ -314,7 +316,7 @@ ftxui::Color::HSV(uint8_t hue, uint8_t saturation, uint8_t value); @endhtmlonly -## LinearGradient #{#dom-linear-gradient} +# LinearGradient #{#dom-linear-gradient} FTXUI supports linear gradient. Either on the foreground or the background. @@ -344,7 +346,7 @@ LinearGradient(45, Color::Red, Color::Blue); See [demo](https://arthursonzogni.github.io/FTXUI/examples/?file=component/linear_gradient_gallery). -## Style {#dom-style} +# Style {#dom-style} In addition to colored text and colored backgrounds. Many terminals support text effects such as: `bold`, `italic`, `dim`, `underlined`, `inverted`, `blink`. @@ -377,7 +379,7 @@ Alternatively, use the pipe operator to chain it on your element: text("This text is bold") | bold | underlined ``` -## Layout {#dom-layout} +# Layout {#dom-layout} Enables elements to be arranged in the following ways: - **Horizontally** with `ftxui::hbox` @@ -438,7 +440,7 @@ Terminal output: └────┘└───────────────────────────────┘└───────────────────────────────┘ ``` -## Table {#dom-table} +# Table {#dom-table} Enables easy formatting of data into a neat table like visual form. @@ -446,7 +448,7 @@ Enables easy formatting of data into a neat table like visual form. ![image](https://user-images.githubusercontent.com/4759106/147250766-77d8ec9e-cf2b-486d-9866-1fd9f1bd2e6b.png) -## Canvas {#dom-canvas} +# Canvas {#dom-canvas} See the API [](./canvas_8hpp_source.html) diff --git a/doc/module-screen.md b/doc/module-screen.md index 4b51e735..0bad56b4 100644 --- a/doc/module-screen.md +++ b/doc/module-screen.md @@ -1,6 +1,8 @@ -@page module-screen Module screen +@page module-screen ftxui / screen @tableofcontents +![title-img](https://nsm09.casimages.com/img/2025/05/31//2505310207423242518595348.png) + The `ftxui::screen` module is the low-level foundation. It can be used standalone, but it is primarily designed to be used together by [ftxui::dom](module-dom.html) and [ftxui::component](module-component.html) diff --git a/doc/module.md b/doc/module.md index cdf58eda..91be215f 100644 --- a/doc/module.md +++ b/doc/module.md @@ -4,13 +4,13 @@ FTXUI is organized into three modules, each building upon the previous: -1. @subpage module-screen — low-level rendering -2. @subpage module-dom — layout and composition -3. @subpage module-component — user interaction +1. [ftxui/screen](#module-screen) - Low-level rendering +2. [ftxui/dom](#module-dom) - Layout and composition +3. [ftxui/component](#module-component) - User interaction --- -[ @subpage module-screen ] +# ftxui/screen Defines: @@ -20,9 +20,18 @@ Defines: Use for direct terminal drawing and styling. +
+ +| Next | +|--------------------------------------:| +| [Documentation](module-screen.html) | + +
+ + --- -[ @subpage module-dom ] +# ftxui/dom Provides: @@ -32,9 +41,17 @@ Provides: Ideal for structured, styled UIs. ---- +
-[ @subpage module-component ] +| Next | +|--------------------------------------:| +| [Documentation](module-dom.html) | + +
+ + +--- +# ftxui/component Adds: @@ -44,6 +61,14 @@ Adds: Use for interactive apps. +
+ +| Next | +|--------------------------------------:| +| [Documentation](module-component.html) | + +
+ --- Modules can be used independently, or together: `screen → dom → component`. diff --git a/doc/stylesheet.css b/doc/stylesheet.css index 33f14a04..7571a3ee 100644 --- a/doc/stylesheet.css +++ b/doc/stylesheet.css @@ -22,7 +22,7 @@ html { --warning-color-darker: #f7768e; --bug-color: #f7768e; - --fragment-background: #2c2e34; + --fragment-background: #222222; --fragment-foreground: #e2e2e3; --fragment-keyword: #f7768e; /* pink */ --fragment-keywordtype: #7fbbb3; /* teal */