# ZRoot

- ZRoot

- 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 overridden `terminalChanged()` function, so that all terminal auto detection is already finished when the widget tree is build.

## Example

    Tui::ZTerminal terminal;

    Tui::ZRoot root;

    terminal.setMainWidget(&root);

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

## Keyboard Usage

Key | State | Result
--- | --- | ---
`F6` | normal | Activate next widget in tab order
``Shift`+`F6`` | normal | Activate previous widget in tab order

## Behavior

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.

ZRoot exposes `Tui::ZClipboard` as a facet. This facet is used as clipboard for copy and paste operations by other widgets in the application.

## Palette

Palette Color | Usage
--- | ---
`root.fg`, `root.bg` | The body of the widget.

## ZRoot

class Tui::ZRoot : public Tui::ZWidget

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

  Functions

  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.