FTXUI Documentation

FTXUI (Functional Terminal (X) User interface) is a cross-platform C++ library designed for creating terminal-based user interfaces. It uses a functional style inspired by React, allowing for simple and elegant syntax.

Key features include:

• Keyboard and mouse navigation.
• Support for UTF8 and fullwidth characters.
• Support for animations and drawing (canvas).
• No external dependencies.
• C++20 Module support.
• Cross-platform compatibility: Linux, MacOS, WebAssembly, and Windows.

The ftxui/screen module is the foundation of the library, providing low-level terminal drawing capabilities. Use it when you need direct control over a 2D grid of styled characters.

Key entities:

• ftxui::Screen: A 2D grid of styled characters.
• ftxui::Cell: The fundamental unit of rendering.
• Helpers: ftxui::Color and Dimension for styling and sizing.

The ftxui::component module provides logic for interactive components that respond to user events like keyboard and mouse input. While ftxui::Element is used for rendering single static frames, ftxui::Component is used for dynamic user interfaces that maintain state and update across multiple frames.

Key concepts:

• ftxui::App: Defines the main loop that renders a component.
• ftxui::Component: A shared pointer to a ftxui::ComponentBase.
• ftxui::ComponentBase: Defines Render() (how to draw), OnEvent() (how to react), and Add() (to build parent/child relationships for keyboard navigation).

Include the header to access predefined components:

#include "ftxui/component/component.hpp"

The ftxui/component module is the highest level of the library, providing stateful and interactive widgets. Use this module to build applications that respond to keyboard or cursor input.

Key entities:

• ftxui::Component: Stateful, interactive widgets that support composition.
• Built-in widgets:
  • Checkbox
  • Input
  • Menu
  • Button

FTXUI is organized into three hierarchical modules:

1. Screen: The lowest level. Handles terminal state, colors, and the raw character grid.
2. DOM: The layout engine. Provides Elements that can be composed for responsive layouts.
3. Component: The interactive layer. Handles user input (keyboard, mouse) and manages the application's main loop.

The ftxui/dom module provides a tree-based structure for building structured and responsive user interfaces. It sits above the screen module and allows you to compose complex layouts.

Key entities:

• ftxui::Element: A tree structure used for layout and UI composition.
• Render(): Method used to draw an Element onto a ftxui::Screen.

You can install unofficial pre-built FTXUI packages using apt. The following packages are available:

• libftxui-dev: Development files
• ftxui-doc: Documentation
• ftxui-examples: Example projects
• libftxui-component<version>
• libftxui-dom<version>
• libftxui-screen<version>

Note: These packages are unofficial and are maintained by the community, not the FTXUI team.

sudo apt install libftxui-dev

Install the FTXUI package using the vcpkg command line tool. You should specify the appropriate triplet for your platform (e.g., x64-linux, x64-windows, or arm64-osx).

vcpkg install --triplet x64-linux

To use FTXUI as a dependency in your own Nix Flake project, add it to your inputs and then reference the package in your outputs.

1. Add the input:

{ 
  inputs.ftxui.url = "github:ArthurSonzogni/FTXUI";
}

2. Reference the package in your outputs using the pattern ftxui.packages.<system>.ftxui.

FTXUI is available in the Arch User Repository (AUR). You can install it using an AUR helper like yay, or by manually downloading the PKGBUILD from the AUR website.

yay -S ftxui

When configuring your project with CMake, you must pass the CMAKE_TOOLCHAIN_FILE pointing to your vcpkg installation path to ensure the dependencies are found.

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build
./build/main