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
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
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
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
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
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 userectmode()
to change the function’s behaviour according to what might suit your script’s needs.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.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
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')
- grayscale:
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.