Getting Started #

Let’s render a map of the world.

Installation #

First create a new project:

mkdir tui-demo
cd tui-demo

and require the php-tui package:

composer require php-tui/php-tui

Rendering #

Now create the file map.php with the following content:

<?php

declare(strict_types=1);

use PhpTui\Tui\DisplayBuilder;
use PhpTui\Tui\Extension\Core\Shape\MapResolution;
use PhpTui\Tui\Extension\Core\Shape\MapShape;
use PhpTui\Tui\Extension\Core\Widget\CanvasWidget;

require 'vendor/autoload.php';

$display = DisplayBuilder::default()->build();
$display->clear();
$display->draw(
    CanvasWidget::fromIntBounds(-180, 180, -90, 90)
        ->draw(
            MapShape::default()->resolution(MapResolution::High)
        )
);

The DisplayBuilder is a builder for the Display object, which is the primary entry point for the PHP-TUI library.
We call clear() to wipe the contents of the terminal.
We draw a widget on the display. The Widget objects are PHP-TUI’s building blocks.
The CanvasWidget is a special widget that allows us to draw arbitrary shapes.
The MapShape is an highly specialised example shape that is able to render the map of the world at either high or low resolutions.

Execute the script:

$ php map.php

and you should see something like the following:

Grids #

We’ve now rendered one widget to the entire screen. Let’s render more widgets!

To render multiple widgets we can use the GridWidget.

<?php

declare(strict_types=1);

use PhpTui\Tui\DisplayBuilder;
use PhpTui\Tui\Extension\Core\Shape\MapResolution;
use PhpTui\Tui\Extension\Core\Shape\MapShape;
use PhpTui\Tui\Extension\Core\Widget\CanvasWidget;
use PhpTui\Tui\Extension\Core\Widget\GridWidget;
use PhpTui\Tui\Extension\Core\Widget\ParagraphWidget;
use PhpTui\Tui\Layout\Constraint;
use PhpTui\Tui\Text\Text;
use PhpTui\Tui\Widget\Direction;

require 'vendor/autoload.php';

$display = DisplayBuilder::default()->build();
$display->clear();
$display->draw(
    GridWidget::default()
        ->direction(Direction::Horizontal)
        ->constraints(
            Constraint::percentage(50),
            Constraint::percentage(50)
        )
        ->widgets(
            CanvasWidget::fromIntBounds(-180, 180, -90, 90)
                ->draw(
                    MapShape::default()->resolution(MapResolution::High)
                ),
            ParagraphWidget::fromText(
                Text::parse(<<<'EOT'
                    The <fg=green>world</> is the totality of <options=bold>entities</>,
                    the whole of reality, or everything that is.[1] The nature of the
                    world has been <fg=red>conceptualized</> differently in different fields. Some
                    conceptions see the world as unique while others talk of a
                    plurality of <bg=green>worlds</>.
                    EOT)
            )
        )
);

We specify that the grid be Horizontal but it can also be Vertical (the default).
We specify constraints. Each constraint specifies the desired dimensions of a “section”. We use percentage. But we can also use length (absolute size) min (has to be at least) or max (cannot be more than).
Each “constraint” represents a section which can be filled with a widget. You cannot specify more widgets than there are constraints!

When you run the script you should see something like the following:

The grid is a widget, and you can nest grids arbitrarily to create complex layouts!

Blocks #

The BlockWidget contains other widgets and provide borders and padding:

<?php

declare(strict_types=1);

use PhpTui\Tui\DisplayBuilder;
use PhpTui\Tui\Extension\Core\Shape\MapResolution;
use PhpTui\Tui\Extension\Core\Shape\MapShape;
use PhpTui\Tui\Extension\Core\Widget\Block\Padding;
use PhpTui\Tui\Extension\Core\Widget\BlockWidget;
use PhpTui\Tui\Extension\Core\Widget\CanvasWidget;
use PhpTui\Tui\Extension\Core\Widget\GridWidget;
use PhpTui\Tui\Extension\Core\Widget\ParagraphWidget;
use PhpTui\Tui\Layout\Constraint;
use PhpTui\Tui\Text\Text;
use PhpTui\Tui\Text\Title;
use PhpTui\Tui\Widget\Borders;
use PhpTui\Tui\Widget\BorderType;
use PhpTui\Tui\Widget\Direction;

require 'vendor/autoload.php';

$display = DisplayBuilder::default()->build();
$display->clear();
$display->draw(
    GridWidget::default()
        ->direction(Direction::Horizontal)
        ->constraints(
            Constraint::percentage(50),
            Constraint::percentage(50)
        )
        ->widgets(
            BlockWidget::default()
                ->titles(Title::fromString('Left'))
                ->padding(Padding::all(2))
                ->borders(Borders::ALL)
                ->borderType(BorderType::Rounded)
                ->widget(
                    CanvasWidget::fromIntBounds(-180, 180, -90, 90)
                        ->draw(
                            MapShape::default()->resolution(MapResolution::High)
                        ),
                ),
            BlockWidget::default()
                ->titles(Title::fromString('Right'))
                ->padding(Padding::all(2))
                ->borders(Borders::ALL)
                ->borderType(BorderType::Rounded)
                ->widget(
                    ParagraphWidget::fromText(
                        Text::parse(<<<'EOT'
                            The <fg=green>world</> is the totality of <options=bold>entities</>,
                            the whole of reality, or everything that is.[1] The nature of the
                            world has been <fg=red>conceptualized</> differently in different fields. Some
                            conceptions see the world as unique while others talk of a
                            plurality of <bg=green>worlds</>.
                            EOT)
                    )
                ),
        )
);

We specify a title. Titles can also be aligned horizontally and vertically.
We specify 2 cells of padding on all sides.
We want borders on all sides
We want our borders to be rounded

When you run the script you should see something like the following: