FTXUI/doc/module-screen.md

@page module-screen ftxui / screen @tableofcontents

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 and ftxui::component modules.

It provides a @ref ftxui::Screen.

---

ftxui::Screen

The @ref ftxui::Screen class represents a 2D grid of styled characters that can be rendered to a terminal.
It provides methods to create a screen, access pixels, and render elements.

You can access the individual cells (@ref ftxui::Pixel) of the screen using the @ref ftxui::Screen::PixelAt method, which returns a reference to the pixel at the specified coordinates.

Example

#include <ftxui/screen/screen.hpp>
#include <ftxui/screen/color.hpp>

void main() {
    auto screen = ftxui::Screen::Create(
        ftxui::Dimension::Full(),   // Use full terminal width
        ftxui::Dimension::Fixed(10) // Fixed height of 10 rows
    );

    // Access a specific pixel at (10, 5)
    auto& pixel = screen.PixelAt(10, 5);

    // Set properties of the pixel.
    pixel.character = U'X';
    pixel.foreground_color = ftxui::Color::Red;
    pixel.background_color = ftxui::Color::RGB(0, 255, 0);
    pixel.bold = true; // Set bold style
    screen.Print(); // Print the screen to the terminal
}

Note

If the coordinates are out of bounds, a dummy pixel is returned.

The screen can be printed to the terminal using @ref ftxui::Screen::Print() or converted to a std::string with @ref ftxui::Screen::ToString().

• Print()

  auto screen = ...;
  screen.Print();
  

• ToString()

  auto screen = ...;
  std::cout << screen.ToString();
  

Note that you can reset the cursor position to the top-left corner of the screen after printing by calling @ref ftxui::Screen::ResetCursorPosition().

Example

auto screen = ...;
while(true) {
  // Drawing operations:
  ...
  
  // Print the screen to the terminal. Then reset the cursor position and the
  // screen content.
  std::cout << screen.ToString();
  std::cout << screen.ResetCursorPosition(/*clear=*/true);
  std::cout << std::flush;

  // Sleep for a short duration to control the refresh rate.
  std::this_thread::sleep_for(std::chrono::milliseconds(100));
}

---

ftxui::Dimension

The @ref ftxui::Dimension utility controls screen sizing:

• Dimension::Full() — use full terminal width or height
• Dimension::Fit(element) — size to fit the rendered @ref ftxui::Element
• Dimension::Fixed(n) — use exactly n columns or rows

These values are to be passed to ftxui::Screen::Create().

@ref ftxui::Screen::Create() provides two overloads:

• Screen::Create(Dimension) sets both width and height to the same kind of dimension
• Screen::Create(Dimension width, Dimension height) allows distinct control per axis

auto screen = ftxui::Screen::Create(
  ftxui::Dimension::Full(),      // width
  ftxui::Dimension::Fixed(10)    // height
);

Once created, render an element and display the result:

ftxui::Render(screen, element);
screen.Print();

---

ftxui::Pixel

Each cell in the screen grid is a @ref ftxui::Pixel, which holds:

• Unicode codepoint.
  • character
• @ref ftxui::Color:
  • foreground_color
  • background_color
• Booleans:
  • blink
  • bold
  • dim
  • italic
  • inverted (swap foreground and background colors)
  • underlined
  • underlined_double
  • strikethrough

auto screen = ftxui::Screen::Create(
  ftxui::Dimension::Fixed(5),
  ftxui::Dimension::Fixed(5),
);

auto& pixel = screen.PixelAt(3, 3);
pixel.character = U'X';
pixel.bold = true;
pixel.foreground_color = ftxui::Color::Red;
pixel.background_color = ftxui::Color::RGB(0, 255, 0);

screen.Print();

Note

PixelAt(x, y) performs bounds checking and returns a reference to the pixel at the specified coordinate. If out-of-bounds, a dummy pixel reference is returned.

Each cell in the screen is a @ref ftxui::Pixel. You can modify them using:

auto& pixel = screen.PixelAt(x, y);
pixel.character = U'X';
pixel.bold = true;
pixel.foreground_color = Color::Red;

---

ftxui::Color

The @ref ftxui::Color class is used to define foreground and background colors for each @ref ftxui::Pixel.

It supports various color spaces and predefined palettes. FTXUI will dynamically fallback to the closest available color in the terminal if the requested color is not supported by the terminal.

Color Spaces

• Default: ftxui::Color::Default (terminal's default color)
• 16-color palette Demo:
  • ftxui::Color::Black,
  • ftxui::Color::Red,
  • ...
• 256-color palette Demo:
  • ftxui::Color::Chartreuse1,
  • ftxui::Color::DarkViolet,
  • ...
• True color (24bit) [Demo](https://arthursonzogni.github.io/FTXUI/examples/?file=dom/color_truecolor_HSV:
  • ftxui::Color::RGB(uint8_t red, uint8_t green, uint8_t blue)
  • ftxui::Color::HSV(uint8_t h, uint8_t s, uint8_t v).

Note

You can query the terminal capability using @ref ftxui::Terminal::ColorSupport();

This can manually be set using @ref ftxui::Terminal::SetColorSupport().