FTXUI README

The project's README from github.com/ArthurSonzogni/FTXUI. As one markdown file: README.md.

Demo image

latest packaged version(s)
Documentation · Report a Bug · Examples . Request Feature · Send a Pull Request
Doc: English | Français | Español | 繁體中文 | 简体中文 | 日本語 |

FTXUI

Functional Terminal (X) User interface

A simple cross-platform C++ library for terminal based user interfaces!

Feature

Documentation

Example

#include <ftxui/ftxui.hpp>
using namespace ftxui;

int main() {
  auto document =
    vbox({
      hbox({
        text("one") | border,
        text("two") | border | flex,
        text("three") | border | flex,
      }),

      gauge(0.25) | color(Color::Red),
      gauge(0.50) | color(Color::White),
      gauge(0.75) | color(Color::Blue),
    });

  auto screen = Screen::Create(Dimension::Full());
  Render(screen, document);
  screen.Print();

  return 0;
}

image

FTXUI is organized into three modules:

  1. screen: Low-level rendering (colors, pixels, terminal)
  2. dom: Layout and composition (hierarchical elements)
  3. component: User interaction (widgets, events, main loop)

For most users, including everything at once is the simplest way to start:

DOM

This module defines a hierarchical set of Element. An Element manages layout and can be responsive to the terminal dimensions.

They are declared in <ftxui/dom/elements.hpp>

Layout

Element can be arranged together:

  • horizontally with hbox
  • vertically with vbox
  • inside a grid with gridbox
  • wrap along one direction using the flexbox.

Element can become flexible using the flex decorator.

Example using hbox, vbox and filler.

image

Example using gridbox:

image

Example using flexbox:

image

See also this demo.

Style

An element can be decorated using the functions:

  • bold
  • italic
  • dim
  • inverted
  • underlined
  • underlinedDouble
  • blink
  • strikethrough
  • color
  • bgcolor
  • hyperlink

Example

image

FTXUI supports the pipe operator. It means: decorator1(decorator2(element)) and element | decorator1 | decorator2 can be used.

Colors

FTXUI supports every color palette:

Color gallery: image

Border and separator

Use decorator border and element separator() to subdivide your UI:

Element document = vbox({
    text("top"),
    separator(),
    text("bottom"),
}) | border;

Demo:

image

Text and paragraph

A simple piece of text is represented using text("content").

To support text wrapping following spaces the following functions are provided:

Element paragraph(string text);
Element paragraphAlignLeft(string text);
Element paragraphAlignRight(string text);
Element paragraphAlignCenter(string text);
Element paragraphAlignJustify(string text);

Paragraph example

ezgif com-gif-maker (4)

Table

A class to easily style a table of data.

Example:

image

Canvas

Drawing can be made on a Canvas, using braille, block, or simple characters:

Simple example:

image

Complex examples:

ezgif com-gif-maker (3)

Component

ftxui/component produces dynamic UI, reactive to the user's input. It defines a set of ftxui::Component. A component reacts to Events (keyboard, mouse, resize, ...) and Renders as an Element (see previous section).

Prebuilt components are declared in <ftxui/component/component.hpp>

Gallery

Gallery of multiple components. (demo)

image

Radiobox

Example:

image

Checkbox

Example:

image

Input

Example:

image

Toggle

Example:

image

Slider

Example:

image

Menu

Example:

image

ResizableSplit

Example:

ezgif com-gif-maker

Dropdown

Example:

youtube-video-gif (3)

Tab

Vertical:

ezgif com-gif-maker (1)

Horizontal:

ezgif com-gif-maker (2)

Libraries for FTXUI

Project using FTXUI

Feel free to add your projects here:

cpp-best-practices/game_jam

Several games using the FTXUI have been made during the Game Jam:

Build using CMake

It is highly recommended to use CMake FetchContent to depend on FTXUI so you may specify which commit you would like to depend on.

include(FetchContent)
FetchContent_Declare(ftxui
  GIT_REPOSITORY https://github.com/ArthurSonzogni/ftxui
  GIT_TAG v7.0.3
)
FetchContent_MakeAvailable(ftxui)

target_link_libraries(your_target PRIVATE
    # Use the umbrella target (recommended)
    ftxui::ftxui

    # Or chose a submodule
    # ftxui::component
    # ftxui::dom
    # ftxui::screen
)

Build using Bazel

MODULE.bazel

bazel_dep(
    name = "ftxui",
    version = "7.0.3",
)

BUILD.bazel

cc_binary(
    name = "your_target",
    srcs = ["your_source.cc"],
    deps = [
        # Choose submodules
        "@ftxui//:component",
        "@ftxui//:dom",
        "@ftxui//:screen",
        
        # Or use the single ftxui target (includes all modules)
        # "@ftxui//:ftxui",
    ],
)

Build using Meson

FTXUI can also be built using Meson. See doc/installation_meson.md for detailed instructions.

meson setup builddir
ninja -C builddir

To use FTXUI as a subproject in your Meson project, create a subprojects/ftxui.wrap file or use it as a dependency:

ftxui_dep = dependency('ftxui-component')

Build with something else:

If you don't, FTXUI may be used from the following packages:

Packaging status

If you choose to build and link FTXUI yourself, ftxui-component must be first in the linking order relative to the other FTXUI libraries, i.e.

g++ . . . -lftxui-component -lftxui-dom -lftxui-screen . . .

To build FTXUI with modules, check documentation

Contributors

FTXUI (ArthurSonzogni/FTXUI)

user-interface
Searching Database…

10.8K ·GitHub
FTXUI
What is this?FTXUI is a simple cross-platform C++ library for building terminal user interfaces — full-screen text apps with colors, layout, widgets, and keyboard and mouse input.
Is it a library I link into my own program, or a ready-made app?A library you link into your own C++ program, not a standalone app. It comes as three modules: screen (rendering), dom (layout) and component (interactive widgets and the main loop).
How do I add it to my project?CMake FetchContent is the preferred way. Alternatives include Bazel, vcpkg, Conan, Meson, distro packages (Debian, Ubuntu, Arch, OpenSUSE), Nix, conda-forge, and a single-header amalgamated build since 7.0.0.
Do I need to install anything else first, like ncurses?None — FTXUI has no external dependencies. You only need a C++20-capable compiler toolchain.
Does it work on Windows, or is it Linux and macOS only?Linux and macOS are the main targets, but Windows is supported too, and it also compiles to WebAssembly, so demos can run in a browser.
How do you describe a UI in FTXUI?You compose elements functionally: hbox and vbox arrange them horizontally or vertically, gridbox and flexbox handle grids and wrapping, decorators add bold, colors, borders and hyperlinks, and a pipe operator chains decorators.
Which widgets are included out of the box?Checkbox, radiobox, text input, toggle, slider, menu, dropdown, resizable split and tabs. Components react to keyboard, mouse and resize events and render as layout elements.
Can it draw graphics, not just text?Yes. You can draw on a Canvas using braille, block or simple characters, every color palette is supported, and elements can be animated.
What have people built with it?Game-jam titles like TermBreaker and Minesweeper Marathon, tools like json-tui, git-tui and rgb-tui, a resource monitor, a terminal file browser, plus community components such as an image viewer and a markdown editor.
What are similar projects?ascii, world.execute-me-ascii, tview, slint, rataflow, tui-rs, textual, ratatui
Which topics is it in?ascii, xterm, ascii-art, user-interface, terminal-based, widgets, functional-programming, rendering, component-library, wasm, tui, ui-components
Creator
ArthurSonzogni
Size
100.9 MB
Stars
10.8K
Updated
CommitOct 17Releasev7.0.3Aug 06
Age
7y
Commits · 90 Days