DisplayScript

Functions and Drawables

A function packages up a sequence of statements into a value.

var f = function () {
    show("Hello from f!")
}

Later, you can call a function using parentheses () to run its statements.

var f = function () {
    show("Hello from f!")
}
f()

Use a function statement to create and name a function at the same time:

function f() {
    show("Hello from f!")
}
f()

Function parameters are values that are specified when a function is called:

function f(a, b, c) {
    show("Hello from f!")
    show(a)
    show(b)
    show(c)
}
f(1, 7, 29)

Here the parameters are named a, b, and c. These names are bound to the values 1, 7, and 29 when the function is called. You can call a function multiple times with different parameter values:

function f(a, b, c) {
    show("Hello from f!")
    show(a)
    show(b)
    show(c)
}
f(1, 7, 29)
f(8, 8, 8)
f("hi", "there", "friend")

Parameter values are also called arguments.

You can access bindings from outside the function definition as well:

var a = "Hello!"
function f(b) {
    show(a)
    show(b)
}
f(2)
f(8)

These bindings are captured by the function. See Bindings and Scope for more about captured bindings.

Functions can return a value using the return statement.

function average(a, b) {
    return (a + b) / 2
}
show(average(7, 11))

Returned values are passed back out of the function call. Here the return value of average is used as a parameter to show.

Drawables

A drawable represents an interface element.

var d = drawable {
    draw fill(gray(0.7))
    draw centered(text("This is a drawable!"))
}

Just like you can call a function, you can draw a drawable to run its statements.

var d = drawable {
    draw fill(gray(0.7))
    draw centered(text("This is a drawable!"))
}
draw d

You can create a drawable and name it at the same time with a drawable statement:

drawable example {
    draw fill(gray(0.7))
    draw centered(text("This is a drawable!"))
}
draw example

Functions and drawables are quite similar, but there are a few key differences. Drawables capture the current persistent identifier, while functions add their source location to the persistent identifier when called. This gives each drawable a consistent identity across frames: see State and Identity for more information about how identity works.

Drawables don't return values like functions do. They can be measured to return a size or tested for readiness to return whether or not they are ready to draw, but when drawn they return nothing.

Drawable Functions

Unlike functions, drawables don't take any parameters. To make a drawable based on some parameters, you can make a function that returns a drawable:

function label(title) {
    return drawable {
        draw centered(text(title))
    }
}
draw label("Hello!")

The drawable function syntax makes this easier: just add parentheses after a drawable name.

drawable label(title) {
    draw centered(text(title))
}
draw label("Hello!")

This definition of label works the same way as the earlier one. Putting parentheses after the drawable name in a drawable expression or statement will create a drawable function that makes a drawable from the statements within and returns it.

All the built-in drawables are returned by drawable functions. Check out the Drawable Function Index for a list of all built-in drawable functions.