• _images/root.tpi.6a542c2fd0.png


  • _images/root-fillchar.tpi.5204f1cd9e.png

    with fill character

ZRoot is designed as the root widget in the widget tree.

It sets a default palette, clears the widget and handles switching between windows using F6 and Shift+F6.

Commonly an application has a class derived from ZRoot to setup the user interface widget tree. It is recommended to create the widgets in an overriden terminalChanged() function, so that all terminal auto detection is already finished when the widget tree is build.


Tui::ZTerminal terminal;

Tui::ZRoot root;


See Getting started for an example overriding terminalChanged() to setup the user interface.

Keyboard Usage






Activate next widget in tab order



Activate previous widget in tab order


ZRoot has by default a minimum size of (40, 7) to raise the chance that applications not tested with very small terminals are still somewhat usable. If an application needs a bigger size to be usable or wants to support smaller sizes it can override this to a suitable value.

If the terminal is smaller than the minimum size of the root widget (as set in the terminal) the terminal will enable a minimal viewport scrolling interface so that the root widget still renders at the minimum size and the user can view parts of the root widget by using the keyboard to scroll the viewport.

See Viewport for details.

If any child widget of ZRoot implements the Tui::ZWindowFacet and its isExtendViewport() const returns true the minimal size for the root widget is temporarily extended to include the whole child widget. This enables selected dialogs and menus to be usable even if the terminal is smaller than the widget.

ZRoot by default has the Tui::ZPalette::classic() palette set as palette. This palette defines the colors used by the widgets in Tui Widgets. The predefined palettes only enable palette colors for widgets that are typically used in windows for widgets that are contained in a widget that has window as the widget’s palette class such as Tui::ZWindow or Tui::ZDialog.

If ZRoot is resized windows that are neither manually placed nor in a window container according to their Tui::ZWindowFacet facet implementation are placed using their window facet’s auto place implementation.

The layout area of ZRoot is usually its geometry with the contents margins removed. If the root widgets size is currently expanded due to a window using isExtendViewport the layout area will not reflect the temporarily larger geometry due to this window.


Palette Color



The body of the widget.


class Tui::ZRoot : public Tui::ZWidget

A widget designed to be used as root of the widget tree.


void setFillChar(int fillChar)
int fillChar() const

The fill character is what character is used to clear the widgets background.

It defaults to Tui::Erased.

This allows for more faithful emulation of the classic look.

void activateNextWindow()
void activatePreviousWindow()

Activate the next/previous child window in the widget.

Eligible child widgets to activate are widgets that are visible, implement the Tui::ZWindowFacet facet and where ZWidget *placeFocus(bool last) returns a widget (not nullptr).

After activation it will be raised using raiseOnActivate(ZWidget *w).

void raiseOnActivate(ZWidget *w)

Override this function to customize if and how a window is raised when activated.

The base implementation raises the window using void Tui::ZWidget::raise().

Protected Functions

void terminalChanged()

This function is called when the terminal changes.

In applications that don’t move the root widget between terminals, it will be called once after the terminal auto detection is finished.

Applications should override this method to build their widget tree.

The base implementation does nothing.