Pictures and windows

The builtin gui module draws pictures and shows them in windows. A picture is a canvas, an image a program draws on; a window shows a canvas on the screen and reports what the keyboard and mouse do to it.

Canvases

gui.blank(width, height, color) makes a canvas, and its methods draw on it: set a pixel, rect and outline a rectangle, line, circle and disc, blit another canvas, and text in an 8 by 8 pixel font. A color is an int, 0xRRGGBB, as gui.rgb(r, g, b) makes it. get(x, y) reads a pixel back, as an option since the point may be off the canvas, and ppm() turns the canvas into the bytes of a PPM image file, which most image viewers open.

// Drawing on a canvas: a disc, text, and a line, printed with a character for each pixel, then
// saved as an image file.
use fs
use gui

// Prints `c` with a character for each pixel: `#` for white, `o` for gold, and `.` for the rest.
fn show(c: gui.canvas):
    for y in range(c.height):
        row = ""
        for x in range(c.width):
            color = c.get(x, y).unwrap()
            if color == gui.rgb(255, 255, 255):
                row += "#"
            elif color == gui.rgb(241, 194, 50):
                row += "o"
            else:
                row += "."
        print(row)

c = gui.blank(30, 11, gui.rgb(20, 24, 40))
c.disc(23, 5, 4, gui.rgb(241, 194, 50))
c.text(1, 1, "hi", gui.rgb(255, 255, 255))
c.line(0, 10, 29, 10, gui.rgb(255, 255, 255))
show(c)

print(fs.write_bytes("picture.ppm", c.ppm()))

prints

..............................
.###.......##........ooooo....
..##................ooooooo...
..##.##...###......ooooooooo..
..###.##...##......ooooooooo..
..##..##...##......ooooooooo..
..##..##...##......ooooooooo..
.###..##..####.....ooooooooo..
....................ooooooo...
.....................ooooo....
##############################
ok(1003)

A canvas is a value like a list, so d = c makes a canvas of its own, and a function that draws on one returns it, as xs = f(xs) does. Drawing outside the canvas draws nothing there, so a shape may hang over an edge.

Windows

gui.open(title, width, height) opens a window, and show(c) shows a canvas in it. events() returns what has happened since it was last called, without waiting, as a list of gui.event values: key_down and key_up with the key’s name ("a", "enter", "left"), text with what a key typed, mouse_move, mouse_down, and mouse_up with the point (and the button’s name), scroll, resize with the new size, redraw when the window lost what it showed, close when its close button is pressed, and failed if the connection to the display breaks. next_frame() returns the same events, after waiting until the screen has shown the last image, so a loop that reads events with it, draws, and shows makes an animation at the screen’s own rate, with no tearing:

use gui

w = gui.open("bounce", 320, 240).unwrap()
c = gui.blank(320, 240, 0)
x = 0
while w.is_open():
    es = w.next_frame()
    for e in es:
        match e:
            case gui.event.key_down(key):
                if key == "escape":
                    w.close()
            case gui.event.close:
                w.close()
            case _:
                cont
    c.fill(gui.rgb(20, 24, 40))
    c.disc(x, 120, 20, gui.rgb(241, 194, 50))
    w.show(c)
    x = (x + 4) % 320

wait() waits for at least one event instead, for a program that changes only when the user does something. Pressing the close button closes nothing by itself: the program decides, here by calling close().

A window speaks the Wayland or X11 protocol to the display server itself, so a built program still needs no C library. Every Linux desktop has a Wayland compositor or an X11 server, and a Mac has an X11 server with XQuartz. gui.open finds it through WAYLAND_DISPLAY or DISPLAY, preferring Wayland, and without either it returns an error. Where a Wayland compositor draws no title bars, as on GNOME, gui draws its own.

On Windows (10 version 1703 or later), a window is an ordinary Win32 window and needs no display variable. It repaints itself from the last canvas shown, so redraw never comes there, and the program goes on running while the window is dragged or resized. Build a program with windows using stone build --windows-gui so that opening it from Explorer opens no console beside it (see the CLI reference).

Sizes, points, and canvases are in logical pixels, so a window is as big on a screen scaled to 200% as on one at 100%: there, each pixel of a canvas is two of the screen’s across, and at 150% one or two. w.scale() says how many of the screen’s pixels a logical one is, as the system’s display settings make it for the monitor the window is on, and STONE_GUI_SCALE (from 0.5 to 8) sets it instead. When the scale changes, the window keeps its size in logical pixels and gets a redraw event.

Apps

Most programs with a window keep some state, change it at each event, and draw it. The gui.app trait names those three steps, and gui.run(title, width, height, state) runs them: at each frame, as next_frame paces them, it gives update every event, plus a tick with the seconds since the last one, then calls draw with a canvas as big as the window and shows what it returns, until the close button is pressed or done returns true:

use gui

struct counter:
    clicks: int

impl gui.app for counter:
    fn update(self, e: gui.event):
        match e:
            case gui.event.mouse_down(_, _, _):
                self.clicks += 1
            case _:
                ret

    fn draw(self, c: gui.canvas) -> gui.canvas:
        c.fill(gui.rgb(255, 255, 255))
        c.text_scaled(10, 10, "clicks: {self.clicks}", 0, 2)
        ret c

    fn done(self) -> bool:
        ret self.clicks >= 10

print(gui.run("counter", 300, 100, counter(clicks=0)))

update changes the state in place, as a method that changes self does, and draw only reads it. run returns ok of the last state, so the program can go on with it after the window closes, or an err if the window does not open or its connection breaks.

For a bigger program, examples/spin.stn in the repository draws spinning 3D shapes: it builds meshes with math.sin and math.cos, turns and lights them, sorts their faces with sort_by_key, and fills them in on a canvas, all in stone. Built with stone build examples/spin.stn and run as examples/build/spin, it draws a frame each time the screen refreshes.

That is the whole tutorial. The Syntax and Builtins pages cover the details, including every method of a socket and of a canvas and a window.