Lua API Reference
The Vexlio Lua API allows you to create diagrams and plugins 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 which can be used to interact with Vexlio drawings from Lua code in program mode, or to create Vexlio plugins. 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. The user guide also contains an introduction on how to create plugins.
Future updates of Vexlio will contain changes enhancements of this API. When we release updates that include changed or new API definitions, this page will be updated accordingly.
Note on type signatures: Though the Lua language does not have explicit type annotations, this document presents properties and methods with full type signatures in a Java-like syntax for clarity.
Core API
This section describes the tables, types, methods and properties used to interact with Vexlio drawings.
Vexlio
The global Vexlio table containing utility properties and methods.
Instance properties:
Drawing drawing
The current drawing.
Instance methods:
float angleBetween(Point p1, Point p2, Point p3, Point p4)
Returns the angle in degrees between line segments (p1,p2) and (p3,p4).
(bool, Point, Point) circleCircleIntersect(Point c1, float r1, Point c2, float r2)
Given two circles, centered at point c1 with radius r1, and centered at point c2 with radius r2, compute the two points where they intersect and return the tuple (true, first intersection point, second intersection point). If the circles intersect at only one point, the two intersection points will be the same values. If the circles do not intersect, return (false, nil, nil).
(bool, Point, Point) circleLineIntersect(Point center, float radius, Point p1, Point p2)
Given a line passing through p1 and p2, and a circle with given center and radius, return the tuple (true, first intersection point, second intersection point). If the line only intersects the circle once (i.e. is a tangent line), the second intersection point will be the same as the first. If there is no intersection, return the tuple (false, nil, nil).
(bool, Point, Point) circleLineSegmentIntersect(Point center, float radius, Point p1, Point p2)
Given a line segment (p1, p2) and a circle with given center and radius, return the tuple (true, first intersection point, second intersection point). If the segment only intersects the circle once, the second intersection point will be nil. If there is no intersection, return the tuple (false, nil, nil).
(float, float) derivative(PathNode n1, PathNode n2, float t)
Compute and return the tuple (dx, dy) of the x and y derivative values at t in [0,1] between the two given nodes of a path. The nodes are assumed to be adjacent and belonging to the same path.
float dist(Point p1, Point p2)
Return the distance between the two given points.
float dot(Point p1, Point p2)
Returns the dot product of the two given vectors.
(bool, Point) lineIntersect(Point p1, Point p2, Point p3, Point p4)
Given a line passing through p1 and p2, and a second line passing through p3 and p4, return the tuple (true, intersection point). Else, if the lines do not intersect, return the tuple (false, undefined point).
Point midpoint(Point p1, Point p2)
Return the midpoint of the line segment (p1,p2).
Point normalize(Point p)
Return a normalized (length 1) copy of the given point.
Point point(float x, float y)
Create a point.
Point pointOnPath(PathNode n1, PathNode n2, float t)
Return the point lying on the path at t in [0,1] between the two given nodes of a path. The nodes are assumed to be adjacent and belonging to the same path.
void print(object[] args)
Print a message to the output window.
(bool, Point) rayIntersect(Point p1, Point p2, Point p3, Point p4)
Given a ray starting at p1 and extending through p2, and a ray starting at p3 and extending through p4, compute their intersection. If the intersection exists, return the tuple (true, intersection point). Else, if the rays do not intersect, return the tuple (false, undefined point).
Point rotatePoint(float x, float y, float aroundX, float aroundY, float degrees)
Rotate the point (x,y) around the point (aroundX,aroundY) by the given degree amount. Return the rotated point. Positive degree amounts are clockwise.
Point rotatePoint(Point p, Point around, float degrees)
Rotate the point (x,y) around the point (aroundX,aroundY) by the given degree amount. Return the rotated point. Positive degree amounts are clockwise.
Window window()
Get a reference to this plugin's window that can be populated with UI elements.
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.
int numSelected
Number of currently selected objects in this Drawing.
Instance methods:
List<DrawingObject> allObjects()
Return a list of all objects in the drawing. Iterate using each().
void centerViewOnObject(DrawingObject obj)
Center the drawing's camera on the given object (without changing zoom).
void deselectAll()
Deselect all objects.
DrawingObject firstObject()
Return the first object in this drawing (the first object in the first layer, i.e. the object that is rendered below all others). Iterate using DrawingObject:successor() and DrawingObject:predecessor().
Layer getLayer(int index)
Return the layer in this Drawing at the given index.
DrawingObject getSelectedObject(int index)
Return the object with the given index in the current selection
DrawingObject lastObject()
Return the last object in this drawing (the last object in the last layer, i.e. the object that is rendered above all others). Iterate using DrawingObject:successor() and DrawingObject:predecessor().
void selectAll()
Select all objects.
List<DrawingObject> allObjectsAtPoint(float x, float y)
Return a list of all objects in the drawing whose bounding boxes contain the given point. The resulting list is in render order, with objects appearing "on top" occurring later in the list.
List<DrawingObject> allObjectsAtPoint(Point point)
Return a list of all objects in the drawing whose bounding boxes contain the given point. The resulting list is in render order, with objects appearing "on top" occurring later in the list.
List<DrawingObject> allObjectsInRegion(float xMin, float xMax, float yMin, float yMax, bool entireObjectsOnly)
Return a list of all objects in the drawing lying entirely in the given rectangular query region.
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:
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.
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.
Equation equation(string latex)
Create and return a new equation with the given LaTeX. Leading and trailing '$' are added automatically.
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.
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.
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.
Text text(string value)
Create and return a new text object with the given string value.
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.
bool interactive
True if an object is "interactive" (true by default). If an object is not interactive, the user can't interact with it in the drawing with normal tools, and the object's bounding box is not kept up-to-date as it changes. A non-interactive object can see higher performance when making many changes to it in short amounts of time.
Instance methods:
void dash()
Make this object's stroke a dashed line.
void delete()
Remove this object from its drawing.
void deselect()
Deselect this object.
Path intersect(DrawingObject other)
Intersect the given object with this object, returning the resulting Path. Neither this object nor the given object is modified.
bool isOnTopOf(DrawingObject other)
Return true if this object is on top of the given object.
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.
DrawingObject predecessor()
Return the object that is just before this one in the drawing (i.e. the object rendered just below this one), or nil if none come before.
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.
bool sameAs(DrawingObject other)
Return true if this object refers to the same object as the given one.
void scale(float sx, float sy)
Scale this object by the given x and y scale factors.
void select(bool append)
Select this object.
Path subtract(DrawingObject other)
Subtract the given object from this object, returning the resulting Path. Neither this object nor the given object is modified.
DrawingObject successor()
Return the object that is just after this one in the drawing (i.e. the object rendered just above this one), or nil if none come after.
void translate(float dx, float dy)
Translate this object by the given amount.
Path union(DrawingObject other)
Union 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 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 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 deleteNode(int index)
Delete the node at the given index from this path.
(float, float) derivative(int i, int j, float t)
Compute and return the tuple (dx, dy) of the x and y derivative values at t in [0,1] between adjacent nodes at indices i and j.
PathNode getNode(int index)
Return a reference to the Bezier node in the path at the given index.
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.
List<Point> intersectionPoints(Path other)
Return a list of points where this path and the given path intersect. The list is empty if they do not intersect.
void lineTo(float x, float y)
Connect the last point on the path to the given coordinates with a straight segment.
Point pointAt(int i, int j, float t)
Return the point lying on the path at t in [0,1] between adjacent nodes at indices i and j.
(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.
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.
void splitPathAtPoint(Point point)
Insert a new node on this path at the given point. If the given point does not lie on the path, the new node is inserted at the point projected onto this path.
PathNode
A Bezier node in a Path. A Bezier node has a location (point) and optionally a "left" and "right" control point.
Example: A path created with an initial starting point, followed by two 'quadTo()' operations to create two quadratic Bezier segments. The path is then a total of three PathNodes. The first PathNode would be the starting point with no control points. The second PathNode would be the middle point with the "left" control point set to the control point of the first quadratic segment and no "right" control point. And the final PathNode would be the last point with the "left" control point set to the control point of the second quadratic segment.
Example: A path created with an initial starting point followed by a 'bezTo()' operation to create a single cubic Bezier segment. The path is then two PathNodes, the first of which has the initial point and the "right" control point set to the first control point of the cubic section. The second PathNode has the final point and the "left" control point set to the second control point of the cubic section.
Example: A path consisting of only straight line segments. In this case, all PathNodes would only have points, and no control points, as they are linear segments.
Instance properties:
Point point
The location of this node.
Point controlLeft
The left control point of this node (may be nil).
Point controlRight
The right control point of this node (may be nil).
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.
[Plugins Only] Window
A window object used by a plugin to display UI elements, for example:
local w = Vexlio:window()
win:label("This is a label.", win:row(), 0, 12)
Instance properties:
string title
The title of the window.
Instance methods:
Button button(string label, function onClickCallback, int row, int col, int colSpan)
Add a new push button with the given label to the window in the given row and column.
Checkbox checkbox(string label, function onClickCallback, int row, int col, int colSpan)
Add a new checkbox with the given label to the window in the given row and column.
Label label(string text, int row, int col, int colSpan)
Add a new static label with the given text to the window in the given row and column.
RadioGroup radioGroup(bool vertical, function onSelectionChangedCallback, int row, int col, int colSpan)
Add a new radio button group with the given text to the window in the given row and column.
int row()
Append a new row to the window and return its ID, which can be used to add elements within the row.
int row(int height)
Append a new row with the specified height to the window and return its ID, which can be used to add elements within the row.
Slider slider(float min, float max, float step, function onValueChangedCallback, int row, int col, int colSpan)
Add a new slider with the given min, max, and step values to the window in the given row and column.
Swatch swatch(int row, int col, int colSpan)
Add a new color swatch to the window in the given row and column. When the user clicks the color swatch, the color picker dialog appears.
Textbox textbox(int row, int col, int colSpan)
Add a new editable text field to the window in the given row and column.
[Plugins Only] UIElement
Base type for all UI elements.
All of the properties and methods defined here can be used on all objects that inherit
from this base type, e.g.TextBox,Label, etc.
Instance properties:
bool enabled
True if the UI element is enabled (user can interact with it).
string tooltip
The tooltip text for the UI element.
[Plugins Only] Button
A push button with a callback function.
Instance properties:
string label
The label text.
function callback
The Lua function that is called when the button is clicked. Signature:void function()
[Plugins Only] Checkbox
A checkbox that has a label and can be checked or unchecked.
Instance properties:
string label
The label text.
bool checked
True if the checkbox is checked.
function callback
The Lua function that is called when the checkbox is clicked. Signature:void function()
[Plugins Only] Label
A static text label.
Instance properties:
string label
The contents of the label.
[Plugins Only] RadioGroup
A group of mutually exclusive choices (a group of radio buttons).
Instance properties:
int numOptions
Total number of options in this group.
int selectedOption
Integer ID of the currently selected option, or -1 if no selection.
function selectionChangedCallback
The Lua function that is called when a radio button in this group is selected. Signature:void function(int newSelectionId)
Instance methods:
int option(string label)
Add a new radio button to the group with the given label. Returns an integer ID of the new option.
[Plugins Only] Swatch
A color swatch button that displays a selected color and displays a color picker window on click.
Instance properties:
int argb
Integer representation 0xaarrggbb of current color.
byte alpha
Alpha component of current color.
byte a
Alpha component of current color.
byte red
Red component of current color.
byte r
Red component of current color.
byte green
Green component of current color.
byte g
Green component of current color.
byte blue
Blue component of current color.
byte b
Blue component of current color.
[Plugins Only] Textbox
A generic text box that the user can edit.
Instance properties:
string text
The value of the text box as a string.
int intValue
The value of the text box as an integer.
float floatValue
The value of the text box as a float.
Extra functions
These helper functions are in the global namespace of every plugin (they don't belong to any table).
void each(List<T> list)
Used to iterate over generic List objects returned through the Vexlio API. For example,
local objects = Vexlio.drawing:allObjects()
for obj in each(objects) do
...
end
int count(List<T> list)
Returns the length of generic List objects returned through the Vexlio API.
string strjoin(char[] chars, string sep)
Returns the given Lua array (a table) of characters joined by the given string separator. Examples:
strjoin({"a", "b"}, ",") -- Returns "a,b"
strjoin({"a", "b"}, "!!") -- Returns "a!!b"
string[] strsplit(string str, string sep)
Returns the given string split on the given string separator. Examples:
strsplit("a,b,c", ",") -- Returns {"a", "b", "c"}
strsplit("a,b,,c", ",") -- Returns {"a", "b", "", "c"}
string readFile(string relativePath)
Read and return the contents of the file at the given path (relative to the plugin input directory configured in Vexlio settings). Reading files outside of the plugin input directory is not allowed.
table readCSVFile(string relativePath)
Parse the contents of the given file as CSV data and return a Lua table. The table will be a list of lists, one per row.