Program Mode

Program Mode Reference

The Vexlio program mode API allows you to create diagrams using scripts written in Lua, a popular open-source language commonly used in applications supporting scripting or plugin systems.

This page contains the documentation for the API to interact with Vexlio drawings from Lua code in program mode. For an introduction to Lua itself (independent of Vexlio), you can find many tutorials online such as the Programming in Lua e-book or the tutorial on lua-users.org. The specific version that Vexlio uses is Lua 5.2.

If instead of an API reference you’re looking for an introduction on how to use program mode, please see that section of the Vexlio User Guide.

For clarity, this document presents properties and methods with full type signatures in a C or Java-like syntax.

Future updates of Vexlio will contain fixes and enhancements of this API. Notably, there is some Vexlio functionality that is not yet exposed with this API, including some object properties and methods. When we release updates that include changed or new API definitions, this page will be updated accordingly.


Drawing

A Vexlio drawing.

Typically you will use this type to interact with the drawing that the script is executing in. For example,

local d = Vexlio.drawing
local layer = d.currentLayer

Instance properties:

int numLayers

Total number of layers in this Drawing.

Layer currentLayer

Currently active layer in this Drawing.

Instance methods:

Layer getLayer(int index)

Return the layer in this Drawing at the given index.


Layer

A layer in Vexlio drawing.

This is the main interface through which you can create new objects.

Instance properties:

int numObjects

Total number of direct children in this layer (groups count as 1 direct child).

Instance methods:

DrawingObject getObject(int index)

Return a new reference to the child at the given index in this layer. Objects with lower index are rendered earlier.

Path path(float x, float y)

Create and return a path with a single point.

Path path(Point point)

Create and return a path with a single point.

Path path(float[] coords)

Create and return a new path with the given list (length >= 2) of points.

Path path(Point[] points)

Create and return a new path with the given list (length >= 2) of points.

Rect rect(float x, float y, float width, float height)

Create and return a new rectangle from top-left (x,y) with given width and height.

Rect rect(Point topLeft, Point lowerRight)

Create and return a new rectangle from the given top-left and lower-right points.

Ellipse ellipse(float cx, float cy, float rx, float ry)

Create and return a new ellipse at center point (cx,cy) with x radius rx and y radius ry.

Ellipse ellipse(Point center, float rx, float ry)

Create and return a new ellipse at given center point with x radius rx and y radius ry.

Arc arc(float startX, float startY, float xRadius, float yRadius, float sweepDegrees)

Create and return a new arc with the given starting point, x radius, y radius, and sweep angle.

Arc arc(Point start, float xRadius, float yRadius, float sweepDegrees)

Create and return a new arc with the given starting point, x radius, y radius, and sweep angle.

Equation equation(string latex)

Create and return a new equation with the given LaTeX. Leading and trailing '$' are added automatically.

Text text(string value)

Create and return a new text object with the given string value.

Polygon polygon(float cx, float cy, float rx, float ry, int numberOfPoints)

Create and return a new polygon object with the given parameters.

Polygon polygon(Point center, float rx, float ry, int numberOfPoints)

Create and return a new polygon object with the given parameters.


DrawingObject

Base type for drawing elements contained in a Layer.

All of the properties and methods defined here can be used on all objects that inherit from this base type, e.g.Arc,Ellipse, etc.

Instance properties:

Type type

The type of this object. Compare against constant 'Type' values e.g.if obj.type == Type.Ellipse then ....

Color fill

Fill color of this object.

Color stroke

Stroke color of this object.

float strokeWidth

Stroke width of this object.

Instance methods:

void delete()

Remove this object from its drawing.

void translate(float dx, float dy)

Translate this object by the given amount.

void moveTo(float x, float y)

Move this object's center point to the given coordinates.

void moveTo(Point point)

Move this object's center point to the given point.

void rotate(float degrees)

Rotate this object around its center point by the given degree amount. Positive degree amounts are clockwise rotations.

void rotate(Point point, float degrees)

Rotate this object around the given point by the given degree amount. Positive degree amounts are clockwise rotations.

void rotate(float x, float y, float degrees)

Rotate this object around the given point by the given degree amount. Positive degree amounts are clockwise rotations.

void scale(float sx, float sy)

Scale this object by the given x and y scale factors.

void dash()

Make this object's stroke a dashed line.

Path union(DrawingObject other)

Union the given object with this object, returning the resulting Path. Neither this object nor the given object is modified.

Path subtract(DrawingObject other)

Subtract the given object from this object, returning the resulting Path. Neither this object nor the given object is modified.

Path intersect(DrawingObject other)

Intersect the given object with this object, returning the resulting Path. Neither this object nor the given object is modified.


Arc

An arc object (inherits from DrawingObject).

Instance properties:

float cx

X coordinate of center point.

float cy

Y coordinate of center point.

float rx

X radius of the arc.

float ry

Y radius of the arc.

float sweepDegrees

Sweep angle (in degrees) of the arc.


Color

Scriptable wrapper for a color.

Instance properties:

int red

Red component in [0,255].

int r

Red component in [0,255].

int green

Green component in [0,255].

int g

Green component in [0,255].

int blue

Blue component in [0,255].

int b

Blue component in [0,255].

int alpha

Alpha component in [0,255].

int a

Alpha component in [0,255].

int argb

Integer representation 0xaarrggbb.


Ellipse

An ellipse object (inherits from DrawingObject).

Instance properties:

float cx

X coordinate of center point.

float cy

Y coordinate of center point.

float rx

X radius of the ellipse.

float ry

Y radius of the ellipse.


Equation

An equation object (inherits from DrawingObject).

Instance properties:

string latex

The LaTeX code for this equation.


Path

A path object (inherits from DrawingObject).

Instance properties:

int size

Number of points in this path (not including control points).

bool closed

True if this path is "closed".

Instance methods:

void lineTo(float x, float y)

Connect the last point on the path to the given coordinates with a straight segment.

void bezTo(float controlX, float controlY, float x, float y)

Connect the last point on the path to the given coordinates with a quadratic Bezier segment.

void bezTo(Point control, Point point)

Connect the last point on the path to the given point with a quadratic Bezier segment.

void bezTo(float controlAX, float controlAY, float controlBX, float controlBY, float x, float y)

Connect the last point on the path to the given coordinates with a cubic Bezier segment.

void bezTo(Point controlA, Point controlB, Point point)

Connect the last point on the path to the given coordinates with a cubic Bezier segment.

void arrow(bool start)

Give this path an arrowhead on its endpoint. If the 'start' parameter is given and true, make the start point an arrowhead instead.

void deleteNode(int index)

Delete the node at the given index from this path.

void insertPoint(int index, float x, float y)

Insert a point before the given node index.

void insertPoint(int index, Point point)

Insert a point before the given node index.

void setPoint(int index, float x, float y)

Move the point at the given index to the given coordinates.

void setPoint(int index, Point point)

Move the point at the given index to the given coordinates.

(Point, int, int) projectPointOnPath(float x, float y)

Calculate the point lying on the path that is closest to the given coordinates. The return value is a 3-tuple (p, i, j) of the result point p, and the node indices i, j of the path segment containing the result point.


Point

A point in space in a Vexlio drawing.

Instance properties:

float x

X coordinate of point.

float y

Y coordinate of point.


Polygon

A polygon object (inherits from DrawingObject).

Instance properties:

int points

Number of points/sides in the polygon.

float cx

X coordinate of center point.

float cy

Y coordinate of center point.

float rx

X radius of the polygon.

float ry

Y radius of the polygon.


Rect

A rectangle object (inherits from DrawingObject).

Instance properties:

float x

X coordinate of top left.

float y

Y coordinate of top left.

float width

Width of the rectangle.

float height

Height of the rectangle.


Text

A text object (inherits from DrawingObject).

Instance properties:

string text

The string value of this text object.

float size

The font size of this text object. If the text contains multiple font sizes, the value of this field is -1.

Instance methods:

void bold()

Toggle bold/unbold of the entire text.