Command reference

This documentation is still missing some parts. Refer to the Nodebox documentation for the best reference in the meantime.

Drawing shapes

rect(x, y, width, height, roundness=0, draw=True, fill=None)

Draw a rectangle.

Parameters:
  • x – top left x-coordinate
  • y – top left y-coordinate
  • width – rectangle width
  • height – rectangle height
  • roundness – rounded corner radius
  • draw (boolean) – whether to draw the shape on the canvas or not
  • fill – fill color
test
rect(10, 10, 35, 35)
# see how roundness affects the shape
rect(55, 10, 35, 35, 0.3)
rect(10, 55, 35, 35, 0.7)
rect(55, 55, 35, 35, 1)
ellipse(x, y, width, height, draw=True)

Draw an ellipse. Same as oval().

Parameters:
  • x – top left x-coordinate
  • y – top left y-coordinate
  • width – ellipse width
  • height – ellipse height
  • draw (boolean) – whether to draw the shape on the canvas or not
test
ellipse(10, 20, 30, 60)
ellipse(50, 30, 40, 40) # circle
arrow(x, y, width, type=NORMAL, draw=True)

Draw an arrow.

Parameters:
  • x – arrow tip x-coordinate
  • y – arrow tip y-coordinate
  • width – arrow width (also sets height)
  • type (NORMAL or FORTYFIVE) – arrow type
  • draw (boolean) – whether to draw the shape on the canvas or not
test
arrow(50, 40, 40) # NORMAL is the default arrow type
arrow(90, 40, 40, FORTYFIVE)
star(startx, starty, points=20, outer=100, inner=50, draw=True)

Draw a star-like polygon.

Parameters:
  • startx – center x-coordinate
  • starty – center y-coordinate
  • points – amount of points
  • outer – outer radius
  • inner – inner radius
  • draw (boolean) – whether to draw the shape on the canvas or not
test
star(25, 25, 5, 20, 10)  # top left
star(75, 25, 10, 20, 3)  # top right
star(25, 75, 20, 20, 17) # bottom left
star(75, 75, 40, 20, 19) # bottom right
line(x1, y1, x2, y2, draw=True)

Draw a line from (x1,y1) to (x2,y2).

Parameters:
  • x1 – x-coordinate of the first point
  • y1 – y-coordinate of the first point
  • x2 – x-coordinate of the second point
  • y2 – y-coordinate of the second point
  • draw (boolean) – whether to draw the shape on the canvas or not
test
stroke(0.5)
strokewidth(3)
line(20, 20, 80, 80)
line(20, 80, 80, 20)
line(50, 20, 50, 80)
rectmode(mode=None)

Change the way rectangles are specified. Each mode alters the parameters necessary to draw a rectangle using the rect() function.

Parameters:mode (CORNER, CENTER or CORNERS) – the mode to draw new rectangles in

There are 3 different modes available:

  • CORNER mode (default)
    • x-value of the top left corner
    • y-value of the top left corner
    • width
    • height
  • CENTER mode
    • x-coordinate of the rectangle’s center point
    • y-coordinate of the rectangle’s center point
    • width
    • height
  • CORNERS mode
    • x-coordinate of the top left corner
    • y-coordinate of the top left corner
    • x-coordinate of the bottom right corner
    • y-coordinate of the bottom right corner

So while you always specify 4 parameters to the rect() function, you can use rectmode() to change the function’s behaviour according to what might suit your script’s needs.

test
nofill()
strokewidth(2)

rectmode(CORNER)  # default, red
stroke(0.8, 0.1, 0.1)
rect(25, 25, 40, 40)

rectmode(CENTER)  # green
stroke(0.1, 0.8, 0.1)
rect(25, 25, 40, 40)

rectmode(CORNERS)  # blue
stroke(0.1, 0.1, 0.8)
rect(25, 25, 40, 40)
ellipsemode(mode=None)

Change the way ellipses are specified. Each mode alters the parameters necessary to draw an ellipse using the ellipse() function.

It works exactly the same as the rectmode() command.

test
nofill()
strokewidth(2)

ellipsemode(CORNER)  # default, red
stroke(0.8, 0.1, 0.1)
ellipse(25, 25, 40, 40)

ellipsemode(CENTER)  # green
stroke(0.1, 0.8, 0.1)
ellipse(25, 25, 40, 40)

ellipsemode(CORNERS)  # blue
stroke(0.1, 0.1, 0.8)
ellipse(25, 25, 40, 40)

Bézier paths

beginpath(x=None, y=None)

Begin drawing a Bézier path. If x and y are not specified, this command should be followed by a moveto() call.

Parameters:
  • x (float or None) – x-coordinate of the starting point
  • y (float or None) – y-coordinate of the starting point
moveto(x, y)

Move the Bézier “pen” to the specified point without drawing; coordinates are absolute.

Parameters:
  • x (float) – x-coordinate of the point to move to
  • y (float) – y-coordinate of the point to move to
relmoveto(x, y)

Move the Bézier “pen” to the specified point without drawing; coordinates are relative to the pen’s current location.

Parameters:
  • x (float) – x-coordinate of the point to move to, relative to the pen’s current point
  • y (float) – y-coordinate of the point to move to, relative to the pen’s current point
lineto(x, y)

Draw a line from the pen’s current point; coordinates are absolute.

Parameters:
  • x (float) – x-coordinate of the point to draw to, relative to the pen’s current point
  • y (float) – y-coordinate of the point to draw to, relative to the pen’s current point
rellineto(x, y)

Draw a line from the pen’s current point; coordinates are relative to the pen’s current location.

Parameters:
  • x (float) – x-coordinate of the point to draw to, relative to the pen’s current point
  • y (float) – y-coordinate of the point to draw to, relative to the pen’s current point
curveto(x1, y1, x2, y2, x3, y3)
arc(x, y, radius, angle1, angle2)
closepath()

Close the path; in case the current point is not the path’s starting point, a line will be drawn between them.

endpath(draw=True)
drawpath(path)
autoclosepath(close=True)
findpath(points, curvature=1.0)

Images

image(path, x=0, y=0, width=None, height=None, alpha=1.0, data=None, draw=True)

Place a bitmap image on the canvas.

Parameters:
  • path (str) – location of the image on disk
  • x (float) – x-coordinate of the top left corner
  • y (float) – y-coordinate of the top left corner
  • width (float or None) – image width (leave blank to use its original width)
  • height (float or None) – image height (leave blank to use its original height)
  • alpha (float) – opacity
  • data (binary data) – image data to load. Use this instead of path if you want to load an image from memory or have another source (e.g. using the web library)
  • draw (bool) – whether to place the image immediately on the canvas or not

Clipping paths

beginclip(path)
endclip()

Transforms

transform(mode=None)
Parameters:mode (CORNER or CENTER) – the mode to base new transformations on
translate(xt, yt, mode=None)
rotate(degrees=0, radians=0)
scale(x=1, y=None)
skew(x=1, y=0)
push()
pop()
reset()

Colors

Colors can be specified in a few ways:
  • grayscale: (value)
  • grayscale with alpha: (value, alpha)
  • RGB: (red, green, blue)
  • RGBA: (red, green, blue, alpha)
  • hex: ('#FFFFFF')
  • hex with alpha: ('#FFFFFFFF')

You can use any of these formats to specify a colour; for example, fill(1,0,0) and fill(‘#FF0000’) yield the same result.

background(*args)

Set background to any valid color

outputmode()

Not implemented yet (Nodebox API)

colormode(mode=None, crange=None)

Set the current colormode (can be RGB or HSB) and eventually the color range.

Parameters:
  • mode (RGB or HSB) – Color mode to use
  • crange – Maximum value for the new color range to use. See colorrange.
Return type:

Current color mode (if called without arguments)

colorrange(crange=1.0)

Set the numeric range for color values. By default colors range from 0.0 - 1.0; use this to set a different range, e.g. with colorrange(255) values will range between 0 and 255.

Parameters:crange (float) – Maximum value for the new color range to use
fill(*args)

Sets a fill color, applying it to new paths.

Parameters:args – color in supported format
stroke(*args)

Set a stroke color, applying it to new paths.

Parameters:args – color in supported format
nofill()

Stop applying fills to new paths.

nostroke()

Stop applying strokes to new paths.

strokewidth(w=None)
Parameters:w – Stroke width
Return type:Current width (if no width was specified)
color(*args)
Parameters:args – color in a supported format
Return type:Color object

Text

text(txt, x, y, width=None, height=1000000, outline=False, draw=True)

Draws a string of text according to current font settings.

Parameters:
  • txt – Text to output
  • x – x-coordinate of the top left corner
  • y – y-coordinate of the top left corner
  • width – text box width. When set, text will wrap to the next line if it would exceed this width. If unset, there will be no line breaks.
  • height – text box height
  • outline (bool) – whether to draw as an outline.
  • draw (bool) – if False, the object won’t be immediately drawn to canvas.
Return type:

BezierPath object representing the text

font(fontpath=None, fontsize=None)

Set the font to be used with new text instances.

Accepts TrueType and OpenType files. Depends on FreeType being installed.

Parameters:
  • fontpath – path to TrueType or OpenType font
  • fontsize – font size in points
Return type:

current font path (if fontpath was not set)

fontsize(fontsize=None)

Set or return size of current font.

Parameters:fontsize – Font size in points (pt)
Return type:Font size in points (if fontsize was not specified)
textpath(txt, x, y, width=None, height=1000000, draw=False)

Generates an outlined path of the input text.

Parameters:
  • txt – Text to output
  • x – x-coordinate of the top left corner
  • y – y-coordinate of the top left corner
  • width – text width
  • height – text height
  • draw – Set to False to inhibit immediate drawing (defaults to False)
Return type:

Path object representing the text.

textmetrics(txt, width=None, height=None)
Return type:the width and height of a string of text as a tuple (according to current font settings)
textwidth(txt, width=None)
Parameters:text – the text to test for its dimensions
Return type:the width of a string of text according to the current font settings
textheight(txt, width=None)
Parameters:text – the text to test for its dimensions
Return type:the height of a string of text according to the current font settings
lineheight(height=None)

Set the space between lines of text.

Parameters:height – line height
align(align=LEFT)

Set the way lines of text align with each other.

Parameters:align (LEFT, CENTER or RIGHT) – Text alignment rule
fontoptions(hintstyle=None, hintmetrics=None, subpixelorder=None, antialias=None)

Not implemented.

Dynamic variables

var(name, type, default=None, min=0, max=255, value=None, step=None, steps=256.0)

Create a live variable.

Parameters:
  • name – Variable name
  • type (NUMBER, TEXT, BOOLEAN or BUTTON) – Variable type
  • default – Default value
  • min – Minimum value (NUMBER only)
  • max – Maximum value (NUMBER only)
  • value – Initial value (if not defined, use default)
  • step – Step length for the variables GUI (use this or steps, not both)
  • steps – Number of steps in the variables GUI (use this or step, not both)

Utility functions

random(v1=None, v2=None)
grid(cols, rows, colSize=1, rowSize=1, shuffled=False)
files(path="*")

You can use wildcards to specify which files to pick, e.g. f = files('*.gif')

Parameters:path – wildcard to use in file list
autotext(sourceFile)

Generates mock philosophy based on a context-free grammar.

Parameters:sourcefile – file path to use as source
Return type:the generated text
snapshot(filename=None, surface=None, defer=None, autonumber=False)

Save the contents of current surface into a file or cairo surface/context.

Parameters:
  • filename – File name to output to. The file type will be deduced from the extension.
  • surface – If specified will output snapshot to the supplied cairo surface.
  • defer (boolean) – Decides whether the action needs to happen now or can happen later. When set to False, it ensures that a file is written before returning, but can hamper performance. Usually you won’t want to do this. For files defer defaults to True, and for Surfaces to False, this means writing files won’t stop execution, while the surface will be ready when snapshot returns. The drawqueue will have to stop and render everything up until this point.
  • autonumber (boolean) – If true then a number will be appended to the filename.

Core

ximport(libName)

Import nodebox libraries.

The libraries get _ctx, which provides them with the nodebox API.

Parameters:libName – Library name to import
size(w=None, h=None)

Sets the size of the canvas, and creates a Cairo surface and context. Only the first call will actually be effective.

speed(framerate)

Set the framerate on windowed mode.

Parameters:framerate – Frames per second
Return type:Current framerate
run(inputcode, iterations=None, run_forever=False, frame_limiter=False)

Executes the contents of a Nodebox or Shoebot script in the current surface’s context.