Skip to content

Your First Program

The best way to learn xnano is to build something with it. In this guide, we will build a focus timer. The timer does these things:

  • It counts down from 25 minutes.
  • It shows its progress on a bar.
  • It pauses and continues when you press the space bar.
  • It plays a bell sound when no time remains.

The program is small, but it uses all the main ideas of xnano: a canvas, placements, hooks, a widget and a sound. Make a file with the name focus.py. From the second step, each step shows the full file, and the highlighted lines are new.

Open a terminal

Every xnano program draws on a canvas. xnano.open() makes a canvas, shows it in your terminal window and returns it as a terminal. When the with block ends, xnano closes the canvas and gives the window back to your shell.

focus.py
import xnano

with xnano.open(height=5) as terminal:  # >> [open]
    terminal.write('Focus', bold=True)  # >> [write]
    terminal.write('25:00', foreground='cyan')  # >> [write]
    terminal.run(stop_on='q')  # >> [run]

The canvas uses a region of five rows, directly below your prompt. If you leave out height, the canvas fills the whole window. When the canvas closes, xnano erases the region.

Writes text on the screen of the canvas. terminal.write() is the same as terminal.screen.write(). Without a position, each write() puts its text on the next line. bold and foreground set the style of the text.

Shows text, a widget, an image or another canvas on the screen. It returns a placement.

Keeps the program open until you press q. During this time, the terminal draws the screen and reads the keys by itself. Without stop_on, ctrl+c stops the program.

learn-first-program-open learn-first-program-open

Run the program with python focus.py. To stop it, press q.

Count down

write() returns a placement, a live handle on the content that you wrote. If you set the text of a placement, the screen shows the new text on the next frame. You do not have to call anything else.

To change the time each second, we add a hook. A hook is a function that xnano calls when something happens. xnano gives the hook a context, which holds the event and the devices of the canvas, such as its clock.

focus.py
import xnano

MINUTES = 25
SECONDS = MINUTES * 60

with xnano.open(height=5) as terminal:
    terminal.write('Focus', bold=True)
    countdown = terminal.write(f'{MINUTES:02}:00', foreground='cyan')

    @terminal.hook(on='tick', every=1.0)  # >> [hook]
    def count_down(context: xnano.Context):  # >> [hook]
        remaining = max(0, SECONDS - round(context.clock.elapsed_seconds))  # >> [clock]
        minutes, seconds = divmod(remaining, 60)
        countdown.text = f'{minutes:02}:{seconds:02}'  # >> [placement]

    terminal.run(stop_on='q')

countdown is the placement of the time. When you set its text, the new text replaces the old text.

@terminal.hook(...) makes count_down a hook of the terminal. With on='tick' and every=1.0, xnano calls it one time each second.

What xnano gives to a hook: the event, and the devices of the canvas, such as context.clock.

elapsed_seconds is the time in seconds since the canvas started. round() makes it a whole number, and max(0, ...) stops the count at zero.

Pause with a key

A hook with on='key' runs when you press a key. keys='space' makes it run only for the space bar. The clock has a pause() method and a resume() method. While the clock is paused, everything that follows the clock stops. This includes our tick hook.

While the timer is paused, we make the time dim, so you can see the pause immediately. A hint on the last row tells you which keys to use.

focus.py
import xnano

MINUTES = 25
SECONDS = MINUTES * 60

with xnano.open(height=5) as terminal:
    terminal.write('Focus', bold=True)
    countdown = terminal.write(f'{MINUTES:02}:00', foreground='cyan')
    terminal.write('space pause · q quit', y='bottom', dim=True)  # >> [hint]

    @terminal.hook(on='tick', every=1.0)
    def count_down(context: xnano.Context):
        remaining = max(0, SECONDS - round(context.clock.elapsed_seconds))
        minutes, seconds = divmod(remaining, 60)
        countdown.text = f'{minutes:02}:{seconds:02}'

    @terminal.hook(on='key', keys='space')  # >> [key]
    def pause_or_resume(context: xnano.Context):
        if context.clock.is_paused:
            context.clock.resume()
        else:
            context.clock.pause()
        countdown.dim(context.clock.is_paused)  # >> [dim]

    terminal.run(stop_on='q')

y='bottom' puts the hint on the last row. A line with its own y stays at that row. It does not move the other lines, and the other lines do not move it.

xnano calls this hook when you press the space bar. If you hold the key, xnano calls the hook again each time the key repeats.

dim(True) makes the text dim, and dim(False) makes it normal again. The value here is is_paused, so the time is dim only while the clock is paused.

Show the progress

A widget shows more than text, for example a gauge, a chart, a table or a list. A Gauge is a bar that fills to a ratio from 0 to 1.

We can change the gauge in the tick hook, but there is a shorter method. Arithmetic on the clock, such as terminal.clock / SECONDS, gives an expression. An expression is a value that xnano calculates again on each frame. If you give an expression to the gauge, the gauge follows the clock without a hook. The gauge also stops while the clock is paused.

focus.py
import xnano
from xnano.widgets import Gauge

MINUTES = 25
SECONDS = MINUTES * 60

with xnano.open(height=5) as terminal:
    terminal.write('Focus', bold=True)
    countdown = terminal.write(f'{MINUTES:02}:00', foreground='cyan')
    terminal.write(Gauge(terminal.clock / SECONDS), width='100%')  # >> [gauge]
    terminal.write('space pause · q quit', y='bottom', dim=True)

    @terminal.hook(on='tick', every=1.0)
    def count_down(context: xnano.Context):
        remaining = max(0, SECONDS - round(context.clock.elapsed_seconds))
        minutes, seconds = divmod(remaining, 60)
        countdown.text = f'{minutes:02}:{seconds:02}'

    @terminal.hook(on='key', keys='space')
    def pause_or_resume(context: xnano.Context):
        if context.clock.is_paused:
            context.clock.resume()
        else:
            context.clock.pause()
        countdown.dim(context.clock.is_paused)

    terminal.run(stop_on='q')

width='100%' makes the gauge as wide as the screen. Its ratio is the elapsed time divided by the full time. A gauge does not fill past 1, so the expression needs no limit.

A bar that fills to a ratio and shows the percentage on it.

Ring the bell

Last, the timer must tell you that no time remains. When remaining is 0, the tick hook does three things:

  • It shows done in green.
  • It removes itself, so the count stops.
  • It plays three notes with a bell sound.

Sound needs the audio extra, and Installation shows how to install it. If the extra is not installed, context.speaker raises an ImportError that tells you what to install. On a computer without a sound device, speaker.is_available is False, and the timer finishes without a sound.

focus.py
import xnano
from xnano.widgets import Gauge

MINUTES = 25
SECONDS = MINUTES * 60

with xnano.open(height=5) as terminal:
    terminal.write('Focus', bold=True)
    countdown = terminal.write(f'{MINUTES:02}:00', foreground='cyan')
    terminal.write(Gauge(terminal.clock / SECONDS), width='100%')
    terminal.write('space pause · q quit', y='bottom', dim=True)

    @terminal.hook(on='tick', every=1.0)
    def count_down(context: xnano.Context):
        remaining = max(0, SECONDS - round(context.clock.elapsed_seconds))
        minutes, seconds = divmod(remaining, 60)
        countdown.text = f'{minutes:02}:{seconds:02}'
        if remaining == 0:
            countdown.text = 'done'  # >> [done]
            countdown.color.fg = 'green'  # >> [done]
            context.hook.remove()  # >> [remove]
            if context.speaker.is_available:
                context.speaker.play('C5 E5 G5:2', instrument='bell')  # >> [bell]

    @terminal.hook(on='key', keys='space')
    def pause_or_resume(context: xnano.Context):
        if context.clock.is_paused:
            context.clock.resume()
        else:
            context.clock.pause()
        countdown.dim(context.clock.is_paused)

    terminal.run(stop_on='q')

The time changes to done. color.fg is the text color of a placement, so the word shows in green.

context.hook is the hook that runs now. remove() stops it, so xnano does not call it again.

The text is a melody of three notes, and :2 makes the last note two beats long. Sound explains melody text.

learn-first-program-finished learn-first-program-finished

That is the full timer. To see the end sooner, set MINUTES = 1.

Next steps

The other guides explain each part in more detail:

  • Writing Content: positions, sizes, boxes, layouts and layers.
  • Styling: colors, text modifiers, and style changes after you write.
  • Hooks & Input: the keyboard, the mouse and pasted text.
  • Time & Effects: the clock, timers, expressions and effects.
  • Widgets: gauges, charts, tables and lists.
  • Images & Pixel Art: pixel art and pictures.
  • Sound: notes, melodies and the microphone.
  • Testing: tests for a program like this timer, without a terminal.