mainpage.md

    \mainpage

    #Introduction{#introduction}

    WelcometotheFTXUIdocumentation!

    Thisisabrieftutorial.Youarealsoencouragedtoself-learnbyreadingthe
    [examples](./examples.html).

    @tableofcontents

    **Shortexample**

    Tobuildasingleframe,youneedcreatean`ftxui::Element`,anddisplayiton
    a`ftxui::Screen`.

    **main.cpp**
    ```cpp
    #include<ftxui/dom/elements.hpp>
    #include<ftxui/screen/screen.hpp>
    #include<iostream>

    intmain(void){
    usingnamespaceftxui;

    //Definethedocument
    Elementdocument=
    hbox({
    text("left")|border,
    text("middle")|border|flex,
    text("right")|border,
    });

    autoscreen=Screen::Create(
    Dimension::Full(),//Width
    Dimension::Fit(document)//Height
    );
    Render(screen,document);
    screen.Print();

    returnEXIT_SUCCESS;
    }
    ```

    **output**
    ```bash
    ┌────┐┌────────────────────────────────────┐┌─────┐
    │left││middle││right│
    └────┘└────────────────────────────────────┘└─────┘
    ```

    ##Configure{#configure}
    ###UsingCMakeandfind_package{#build-cmake-find-package}

    AssumingFTXUIisavailableorinstalledonthesystem.

    **CMakeLists.txt**
    ```cmake
    cmake_minimum_required(VERSION3.11)
    find_package(ftxui5REQUIRED)
    project(ftxui-starterLANGUAGESCXXVERSION1.0.0)
    add_executable(ftxui-startersrc/main.cpp)
    target_link_libraries(ftxui-starter
    PRIVATEftxui::screen
    PRIVATEftxui::dom
    PRIVATEftxui::component#Notneededforthisexample.
    )

    ```

    ###UsingCMakeandFetchContent{#build-cmake}

    IfyouwanttofetchFTXUIusingcmake:

    **CMakeLists.txt**
    ```cmake
    cmake_minimum_required(VERSION3.11)

    include(FetchContent)
    set(FETCHCONTENT_UPDATES_DISCONNECTEDTRUE)
    FetchContent_Declare(ftxui
    GIT_REPOSITORYhttps://github.com/ArthurSonzogni/ftxui
    GIT_TAGmain#Important:Specifyaversionoracommithashhere.
    )
    FetchContent_MakeAvailable(ftxui)

    project(ftxui-starterLANGUAGESCXXVERSION1.0.0)
    add_executable(ftxui-startersrc/main.cpp)
    target_link_libraries(ftxui-starter
    PRIVATEftxui::screen
    PRIVATEftxui::dom
    PRIVATEftxui::component#Notneededforthisexample.
    )
    ```

    ##Build

    ```bash
    mkdirbuild&&cdbuild
    cmake..
    make
    ./main
    ```

    #Listofmodules.{#modules}

    Theprojectiscomprisedof3modules:

    1.**ftxui/screen**definesa`ftxui::Screen`,agridof`ftxui::Pixel`.

    2.**ftxui/dom**isthemainmodule.Itdefinesahierarchicalsetof
    `ftxui::Element`.Anelementdrawssomethingonthe`ftxui::Screen`.Itis
    responsivetothesizeofitscontainer.

    3.**ftxui/component**Themoduleisrequiredifyourprogramneedstorespond
    touserinput.Itdefinesasetof`ftxui::Component`.Thesecomponentscan
    beutilizedtonavigateusingthearrowkeys*and/or*cursor.Thereare
    severalbuiltinwidgetslikecheckbox/inputbox/etctointeractwith.Youcan
    combinethem,orevendefineyourowncustomcomponents.

    #screen{#module-screen}

    Thisisthevisualelementoftheprogram.Itdefinesa`ftxui::Screen`,which
    isagridof`ftxui::Pixel`.APixelrepresentsaUnicodecharacterandits
    associatedstyle(bold,italic,colors,etc.).Thescreencanbeprintedasa
    stringusing`ftxui::Screen::ToString()`.Thefollowingexamplehighlightsthis
    process:

    ```cpp
    #include<ftxui/screen/screen.hpp>
    #include<iostream>

    intmain(void){
    usingnamespaceftxui;
    autoscreen=Screen::Create(Dimension::Fixed(32),Dimension::Fixed(10));

    auto&pixel=screen.PixelAt(9,9);
    pixel.character=U'A';
    pixel.bold=true;
    pixel.foreground_color=Color::Blue;

    std::cout<<screen.ToString();
    returnEXIT_SUCCESS;
    }
    ```

    #dom{#module-dom}

    Thismoduledefinesahierarchicalsetof`ftxui::Element`.Anelementmanages
    thelayoutandcanberesponsivetotheterminaldimensionchanges.Notethe
    followingexamplewherethismoduleisusedtocreateasimplelayoutwitha
    numberofoperators:

    **Example:**
    ```cpp
    //Definethedocument
    Elementdocument=vbox({
    text("Thewindow")|bold|color(Color::Blue),
    gauge(0.5)
    text("Thefooter")
    });

    //Addaborder,bycallingthe`ftxui::border`decoratorfunction.
    document=border(document);

    //Addanotherborder,usingthepipeoperator.
    document=document|border.

    //Addanotherborder,usingthe|=operator.
    document|=border

    ```

    **Listofelements**

    Thelistofallelementsareincludedandcanbeaccessedbyincludingthe
    correspondingheaderfile:
    ```cpp
    #include<ftxui/dom/elements.hpp>
    ```

    \includeftxui/dom/elements.hpp

    ##text##{#dom-text}

    Themostsimplewidget.Itdisplaysatext.
    ```cpp
    text("Iamapieceoftext");
    ```
    ```bash
    Iamapieceoftext.
    ```

    ##vtext{#dom-vtext}

    Identicalto`ftxui::text`,butdisplayedvertically.

    Code:
    ```cpp
    vtext("HELLO");
    ```

    Terminaloutput:
    ```bash
    H
    E
    L
    L
    O
    ```

    ##paragraph {#dom-paragraph}

    Similarto`ftxui::text`,buttheindividualwordarewrappedalongmultiple
    lines,dependingonthewidthofitscontainer.

    SampleCode:
    ```cpp
    paragraph("Averylongtext")
    ```

    Foramoredetailedexamplereferto[detailedexample](examples_2dom_2paragraph_8cpp-example.html).Paragraphalsoincludesanumberofothervariantsasshownbelow:
    ```cpp
    Elementparagraph(std::stringtext);
    ElementparagraphAlignLeft(std::stringtext);
    ElementparagraphAlignRight(std::stringtext);
    ElementparagraphAlignCenter(std::stringtext);
    ElementparagraphAlignJustify(std::stringtext);
    ```

    ##border{#dom-border}

    Addsaborderaroundanelement.

    Code:
    ```cpp
    border(text("Theelement"))
    ```

    Terminaloutput:
    ```bash
    ┌───────────┐
    │Theelement│
    └───────────┘
    ```

    Youcanachievethesamebehaviorbyusingthepipeoperator.

    Code:
    ```cpp
    text("Theelement")|border
    ```

    Borderalsocomesinavarietyofstylesasshownbelow:
    ```cpp
    Elementborder(Element);
    ElementborderLight(Element);
    ElementborderHeavy(Element);
    ElementborderDouble(Element);
    ElementborderRounded(Element);
    ElementborderEmpty(Element);
    DecoratorborderStyled(BorderStyle);
    DecoratorborderWith(Pixel);
    ```

    ##window##{#dom-window}

    A`ftxui::window`isa`ftxui::border`,butwithanadditionalheader.Toadda
    windowaroundanelement,wrapitandspecifyastringastheheader.
    Code:
    ```cpp
    window("Thewindow",text("Theelement"))
    ```

    Terminaloutput:
    ```bash
    ┌Thewindow─┐
    │Theelement│
    └───────────┘
    ```

    ##separator{#dom-separator}

    Displaysavertical/horizontallinetovisuallysplitthecontentofa
    containerintwo.

    Code:
    ```cpp
    border(
    hbox({
    text("Left"),
    separator(),
    text("Right")
    })
    )
    ```

    Terminaloutput:
    ```bash
    ┌────┬─────┐
    │left│right│
    └────┴─────┘
    ```

    Separatorscomeinavarietyofflavorsasshownbelow:
    ```cpp
    Elementseparator(void);
    ElementseparatorLight();
    ElementseparatorHeavy();
    ElementseparatorDouble();
    ElementseparatorEmpty();
    ElementseparatorStyled(BorderStyle);
    Elementseparator(Pixel);
    ElementseparatorCharacter(std::string);
    ElementseparatorHSelector(floatleft,
    floatright,
    Colorbackground,
    Colorforeground);
    ElementseparatorVSelector(floatup,
    floatdown,
    Colorbackground,
    Colorforeground);
    ```

    ##gauge{#dom-gauge}

    Itconstitutesagauge.Itcanbeusedtorepresentaprogressbar.

    Code:
    ```cpp
    border(gauge(0.5))
    ```

    Teminaloutput:
    ```bash
    ┌────────────────────────────────────────────────────────────────────────────┐
    │██████████████████████████████████████│
    └────────────────────────────────────────────────────────────────────────────┘
    ```

    Gaugescanbedisplayedinmanyorientationsasshownbelow:
    ```cpp
    Elementgauge(floatratio);
    ElementgaugeLeft(floatratio);
    ElementgaugeRight(floatratio);
    ElementgaugeUp(floatratio);
    ElementgaugeDown(floatratio);
    ElementgaugeDirection(floatratio,GaugeDirection);
    ```

    ##graph{#dom-graph}

    See:
    ```cpp
    Elementgraph(GraphFunction);
    ```

    ##Colors{#dom-colors}

    Mostterminalconsolescandisplaycoloredtextandcoloredbackgrounds.FTXUI
    supportseverycolorpalette:
    ```cpp
    Decoratorcolor(Color);
    Decoratorbgcolor(Color);
    ```

    Color[gallery](examples_2dom_2color_gallery_8cpp-example.html):

    ###Palette16 #{#dom-colors-palette-16}

    Onmostterminalsthefollowingcolorsaresupported:
    -Default

    -Black
    -GrayDark
    -GrayLight

    -White

    -Blue
    -BlueLight

    -Cyan
    -CyanLight

    -Green
    -GreenLight

    -Magenta
    -MagentaLight

    -Red
    -RedLight

    -Yellow
    -YellowLight

    Exampleuseoftheabovecolorsusingthepipeoperator:
    ```cpp
    text("Blueforeground")|color(Color::Blue);
    text("Bluebackground")|bgcolor(Color::Blue);
    text("Blackonwhite")|color(Color::Black)|bgcolor(Color::White);
    ```

    ###Palette256 #{#dom-colors-palette-256}

    Onterminalsupporting256colors.

    ```cpp
    text("HotPink")|color(Color::HotPink);
    ```

    ###TrueColor#{#dom-colors-true-color}

    OnterminalsupportingtrueColor,youcandirectlyusethe24bitRGBcolor
    space:

    Usetheconstructorsbelowtospecifythe**RGB**or**HSV**valuesforyour
    color:

    Therearetwoconstructors:
    ```cpp
    ftxui::Color::RGB(uint8_tred,uint8_tgreen,uint8_tblue);
    ftxui::Color::HSV(uint8_thue,uint8_tsaturation,uint8_tvalue);
    ```

    ##LinearGradient#{#dom-linear-gradient}

    FTXUIsupportslineargradient.Eitherontheforegroundorthebackground.

    ```cpp
    Decoratorcolor(constLinearGradient&);
    Decoratorbgcolor(constLinearGradient&);
    ```

    A`ftxui::LinearGradient`isdefinedbyanangleindegree,andalistofcolor
    stops.
    ```cpp
    autogradient=LinearGradient()
    .Angle(45)
    .AddStop(0.0,Color::Red)
    .AddStop(0.5,Color::Green)
    .AddStop(1.0,Color::Blue);
    ```

    Youcanalsousesimplifiedconstructors:
    ```cpp
    LinearGradient(Color::Red,Color::Blue);
    ```
    ```cpp
    LinearGradient(45,Color::Red,Color::Blue);
    ```

    See[demo](https://arthursonzogni.github.io/FTXUI/examples/?file=component/linear_gradient_gallery).

    ##Style{#dom-style}
    Inadditiontocoloredtextandcoloredbackgrounds.Manyterminalssupporttext
    effectssuchas:`bold`,`italic`,`dim`,`underlined`,`inverted`,`blink`.

    ```cpp
    Elementbold(Element);
    Elementitalic(Element);
    Elementdim(Element);
    Elementinverted(Element);
    Elementunderlined(Element);
    ElementunderlinedDouble(Element);
    Elementstrikethrough(Element);
    Elementblink(Element);
    Decoratorcolor(Color);
    Decoratorbgcolor(Color);
    Decoratorcolorgrad(LinearGradient);
    Decoratorbgcolorgrad(LinearGradient);
    ```

    [Example](examples_2dom_2style_gallery_8cpp-example.html)

    Tousetheseeffects,simplywrapyourelementswithyourdesiredeffect:
    ```cpp
    underlined(bold(text("Thistextisboldandunderlined")))
    ```

    Alternatively,usethepipeoperatortochainitonyourelement:
    ```cpp
    text("Thistextisbold")|bold|underlined
    ```

    ##Layout{#dom-layout}

    Enableselementstobearrangedinthefollowingways:
    -**Horizontally**with`ftxui::hbox`
    -**Vertically**with`ftxui::vbox`
    -**Insideagrid**with`ftxui::gridbox`
    -**Wrappedalongonedirection**usingthe`ftxui::flexbox`.

    [Example](examples_2dom_2vbox_hbox_8cpp-example.html)using`ftxui::hbox`,`ftxui::vbox`and`ftxui::filler`.

    [Example](examples_2dom_2gridbox_8cpp-example.html)
    using`ftxui::gridbox`:

    [Example](examples_2dom_2hflow_8cpp-example.html)
    usingflexbox:

    Checkoutthis
    [example](examples_2dom_2hflow_8cpp-example.html)
    andtheassociated
    [demo](https://arthursonzogni.github.io/FTXUI/examples/?file=component/flexbox).

    Elementcanalsobecomeflexibleusingthethe`ftxui::flex`decorator.

    Code:
    ```cpp
    hbox({
    text("left")|border,
    text("middle")|border|flex,
    text("right") |border,
    });
    ```
    Terminaloutput:
    ```bash
    ┌────┐┌─────────────────────────────────────────────────────┐┌─────┐
    │left││middle││right│
    └────┘└─────────────────────────────────────────────────────┘└─────┘
    ```

    Code:
    ```cpp
    hbox({
    text("left")|border,
    text("middle")|border|flex,
    text("right") |border|flex,
    });
    ```

    Terminaloutput:
    ```bash
    ┌────┐┌───────────────────────────────┐┌───────────────────────────────┐
    │left││middle││right│
    └────┘└───────────────────────────────┘└───────────────────────────────┘
    ```

    ##Table{#dom-table}

    Enableseasyformattingofdataintoaneattablelikevisualform.

    [Codeexample](examples_2dom_2table_8cpp-example.html):

    ##Canvas{#dom-canvas}

    SeetheAPI[<ftxui/dom/canvas.hpp>](./canvas_8hpp_source.html)

    ```cpp
    autoc=Canvas(100,100);
    c.DrawPointLine(10,10,80,10,Color::Red);
    autoelement=canvas(c);
    ```

    Drawingcanbeperformedona`ftxui::Canvas`,usingbraille,block,orsimple
    characters:

    Simple[example](examples_2dom_2canvas_8cpp-example.html):

    Complex[example](examples_2component_2canvas_animated_8cpp-example.html):

    #component{#module-component}

    The`ftxui::component`moduledefinesthelogicthatproducesinteractive
    componentsthatrespondtouserevents(keyboard,mouse,etc.).

    A`ftxui::ScreenInteractive`definesamainloopthatrendersacomponent.

    A`ftxui::Component`isasharedpointertoa`ftxui::ComponentBase`.Thelatterdefines:
    -`ftxui::ComponentBase::Render()`:Howtorendertheinterface.
    -`ftxui::ComponentBase::OnEvent()`:Howtoreacttoevents.
    -`ftxui::ComponentBase::Add()`:Constructaparent/childrelationship
    betweentwocomponents.Thetreeofcomponentisusedtodefinehowto
    navigateusingthekeyboard.

    `ftxui::Element`areusedtorenderasingleframe.

    `ftxui::Component`areusedtorenderdynamicuserinterface,producingmultiple
    frame,andupdatingitsstateonevents.

    [Gallery](examples_2component_2gallery_8cpp-example.html)ofmultiplecomponents.([demo](https://arthursonzogni.github.io/FTXUI/examples/?file=component/gallery))

    Allpredefinedcomponentsareavailablein
    ["ftxui/dom/component.hpp"](./component_8hpp.html)

    \includeftxui/component/component.hpp

    ##Input{#component-input}

    [Example](examples_2component_2input_8cpp-example.html):

    Producedby:`ftxui::Input()`from"ftxui/component/component.hpp"

    ###Filteredinput

    Oncanfilteroutthecharactersreceivedbytheinputcomponent,using
    `ftxui::CatchEvent`.

    ```cpp
    std::stringphone_number;
    Componentinput=Input(&phone_number,"phonenumber");

    //Filteroutnon-digitcharacters.
    input|=CatchEvent([&](Eventevent){
    returnevent.is_character()&&!std::isdigit(event.character()[0]);
    });

    //Filteroutcharacterspastthe10thone.
    input|=CatchEvent([&](Eventevent){
    returnevent.is_character()&&phone_number.size()>=10;
    });
    ```

    ##Menu{#component-menu}

    Definesamenuobject.Itcontainsalistofentries,oneofthemisselected.

    [Example](examples_2component_2menu_8cpp-example.html):

    Producedby:`ftxui::Menu()`from"ftxui/component/component.hpp"

    ##Toggle {#component-toggle}

    Aspecialkindofmenu.Theentriesaredisplayedhorizontally.

    [Example](examples_2component_2toggle_8cpp-example.html):

    Producedby:`ftxui::Toggle()`from"ftxui/component/component.hpp"

    ##CheckBox{#component-checkbox}

    Thiscomponentdefinesacheckbox.Itisasingleentrythatcanbeturned
    on/off.

    [Example](examples_2component_2checkbox_8cpp-example.html):

    Producedby:`ftxui::Checkbox()`from"ftxui/component/component.hpp"

    ##RadioBox{#component-radiobox}

    Aradiobuttoncomponent.Thisisalistofentries,whereonecanbeturnedon.

    [Example](examples_2component_2radiobox_8cpp-example.html):

    Producedby:`ftxui::Radiobox()`from"ftxui/component/component.hpp"

    ##Dropdown{#component-dropdown}

    Adropdownmenuisacomponentthatwhencheckeddisplayalistofelementfor
    theusertoselectone.

    [Example](examples_2component_2dropdown_8cpp-example.html):

    Producedby:`ftxui::Dropdown()`from"ftxui/component/component.hpp"

    ##Slider{#component-slider}

    Representsasliderobjectthatconsistsofarangewithbinnedintermediate
    intervals.Itcanbecreatedby`ftxui::Slider()`.

    [Example](examples_2component_2slider_8cpp-example.html):

    Producedby:`ftxui::Slider()`from"ftxui/component/component.hpp"

    ##Renderer{#component-renderer}

    Producedby:`ftxui::Renderer()`from\refftxui/component/component.hpp.This
    componentdecorateanotheronebyusingadifferentfunctiontorenderan
    interface.

    Example:
    ```cpp
    autoinner=[...]

    autorenderer=Renderer(inner,[&]{
    returninner->Render()|border
    });
    ```

    `ftxui::Renderer`alsosupportsthecomponentdecoratorpattern:
    ```cpp
    autocomponent= [...]
    component=component
    |Renderer([](Elemente){returne|border))
    |Renderer(bold)
    ```

    Asashorthand,youcanalsocomposeacomponentwithanelementdecorator:
    ```cpp
    autocomponent=[...]
    component=component|border|bold;
    ```

    ##CatchEvent{#component-catchevent}

    Producedby:`ftxui::CatchEvent()`from\refftxui/component/component.hpp.
    Thiscomponentdecorateothers,catchingeventsbeforetheunderlyingcomponent.

    Examples:
    ```cpp
    autoscreen=ScreenInteractive::TerminalOutput();
    autorenderer=Renderer([]{
    returntext("Myinterface");
    });
    autocomponent=CatchEvent(renderer,[&](Eventevent){
    if(event==Event::Character('q')){
    screen.ExitLoopClosure()();
    returntrue;
    }
    returnfalse;
    });
    screen.Loop(component);
    ```

    The`ftxui::CatchEvent`canalsobeusedasadecorator:
    ```cpp
    component=component
    |CatchEvent(handler_1)
    |CatchEvent(handler_2)
    |CatchEvent(handler_3)
    ;
    ```

    ##Collapsible{#component-collapsible}

    Usefulforvisualelementswhosevisibilitycanbetoggleon/offbytheuser.
    Essentially,thisthecombinationofthe`ftxui::Checkbox()`and
    `ftxui::Maybe()`components.

    ```cpp
    autocollabsible=Collapsible("Showmore",inner_element);
    ```

    ##Maybe{#component-maybe}

    Producedby:`ftxui::Maybe()`from\refftxui/component/component.hpp.
    Thiscomponentcanbeutilizedtoshow/hideanyothercomponentviaabooleanor
    apredicate.

    Examplewithaboolean:
    ```cpp
    boolshow=true;
    autocomponent=Renderer([]{return"HelloWorld!";});
    automaybe_component=Maybe(component,&show)
    ```

    Examplewithapredicate:
    ```cpp
    autocomponent=Renderer([]{return"HelloWorld!";});
    automaybe_component=Maybe(component,[&]{returntime>10;})
    ```

    Asusual,`ftxui::Maybe`canalsobeusedasadecorator:
    ```cpp
    component=component
    |Maybe(&a_boolean)
    |Maybe([&] {returntime>10;})
    ;
    ```

    ##Container{#component-container}

    ###Horizontal{#component-horizontal}

    Producedby:`ftxui::Container::Horizontal()`from
    "ftxui/component/component.hpp".Itdisplaysalistofcomponentshorizontally
    andhandlekeyboard/mousenavigation.

    ###Vertical{#component-vertical}

    Producedby:`ftxui::Container::Vertical()`from
    "ftxui/component/component.hpp".Itdisplaysalistofcomponentsvertically
    andhandleskeyboard/mousenavigation.

    ###Tab{#component-tab}

    Producedby:`ftxui::Container::Tab()`from
    "ftxui/component/component.hpp".Ittakealistofcomponentanddisplayonly
    oneofthem.Thisisusefulforimplementingatabbar.

    [Vertical](examples_2component_2tab_vertical_8cpp-example.html):

    [Horizontal](examples_2component_2tab_horizontal_8cpp-example.html):

    ##ResizableSplit{#component-resizable-split}

    Itdefinesahorizontalorverticalseparationbetweentwochildrencomponents.
    Thepositionofthesplitisvariableandcontrollableusingthemouse.
    Therearefourpossiblesplits:
    -`ftxui::ResizableSplitLeft()`
    -`ftxui::ResizableSplitRight()`
    -`ftxui::ResizableSplitTop()`
    -`ftxui::ResizableSplitBottom()`
    from"ftxui/component/component.hpp"

    [Example](examples_2component_2resizable_split_8cpp-example.html):

    ##Forceaframeredraw.{#component-force-redraw}

    Typically,`ftxui::ScreenInteractive::Loop()`isresponsiblefordrawinganew
    framewheneveranewgroupofevents(e.gkeyboard,mouse,windowresize,etc.)
    hasbeenprocessed.However,youmightwanttoreacttoarbitraryeventsthat
    areunknowntoFTXUI.Toaccomplishthis,youmustposteventsusing
    `ftxui::ScreenInteractive::PostEvent`(**thisisthreadsafe**)viaathread.
    Youwillhavetoposttheevent`ftxui::Event::Custom`.

    Example:
    ```cpp
    screen->PostEvent(Event::Custom);
    ```