NAME

Term::Fabulous::Manual - The Term::Fabulous user guide

HOW TO READ THIS MANUAL

This manual explains how Term::Fabulous works and how you use it. This page is its starting point: it introduces the library, shows a first program and ends with the "FEATURE INDEX", which maps tasks to the sections, recipes and class pages that describe them. The topics themselves are on pages of their own, listed under "CONTENTS".

To learn Term::Fabulous: Read "INTRODUCTION" and "YOUR FIRST PROGRAM" on this page, then the topic pages in the order of "CONTENTS". Every topic page links to the previous and the next page at its top and bottom, so you can read the whole manual from start to end.
To find something: Look the task up in the "FEATURE INDEX". Every topic has its own heading, so you can also search a page: with / in perldoc, or with the table of contents on MetaCPAN. Terms the manual uses are defined in Term::Fabulous::Manual::Glossary.

The manual is one of four kinds of documentation:

The manual (this page and its topic pages): Explains the concepts: layout, text and colors, events, the keyboard, the mouse and the focus, forms, tables, charts, KDL layout files, the event loop, testing and writing widgets of your own.
Term::Fabulous::Cookbook: Recipes: complete, runnable programs for common tasks, each with a picture and notes on the lines that matter. Its index page lists every recipe; the recipes themselves are on fifteen topic pages, from Term::Fabulous::Cookbook::GettingStarted to Term::Fabulous::Cookbook::Extending.
Term::Fabulous::Examples: The example programs of the distribution, each with a picture: demo programs, one program per widget, and the programs of the cookbook.
The class pages: One reference page per class, such as Term::Fabulous (the application object), Term::Fabulous::Widget::Box or Term::Fabulous::Widget::TextField. A class page lists every constructor parameter, method, event, key, mouse action and KDL property of the class. The list of modules on the main page names all of them, grouped by purpose.

Conventions

Every example uses subroutine signatures. A complete program starts with this header, which works on every Perl that Term::Fabulous supports (5.32.1 and later):

use v5.32;
use warnings;
use feature 'signatures';
no warnings 'experimental::signatures';

Shorter snippets leave the header out. A snippet may use variables from an earlier snippet of the same section, and usually $root (the root widget) and $ui (the Term::Fabulous object).

Code in these documents is indented. When you copy an example that contains a here-document (<<'KDL'), remove the indentation from the line that ends it (KDL): Perl recognizes the terminator only at the start of a line.

The manual has these pages, in reading order:

This page: "INTRODUCTION": what Term::Fabulous does, the libraries it builds on, and how a frame is drawn. "REQUIREMENTS", "YOUR FIRST PROGRAM" and the "FEATURE INDEX".
Term::Fabulous::Manual::Layout: The widgets and the widget tree, widget ids, and how the layout engine sizes and places widgets: direction, sizing, padding, gaps, alignment, flow and stack layouts, floating widgets and equal sizes across the tree. Dividers between widgets, accordions whose sections open and close, tabs, and the tabs of the open documents of a program.
Term::Fabulous::Manual::Looks: Text (character strings, wrapping, alignment, wide characters and emoji), colors (formats, alpha, the terminal's default colors, lighter and darker colors), borders and themes.
Term::Fabulous::Manual::Events: Events and listeners, bubbling, the keyboard and key names, the focus, the mouse, hover and press, and scrolling.
Term::Fabulous::Manual::Forms: The input widgets (text fields, text areas, check boxes, radio buttons, dropdowns, sliders, star ratings, segmented controls, color pickers), what they have in common, editing text, the clipboard, undo, and complete forms.
Term::Fabulous::Manual::Feedback: The widgets that show what the program is doing: progress bars, with and without a known extent, spinners, toasts that appear in a corner and go away by themselves, status bars, and how widgets animate without timers. Also prompts, which ask the user a question and wait for the answer, and file dialogs, which ask for a file or a folder.
Term::Fabulous::Manual::Menus: Commands and the keys that run them, menu bars, context menus, a help screen that lists the keys, and the shape of an application window with a menu bar and a status bar.
Term::Fabulous::Manual::Charts: Canvases you draw on yourself, and the chart widgets that draw themselves from data.
Term::Fabulous::Manual::Tables: The table widget: how it works, rows, columns, display text and mutators, widgets in cells, and the feature index of the table.
Term::Fabulous::Manual::TableRows: Tables, continued: sorting, filtering, groups, trees, pages, the cursor and the selection.
Term::Fabulous::Manual::TableStyles: Tables, continued: colors, styles, lines, padding, size, scrolling and printing a table.
Term::Fabulous::Manual::KDL: Describing the widget tree in a KDL layout file instead of Perl code.
Term::Fabulous::Manual::Programs: The event loop, timers and other asynchronous work, quitting, errors, output without a terminal, and testing.
Term::Fabulous::Manual::CustomWidgets: Writing widgets of your own.
Term::Fabulous::Manual::Troubleshooting: Solutions to common problems.
Term::Fabulous::Manual::Glossary: The terms used in this documentation.

INTRODUCTION

Term::Fabulous builds terminal user interfaces in Perl: forms, dashboards, log viewers, data browsers, editors, games. You describe the screen as a tree of widgets: boxes, text, buttons, input fields, tables, charts, scrollable areas and canvases. Term::Fabulous sizes and positions the widgets, draws them, and turns key presses, mouse clicks and terminal resizes into events that your code reacts to.

A program usually takes over the whole terminal while it runs and gives it back unchanged when it ends. It can also draw into a few rows below the shell's output instead, like a prompt (see "INLINE MODE" in Term::Fabulous), or print a widget tree once as text, without any interaction (see "RENDERING WITHOUT A TERMINAL" in Term::Fabulous::Manual::Programs).

The parts of a program are always the same:

The widget tree: The widgets, built in Perl with new and add_child, or read from a KDL layout file. The top of the tree is the root widget. See Term::Fabulous::Manual::Layout.
Listeners: Code references registered with $widget->on( EventName => sub {...} ) that run when an event happens: a key press, a click, a changed value. See Term::Fabulous::Manual::Events.
The application object: A Term::Fabulous object that holds the tree. Its run method opens the terminal, runs the event loop and returns when the program should end.

Three libraries do the heavy lifting:

Clay: A layout engine (used through Clay::XS and Clay::UI). It decides the position and size of every widget from rules such as "fill the remaining width" or "be as tall as the content". Term::Fabulous measures in terminal cells, so for Clay one unit is one cell.
termbox2: A small C library, compiled into Term::Fabulous::Termbox, that switches the terminal into full-screen mode, reads keys and mouse input, and writes characters with 24-bit colors.
IO::Async: The event loop (IO::Async::Loop). It waits for input, draws the screen when something changed, and runs your timers, sockets and child processes in the same loop.

You do not need to know these libraries in detail. The manual explains everything you need from them and links to their documentation for the rest.

How a frame is drawn

A frame is one complete layout and drawing of the screen. While run is active, Term::Fabulous checks 30 times per second whether anything changed since the last frame: a widget was changed through one of its methods, input arrived, the terminal was resized, or the program asked for a frame with invalidate. When nothing changed, nothing is drawn. When something changed, a frame is drawn in three steps:

Clay lays out the widget tree for the current terminal size.
Term::Fabulous draws every widget into termbox2's screen buffer: backgrounds, borders, text and canvases.
termbox2 compares the buffer with what the terminal already shows and sends only the cells that changed.

Because the whole screen is laid out again in every frame, there is no "redraw" method to call. Change a widget (its text, color, size or children), and the change is visible in the next frame, at most 1/30 second later. The widget methods tell Term::Fabulous that a frame is needed; only a widget of your own that draws from state it keeps itself has to say so (see telling Term::Fabulous that something changed).

Pointer movement is the one exception to "drawn at the next check": when frames take long to draw, a frame that only shows the pointer at a new position is drawn at most at every other check, so that moving the mouse cannot keep the program busy with nothing but redrawing.

REQUIREMENTS

Perl 5.32.1 or later.
A C compiler. termbox2 ships with the distribution and is compiled into Term::Fabulous::Termbox when Term::Fabulous is installed, with truecolor and grapheme cluster support always on; there is no separate library to install or find.
A terminal that understands 24-bit ("truecolor") colors. Most modern terminals do (xterm, GNOME Terminal, Konsole, kitty, iTerm2, Windows Terminal), and so does tmux with truecolor enabled (see "Colors are wrong or look washed out" in Term::Fabulous::Manual::Troubleshooting). In a terminal without truecolor support, the colors come out wrong.
A UTF-8 locale, for example LANG=C.UTF-8 or LANG=en_US.UTF-8 (locale -a lists the installed ones). Without it, wide characters such as CJK text and emoji cannot be placed correctly, and run warns about it when it starts.
For mouse support, a terminal that reports mouse events. Nearly all do; see "MOUSE" in Term::Fabulous::Manual::Events for what is reported.
Optional: Imager, for pictures in Term::Fabulous::Widget::Image, with the image libraries (libpng, libjpeg, ...) of the formats you want to show. Installing Term::Fabulous does not require it; without it, an image widget shows a notice in its place.
Optional: Imager::File::SIXEL with Imager, for pictures in sixel graphics in Term::Fabulous::Widget::Sixel, and a terminal that shows sixel graphics and reports the size of its cells. Without them, a sixel widget shows a notice in its place.

YOUR FIRST PROGRAM

This program shows a dark blue screen with a framed greeting in the middle and ends when you press q, Escape or Ctrl+C. It is shipped as examples/cookbook/first-program.pl; run it with perl examples/cookbook/first-program.pl (see "RUNNING THE EXAMPLES" in Term::Fabulous::Examples).

use v5.32;
use warnings;
use feature 'signatures';
no warnings 'experimental::signatures';

use Clay::XS qw(sizing_grow CLAY_ALIGN_X_CENTER CLAY_ALIGN_Y_CENTER);
use Term::Fabulous;
use Term::Fabulous::Enum::BorderStyle;
use Term::Fabulous::Widget::Box;
use Term::Fabulous::Widget::Text;

# The root widget fills the whole terminal and centers its child.
my $root = Term::Fabulous::Widget::Box->new(
	background_color => [ 20, 25, 45, 255 ],
	layout           => {
		sizing          => { width => sizing_grow(),       height => sizing_grow() },
		child_alignment => { x     => CLAY_ALIGN_X_CENTER, y      => CLAY_ALIGN_Y_CENTER },
	},
);

# A box with a rounded border, one cell of space left and right of the text.
my $frame = Term::Fabulous::Widget::Box->new(
	bordered     => 1,
	border_style => Term::Fabulous::Enum::BorderStyle->Round,
	border_color => [ 120, 170, 255, 255 ],
	layout       => { padding => { left => 1, right => 1 } },
);
$frame->add_child(
	Term::Fabulous::Widget::Text->new(
		text       => 'Hello, terminal! Press q to quit.',
		text_color => [ 255, 255, 255, 255 ],
	)
);
$root->add_child($frame);

my $ui = Term::Fabulous->new( root => $root, width => 80, height => 24 );

# Nothing has the keyboard focus, so key presses go to the root widget.
$root->on(
	KeyPress => sub ($event) {
		my $name = $event->key_name // '';
		$ui->loop->stop if $name eq 'q' || $name eq 'Escape';
		return;
	}
);

$ui->run;    # returns when the loop stops
say 'Bye!';

The first program: a greeting in a box with a rounded blue border, centered on a dark blue screen

What happens here:

Term::Fabulous::Widget::Box is the general container. It can have a background color, a border and any number of children.
The layout hash tells Clay how to size and arrange the box and its children (see "LAYOUT" in Term::Fabulous::Manual::Layout). sizing_grow() means "take all the room the parent offers"; a box without sizing is as big as its content. child_alignment centers the children (see "Aligning and centering children" in Term::Fabulous::Manual::Layout).
Term::Fabulous::Widget::Text shows one piece of text. Colors are [red, green, blue, alpha] arrays with values from 0 to 255; color strings such as '#78aaff' work too (see "COLORS" in Term::Fabulous::Manual::Looks). The border style comes from Term::Fabulous::Enum::BorderStyle (see "BORDERS" in Term::Fabulous::Manual::Looks).
Term::Fabulous->new takes the root widget and an initial size. width and height are required, but run replaces them with the real terminal size.
$root->on( KeyPress => sub { ... } ) registers a listener: code that runs when the event happens (see "EVENTS" in Term::Fabulous::Manual::Events). Key presses go to the widget that has the keyboard focus, or to the root widget when no widget has it, as here. key_name returns a readable name of the key, such as q, Escape or Ctrl+Left (see "KEYBOARD" in Term::Fabulous::Manual::Events).
$ui->run opens the terminal, handles input and draws frames until the loop stops: when a listener calls $ui->loop->stop, when the user presses Ctrl+C, or when the process receives SIGINT, SIGTERM or SIGHUP. Then it restores the terminal and returns, and the program prints Bye! on the normal screen.
Quitting on Escape does not catch Alt plus a letter: terminals send that as Escape followed by the letter, in one write, and Term::Fabulous names it Alt+x (see "Key names" in Term::Fabulous::Manual::Events).

Where to go next: Term::Fabulous::Manual::Layout explains the widget tree and the layout, and the recipe A minimal program to start from is a program to start your own from.

FEATURE INDEX

Where to find what, by task. Each entry names the section of the manual that explains the feature, the recipes that show it in a complete program, and the class pages with the reference.