Skip to content

Widgets

A widget is ready-made content, such as a gauge, a chart, a table or a list. You write a widget on the screen in the same way as text. A widget takes a position, a size, a border and a title, as text does. canvas.write() is the same as canvas.screen.write(), and canvas.render() is the same as canvas.screen.render().

The widgets are in xnano.widgets. xnano draws them with ratatui, a Rust library for terminal programs. Each section of this guide links to the ratatui widgets that draw the xnano widgets. The ratatui pages show more examples and all the options.

Gauges

A Gauge fills a bar to a ratio from 0 to 1 and shows a label on the bar. A LineGauge shows the same ratio on one line. xnano draws them with the ratatui widgets Gauge and LineGauge.

import xnano
from xnano.styles import Style
from xnano.widgets import Gauge, LineGauge

with xnano.new(width=48, height=4) as canvas:
    canvas.write(
        Gauge(0.62, label='62% of 512 GB', gauge_style=Style('green')), width='100%'
    )
    canvas.write(
        LineGauge(0.35, label='upload', filled_style=Style('cyan')), width='100%', y=2
    )
    print(canvas.render(format='ansi'))

learn-widgets-gauges learn-widgets-gauges

Sparklines and bar charts

A Sparkline shows a series of values as bars that are one cell wide. It shows the shape of the series in a small area. A BarChart shows bars, and each Bar has a value and an optional label. xnano draws them with the ratatui widgets Sparkline, BarChart and Bar.

import math

import xnano
from xnano.styles import Style
from xnano.widgets import Bar, BarChart, Sparkline

requests = [round(6 + 3 * math.sin(second / 4)) for second in range(46)]

with xnano.new(width=48, height=11) as canvas:
    canvas.write(
        Sparkline(requests, style=Style('cyan')),
        width='100%',
        height=3,
        border='rounded',
        title='requests',
    )
    canvas.write(
        BarChart(
            [Bar(73, label='cpu'), Bar(41, label='memory'), Bar(18, label='disk')],
            bar_width=8,
            bar_gap=2,
            bar_style=Style('magenta'),
        ),
        width='100%',
        height=7,
    )
    print(canvas.render(format='ansi'))

learn-widgets-charts learn-widgets-charts

Tables

A Table takes its rows as lists of cells. To style a full row, for example the header, use a TableRow. To style one cell, use a TableCell. xnano draws them with the ratatui widgets Table, Row and Cell.

import xnano
from xnano.styles import Style
from xnano.widgets import Table, TableCell, TableRow

with xnano.new(width=48, height=6) as canvas:
    canvas.write(
        Table(
            [
                ['web', 'up', '41 ms'],
                ['api', 'up', '12 ms'],
                ['db', TableCell('down', style=Style('red')), '—'],
            ],
            header=TableRow(['service', 'status', 'p95'], style=Style(bold=True)),
        ),
        width='100%',
        border='rounded',
        title='services',
    )
    print(canvas.render(format='ansi'))

learn-widgets-table learn-widgets-table

Lists and tabs

An ItemList shows a list of items. selected sets the selected item, and highlight_symbol and highlight_style mark it. Tabs shows a row of titles, and selected sets the selected title. xnano draws them with the ratatui widgets List and Tabs.

import xnano
from xnano.styles import Style
from xnano.widgets import ItemList, Tabs

with xnano.new(width=48, height=6) as canvas:
    canvas.write(
        Tabs(
            ['mail', 'calendar', 'contacts'],
            selected=0,
            highlight_style=Style('yellow', bold=True),
        ),
        width='100%',
    )
    canvas.write(
        ItemList(
            ['inbox', 'drafts', 'sent', 'archive'],
            selected=1,
            highlight_symbol='› ',
            highlight_style=Style(reverse=True),
        ),
        height=4,
        y=2,
    )
    print(canvas.render(format='ansi'))

learn-widgets-lists learn-widgets-lists

Change a widget

A widget stays live after you write it, like a placement. Set one of its values, and the next frame shows the change. For example, selected of an ItemList moves the highlight, and ratio and label of a Gauge change its bar and its text. This list follows the arrow keys:

import xnano
from xnano.styles import Style
from xnano.widgets import Gauge, ItemList

folders = ['inbox', 'drafts', 'sent', 'archive']
unread = {'inbox': 12, 'drafts': 3, 'sent': 0, 'archive': 48}

with xnano.open(height=6) as terminal:
    items = ItemList(
        folders, selected=0, highlight_symbol='› ', highlight_style=Style(bold=True)
    )
    share = Gauge(unread['inbox'] / 48, label='12 unread')
    terminal.write(items, width=20, height=4)
    terminal.write(share, x=20, y=0, width=20, height=1)
    terminal.write('↑ ↓ choose · q quit', y='bottom', dim=True)

    @terminal.hook(on='key', keys=['up', 'down'])
    def choose(context: xnano.Context):
        step = 1 if context.keyboard.key == 'down' else -1
        items.selected = (items.selected + step) % len(folders)  # >> [selected]
        count = unread[folders[items.selected]]
        share.ratio = count / 48  # >> [gauge]
        share.label = f'{count} unread'  # >> [gauge]

    terminal.run(stop_on='q')

Moves the highlight one item up or down. % takes it from the last item to the first item, and back.

The gauge shows the folder that is selected. You do not write the gauge again.

Widgets that follow the clock

Each number and text in a widget can be an expression. xnano calculates an expression again on each frame. This gauge fills in ten seconds, and it needs no hook:

import xnano
from xnano.widgets import Gauge

with xnano.open(height=2) as terminal:
    terminal.write(Gauge(terminal.clock / 10), width='100%')
    terminal.write('q quit', y='bottom', dim=True)
    terminal.run(stop_on='q')

learn-widgets-expression learn-widgets-expression

More widgets

xnano.widgets has more widgets:

Widget What it shows ratatui widget
Chart Line and scatter plots of datasets on two axes Chart
Calendar A month, with a style for each event date in events Monthly
Scrollbar The position in content that is longer than its area Scrollbar
Paragraph Text that wraps, aligns and scrolls Paragraph
Figure Lines, circles, rectangles, points and maps on a plane with coordinates Canvas

The xnano.widgets reference gives the arguments of each widget.