From cd828bf94deec2dbc2e9bdcf8be34c1cfcc7e804 Mon Sep 17 00:00:00 2001 From: cmorganBE <51970032+cmorganBE@users.noreply.github.com> Date: Mon, 12 Jul 2021 17:15:44 -0400 Subject: [PATCH] =?UTF-8?q?mainpage.md=20-=20Document=20'refreshing=20/=20?= =?UTF-8?q?invalidating=20the=20screen=20to=20cause=E2=80=A6=20(#147)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a section explaining the use for ScreenInteractive::PostEvent. Co-authored-by: ArthurSonzogni --- doc/mainpage.md | 109 ++++++++++++++++++++++++------------------------ 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/doc/mainpage.md b/doc/mainpage.md index 6f9faa7..68d8b2c 100644 --- a/doc/mainpage.md +++ b/doc/mainpage.md @@ -96,40 +96,26 @@ make ./main ~~~ -## Using NXXM - -**.nxxm/deps** -~~~json -{ - "ArthurSonzogni/FTXUI": {} -} -~~~ - -Build: -~~~ -nxxm . -t clang-cxx17 -~~~ - # List of modules. The project is split into 3 modules: -1. **ftxui/screen** defines a ftxui::Screen, this is a grid of ftxui::Pixel. +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. +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. +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(). +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 @@ -151,8 +137,8 @@ The screen can be printed as a string using ftxui::Screen::ToString(). # dom -This module defines a hierachical set of Element. An element manages layout and can be responsive to the terminal dimensions. - +This module defines a hierarchical set of Element. An element manages layout and +can be responsive to the terminal dimensions. **Example:** ```cpp @@ -198,7 +184,7 @@ border(text(L"The element")) ## window -A ftxui::window is a ftxui::border, but with some text on top of the border. +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")) @@ -290,7 +276,7 @@ On most terminal the following colors are supported: Example: ```cpp text(L"Blue foreground") | color(Color::Blue); -text(L"Blue backgrond") | bgcolor(Color::Blue); +text(L"Blue background") | bgcolor(Color::Blue); text(L"Black on white") | color(Color::Black) | bgcolor(Color::White); ``` @@ -355,8 +341,8 @@ 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 +`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: @@ -395,13 +381,13 @@ An horizontal flow layout is implemented by: 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::ScreenInteractive` defines a main loop to render a component. -A ftxui::Component is a shared pointer to a ftxui::ComponentBase. The later +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 + - `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. @@ -415,7 +401,7 @@ its keyboard. They handle keyboard navigation, including component focus. ## Input -Produced by: ftxui::Input() from "ftxui/component/component.hpp" +Produced by: `ftxui::Input()` from "ftxui/component/component.hpp" @htmlonly @@ -423,7 +409,7 @@ Produced by: ftxui::Input() from "ftxui/component/component.hpp" ## Menu -Produced by: ftxui::Menu() from "ftxui/component/component.hpp" +Produced by: `ftxui::Menu()` from "ftxui/component/component.hpp" @htmlonly @@ -431,7 +417,7 @@ Produced by: ftxui::Menu() from "ftxui/component/component.hpp" ## Toggle. -Produced by: ftxui::Toggle() from "ftxui/component/component.hpp" +Produced by: `ftxui::Toggle()` from "ftxui/component/component.hpp" @htmlonly @@ -439,7 +425,7 @@ Produced by: ftxui::Toggle() from "ftxui/component/component.hpp" ## CheckBox -Produced by: ftxui::Checkbox() from "ftxui/component/component.hpp" +Produced by: `ftxui::Checkbox()` from "ftxui/component/component.hpp" @htmlonly @@ -447,7 +433,7 @@ Produced by: ftxui::Checkbox() from "ftxui/component/component.hpp" ## RadioBox -Produced by: ftxui::Radiobox() from "ftxui/component/component.hpp" +Produced by: `ftxui::Radiobox()` from "ftxui/component/component.hpp" @htmlonly @@ -455,48 +441,63 @@ Produced by: ftxui::Radiobox() from "ftxui/component/component.hpp" ## Renderer -Produced by: ftxui::Renderer() from \ref "ftxui/component/component.hpp". This +Produced by: `ftxui::Renderer()` from \ref "ftxui/component/component.hpp". This component decorate another one by using a different function to render an interface. ## CatchEvent -Produced by: ftxui::CatchEvent() from \ref "ftxui/component/component.hpp". This -component decorate another one and catch the events before the underlying +Produced by: `ftxui::CatchEvent()` from \ref "ftxui/component/component.hpp". +This component decorate another one and catch the events before the underlying component. ## Container::Horizontal -Produced by: ftxui::Container::Horizontal() from +Produced by: `ftxui::Container::Horizontal()` from "ftxui/component/component.hpp". It displays a list of components horizontally and handle keyboard/mouse navigation. ## Container::Vertial -Produced by: ftxui::Container::Vertical() from +Produced by: `ftxui::Container::Vertical()` from "ftxui/component/component.hpp". It displays a list of components vertically and handles keyboard/mouse navigation. ## Container::Tab -Produced by: ftxui::Container::Tab() from +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. ## ResizableSplit::{Left, Right, Top, Bottom} Produced by: -- ftxui::ResizableSplitLeft() -- ftxui::ResizableSplitRight() -- ftxui::ResizableSplitTop() -- ftxui::ResizableSplitBottom() - +- `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 +It defines an horizontal or vertical separation in between two children +component. The position of the split is variable and controllable using the mouse. @htmlonly @endhtmlonly + +## Force a frame redraw. + +Whenever a new group of events have been processed: keyboard, mouse, window +resize, etc..., the `ftxui::ScreenInteractive::Loop()` is responsible for +drawing a new frame. + +You might want to react to arbitrary events that are unknown to FTXUI. This can +be achieve by posting events via `PostEvent`, via a thread. You can post the +event`Event::Custom`. + +```cpp +screen->PostEvent(ftxui::Event::Custom); +``` + +`ftxui::ScreenInteractive::PostEvent` is thread safe.