NAME
Term::Fabulous::Manual::Troubleshooting - Solutions to common problems
DESCRIPTION
This page is part of Term::Fabulous::Manual. Previous page: Term::Fabulous::Manual::CustomWidgets. Next page: Term::Fabulous::Manual::Glossary.
This page lists common problems, each under a heading that describes the symptom or quotes the error message, with the cause and the solution. When a program dies, search this page for the start of its message. The limits of Term::Fabulous itself are listed under LIMITATIONS on the main page.
TROUBLESHOOTING
"tb_init failed: No such device or address"
$ui->run needs a terminal: the process has no controlling terminal, for example in a cron job, a service or a CI run. Print the widget tree as text with Term::Fabulous::Static there instead (see "RENDERING WITHOUT A TERMINAL" in Term::Fabulous::Manual::Programs), and test programs with Term::Fabulous::Terminal::Memory (see "TESTING" in Term::Fabulous::Manual::Programs).
"the terminal did not report its cursor position"
Inline mode asks the terminal where its cursor is (ESC [ 6 n) and waits a second for the answer. The terminal, or a program between it and yours, does not answer. Use a terminal that does (xterm-compatible terminals and tmux do), or run in full-screen mode.
"the locale's character set is not UTF-8"
$ui->run warns when the locale is not UTF-8, because wide characters are then misaligned. See "Wide characters (CJK, emoji) shift the rest of the line".
My text does not show (invisible text)
A Text widget takes the theme's text color unless it is given a text_color, so the text is invisible only when its text_color matches the background, for example a fixed dark color on a dark theme. Leave the text_color out, pick one that stands out from the background, or pass [0, 0, 0, 0] for the terminal's default text color. See "TEXT" in Term::Fabulous::Manual::Looks.
A newline shows as a replacement character
The Text has the wrap_mode CLAY_TEXT_WRAP_NONE, which keeps the whole text on one line and shows a "\n" as U+FFFD. Use CLAY_TEXT_WRAP_NEWLINES to break the text only at its newlines. See "Wrapping" in Term::Fabulous::Manual::Looks.
A long line is cut off at the edge of its box
A text with the wrap_mode CLAY_TEXT_WRAP_NEWLINES or CLAY_TEXT_WRAP_NONE keeps its width only while the widgets beside it can get narrower; after that it is cut off at its parent's edge. Put it in a Term::Fabulous::Widget::ScrollBox with horizontal => 1 to keep it whole and let the user scroll sideways. See "Wrapping" in Term::Fabulous::Manual::Looks.
"the widget tree has more elements than max_element_count (8192) allows"
The widget tree is too large for Clay's element table: by default at most 8190 widgets fit in a frame. Pass a larger max_element_count to Term::Fabulous->new, or show fewer widgets at a time, for example by building only the visible part of a long list, or by drawing many small items on a canvas instead. See "new" in Term::Fabulous.
A table shows no cursor
The cursor of a Term::Fabulous::Widget::Table is drawn only while the table, or a widget in one of its cells, has the keyboard focus. Give it the focus with Tab, a click, or $ui->interaction->set_focused_widget($table). See "The cursor" in Term::Fabulous::Manual::TableRows.
"a table needs an id"
Term::Fabulous::Widget::Table dies with Term::Fabulous::Widget::Table: a table needs an id (its body keeps its scroll position by it) when it is made without an id. Give every table an id that is unique in the widget tree, for example Term::Fabulous::Widget::Table->new( id => 'staff', ... ). See "TABLES" in Term::Fabulous::Manual::Tables.
Garbled characters in a Text widget, input, canvas or KDL layout
All of these take character strings. If your source code contains non-ASCII characters, add use utf8;. If the text comes from a file, a command or @ARGV, decode it first (decode('UTF-8', $bytes)); see "Text is character strings" in Term::Fabulous::Manual::Looks.
Wide characters (CJK, emoji) shift the rest of the line
The locale is not UTF-8 (run warns about it), or the terminal disagrees with the C library about the character's width. Set a UTF-8 locale, for example export LANG=C.UTF-8 (locale -a lists the installed locales).
Colors are wrong or look washed out
The terminal does not support 24-bit colors. Use a terminal that does; inside tmux, enable truecolor (set -as terminal-features ",*:RGB").
A KeyPress listener on the root never sees some keys
The focused widget used them, or one of its listeners (or one on a widget between it and the root) did not return Clay::UI::Enum::Result->CONTINUE. See "Return values and bubbling" in Term::Fabulous::Manual::Events.
A Mouse listener never fires
The widget draws nothing at the clicked cell (no background color, no border), so the click goes to the widget behind it, or it is a Text widget. Give the box a background color, or listen on an ancestor.
Hover effects do not follow the mouse
The terminal does not report mouse movement (mode 1003), or a terminal multiplexer between it and the program drops the reports. Clicks, drags and the wheel still work. See "What the terminal reports" in Term::Fabulous::Manual::Events.
A change from a timer does not show
Term::Fabulous draws a frame only when it knows that something changed. The widget methods tell it; state a widget of your own keeps itself does not. Call mark_changed on the widget after changing it, or $ui->invalidate. See Telling Term::Fabulous that something changed.
Unrecognised parameters for ... constructor
Every Term::Fabulous class rejects constructor parameters it does not know, to catch typos. Check the spelling against the class's documentation.
"Unrecognised parameters for Term::Fabulous::Widget::Table constructor: 'double_click_seconds'"
A table no longer has a double_click_seconds parameter: the time between the presses of a double click is set once for the whole program. Pass it to Term::Fabulous->new instead; see "new" in Term::Fabulous.
"Can't locate Term/Fabulous/Widget/RichText.pm"
The classes Term::Fabulous::Widget::RichText and Term::Fabulous::Widget::FocusableText are gone. Use Term::Fabulous::Widget::Text, which takes markup, spans and links itself (see "Styled spans inside one text" in Term::Fabulous::Manual::Looks). After an upgrade with make install, the old RichText.pm may still be on disk; loading it then dies with Already have a named constructor parameter called 'markup' inherited from Term::Fabulous::Widget::Text. Delete the stale Term/Fabulous/Widget/RichText.pm and FocusableText.pm from the installed library.
"palette token '...' needs exactly one string argument"
A theme file gives a palette token properties or child nodes, or more than one argument. A token takes exactly one string, its color, and nothing else: accent "#5fafff". Earlier versions read such a file without complaint; the theme editor always rejected it. See "Tokens" in Term::Fabulous::Theme.
The program dies with "is still attached to a parent"
A widget has one parent at a time, so add_child dies with Clay::UI: widget ... is still attached to a parent; remove it first for a widget that has one. Remove it from its current parent before adding it elsewhere; see "Changing the tree" in Term::Fabulous::Manual::Layout.
"'root' is already the root of another Clay::UI"
A widget tree belongs to one Term::Fabulous or Term::Fabulous::Static object at a time. Keep one object and call its methods again (run, render_lines) instead of creating a second one for the same root; see "new" in Term::Fabulous.
SEE ALSO
This page is part of Term::Fabulous::Manual. Previous page: Term::Fabulous::Manual::CustomWidgets. Next page: Term::Fabulous::Manual::Glossary.