ftxui / screen

Table of Contents

• ftxui::Screen
• ftxui::Dimension
• ftxui::Pixel
• ftxui::Color

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 ftxui::Screen.

---

ftxui::Screen

The 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 (ftxui::Pixel) of the screen using the 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 ftxui::Screen::Print() or converted to a std::string with 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 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 ftxui::Dimension utility controls screen sizing:

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

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

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 ftxui::Pixel, which holds:

• Unicode codepoint.
  • character
• 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 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 ftxui::Color class is used to define foreground and background colors for each 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 ftxui::Terminal::ColorSupport();

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