NAME

Term::Fabulous::Cookbook - Recipes for common Term::Fabulous tasks

HOW TO USE THIS COOKBOOK

The cookbook is a collection of recipes: short, complete solutions to common tasks, each with a program you can run and change. The recipes are grouped by topic into fifteen pages. "THE RECIPES" below lists every page with every recipe on it. Each page lists its own recipes at the top and links to the previous and the next page, so you can also read the cookbook from start to end.

The cookbook shows how to do something. The concepts behind the recipes (layout, colors, events, focus, forms, charts, tables, KDL layouts) are explained in Term::Fabulous::Manual, and every class has a reference page of its own. The recipes link to the exact sections they rely on.

How a recipe is written

Every recipe solves one task. Its title names the task in plain words, often followed in parentheses by the classes, options or keywords it uses, so a search for the task or the class finds it: search this index (with / in perldoc Term::Fabulous::Cookbook, or with the browser on MetaCPAN), or the page of the topic.

A recipe starts with one sentence on its goal, introduced with "Goal:". Then it shows a complete program or a snippet, a picture of the program running (or the text it prints), and a list that explains the lines that matter, with links to the reference documentation.

A snippet is not a complete program. It shows the lines that change the program of another recipe and names that recipe with a link. When a snippet uses $root or $ui, these are the root widget and the Term::Fabulous object of that program.

Running the programs

You need not copy the programs: every complete program is shipped as a file in the distribution, and each recipe names its file. Most are in the examples/cookbook directory and start with this header:

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

Programs with non-ASCII text in their source add use utf8 after use warnings.

A few recipes show a demo program from the examples directory, which holds the programs of Term::Fabulous::Examples. Those start with use experimental 'signatures' instead of use feature 'signatures', and with a use lib "$FindBin::Bin/../lib/" line.

Run a program with perl FILE in a terminal that uses a UTF-8 locale and supports 24-bit colors (see "REQUIREMENTS" in Term::Fabulous::Manual), after installing Term::Fabulous. In an unpacked copy of the distribution that is built but not installed (perl Makefile.PL && make), add -Mblib:

perl -Mblib examples/cookbook/minimal-program.pl

Interactive programs take over the terminal (all of it, or a few rows below the shell's output in inline mode); Ctrl+C ends every one of them. Programs that only print something, such as a report made with Term::Fabulous::Static or the results of a test, print and end on their own.

The pictures are taken from the shipped files by running them in a terminal of the size shown, after the input the recipe describes, so they show exactly what the code does. They appear in the HTML version of the documentation, for example on MetaCPAN, but not in perldoc; programs that print text show that text in the recipe as well.