WINDOWS

Satellite can open real windows on your desktop, with buttons, text boxes, sliders, menus and drawings in them. Everything you need is under one word, satellite.window, and everything it makes is held in one type, satellite.variable.window.

Every example on this page opens a window, so none has an output box. Save one and run it on your own desktop with satl name.satl.

Your first window

Three steps make every window:

1. Make the window with satellite.window.new(title, width, height).
2. Make a piece, such as satellite.window.button("text").
3. Put the piece in the window with my_window.append(piece, across, down). The position is where the piece’s centre goes, so 400, 300 is the middle of an 800 by 600 window.

A piece talks back by running a capsule you name. .pressed(when_pressed) on a button means “when someone presses this, run the capsule when_pressed“. You write the capsule’s name bare, with no quotes, and satl checks that capsule exists before the program starts.

satellite.include(satellite)

satellite.capsule when_pressed(satellite.variable.window the_piece, satellite.variable.window its_window)
{
    satellite.console.display("the button was pressed")
    its_window.close()
}

satellite.capsule satellite.main()
{
    satellite.variable.window my_window = satellite.window.new("window_title", 800, 600)

    satellite.variable.window my_button = satellite.window.button("text")
    my_button.pressed(when_pressed)

    my_window.append(my_button, 400, 300)

    satellite.console.display(my_window)

    satellite.return(satellite)
}

The program’s own lines run straight away, so (window "window_title") appears in your terminal at once. Then satl waits: a program does not end while one of its windows is open. Press the button and the capsule runs, writes its line and closes the window, and the program ends. Closing the window yourself ends it too.

A capsule named by .pressed may take nothing, the piece that was pressed, or the piece and the window it is in. There are no global variables in satellite, so the window handed to the capsule is how it reaches the window to close it.

Pieces, and reading what people type

These make pieces, each a satellite.variable.window:

• button(text), label(text), text_box(text), text_area(text), checkbox(text), switch()
• slider(least, most), number_box(least, most), progress(), choice(list), one_of(list)
• row(), column() and grid() to arrange other pieces, and scroll(), frame(title), split() and tabs() to hold them
• picture(path), canvas(width, height) and menu(title)

A row or a column takes .append(piece) and lines its pieces up. Most pieces can be read and set with the same word: .text reads the text, and .text("hi") sets it. .value, .on, .chosen and .title work the same way. .changed(a_capsule) runs a capsule whenever someone changes a piece.

satellite.include(satellite)

satellite.capsule when_typed(satellite.variable.window the_box)
{
    satellite.console.display(the_box.text)
}

satellite.capsule when_done(satellite.variable.window the_button, satellite.variable.window its_window)
{
    its_window.close()
}

satellite.capsule satellite.main()
{
    satellite.variable.window my_window = satellite.window.new("a form", 400, 300)
    satellite.variable.window a_column = satellite.window.column()
    satellite.variable.window your_name = satellite.window.text_box("")
    your_name.changed(when_typed)
    satellite.variable.window done = satellite.window.button("done")
    done.pressed(when_done)
    a_column.append(your_name)
    a_column.append(done)
    my_window.append(a_column, 200, 150)
    satellite.return(satellite)
}

Drawing on a canvas

A canvas is a piece you draw on. Its pen draws in the canvas’s .colour(...), and positions count from its top-left corner:

• .line(x1, y1, x2, y2) from one point to another
• .box(x, y, width, height) from its top-left corner
• .circle(x, y, radius) and .arc(x, y, radius, from, to), with the angles in degrees
• .write(x, y, "words"), in the font from .font("IBM Plex Mono", 18)
• .clear() wipes it, and .save("picture.png") saves what is drawn as a picture

satellite.include(satellite)

satellite.capsule satellite.main()
{
    satellite.variable.window my_window = satellite.window.new("a drawing", 400, 300)
    satellite.variable.window c = satellite.window.canvas(400, 300)
    c.colour("#40c8ff")
    c.line(0, 0, 399, 299)
    c.box(20, 20, 80, 50)
    c.circle(100, 200, 30)
    c.font("IBM Plex Mono", 18)
    c.write(150, 40, "hello from satellite")
    my_window.append(c, 200, 150)
    satellite.return(satellite)
}

Things a window can do

A window has its own words too:

• .close(), .focus(), .resize(1024, 768) and .fullscreen(1)
• .message("saved") shows a message, and .ask(a_capsule, "sure?") asks a question and runs the capsule with the answer in its_window.answer
• .every(a_capsule, 1000) runs a capsule every 1000 milliseconds, for as long as the window is open
• .closed(a_capsule) runs a capsule when the window is closed, and .key(a_capsule) when a key is pressed

satellite.include(satellite)

satellite.capsule tick()
{
    satellite.console.display("tick")
}

satellite.capsule stop(satellite.variable.window the_button, satellite.variable.window its_window)
{
    its_window.close()
}

satellite.capsule satellite.main()
{
    satellite.variable.window w = satellite.window.new("a clock", 300, 200)
    satellite.variable.window done = satellite.window.button("stop")
    done.pressed(stop)
    w.append(done, 150, 100)
    w.every(tick, 1000)
    satellite.return(satellite)
}

What satl refuses, and when

• Before anything runs: a wrong number of arguments, a method no piece has, and a capsule nobody wrote. A method this particular piece lacks, like .resize on a button, is refused when its line runs.
• Write 800, 600, never 800×600. Satellite reads x600 as a hex number.
• No screen, no window. On a machine with no display, such as a server reached over ssh, the first window word stops with S730 NO_DISPLAY and satl exits with 50. That is the machine, not your program: the same file opens its window on a desktop.
• Windows stay on the main thread. A window word used on a thread of your own is refused with S727.

One more word makes a window: satellite.console.new(title, width, height) makes a console of your own, a window whose whole inside is a terminal, with c.display("words") to write into it and c.typed(a_capsule) to hear each line a person types.

Where next

Every window word, piece and method is listed in the FULL REFERENCE. A window’s capsules are ordinary CAPSULES, and the help system has both window topics: see THE HELP SYSTEM.