Vexlio User Guide

Welcome!

Vexlio aims to be simple, easy to use, and powerful. This user guide will provide you with an introduction to the user interface, highlight important elements, and an introduction to creating diagrams with program mode.

Table of Contents


User Interface

When you first open Vexlio, the main drawing window will appear. The following image is a screenshot of Vexlio’s main window. Several areas have been highlighted and numbered, and we’ll discuss each of those in turn.

1. Drawing area

This is the drawing area, sometimes referred to as the canvas.

In Vexlio, each object has its own specific position in “drawing space,” meaning each object is positioned by x and y coordinates. Moving an object modifies its coordinates, and you can also set the coordinates for objects manually by using the text boxes in the lower-right corner of the screen.

Vexlio also uses the concept of a “drawing camera,” which allows you to zoom in and out and pan around the drawing without having to move any objects. Zooming and panning lets you move your view to fit whatever you’d like to focus on, without having to move the objects in the drawing themselves.

To zoom in and out, simply hold Ctrl while scrolling the mouse wheel, or use the “Zoom” box in the lower-right corner of the screen. The “View” menu also has the “Zoom to all” item to zoom to fit all objects on the screen, and the “Zoom to selection” item to fit all selected objects on the screen.

To pan around, press down the middle mouse button (typically, just press your scroll wheel down) in the drawing area and move the mouse. You can also hold Space Bar and click and drag the drawing if your mouse does not have a middle button.

Vexlio’s canvas is infinite, meaning there is no limit on how far you can zoom or pan.

2. Tool palette

In Vexlio, a single tool is active at all times, and only one tool can be active at a time. To activate a tool, click on its button in this region, called the “tool palette.” When you open Vexlio, the select and move tool (the topmost button, shaped like a mouse cursor) is initially activated.

Hovering over the tool buttons (in fact, most buttons in Vexlio) will display a small tooltip explaining what that button does. The tooltip will also display a keyboard shortcut for that button, if one exists. For example, hovering over the first tool button will display the tooltip “Select and move (M)“, indicating that pressing M will activate that tool.

We’ll look at each tool in more detail now.

Tool Description
Select and transform. Use this tool to select objects in the drawing. This tool is also used to move, rotate, and scale objects. Holding Shift while dragging objects will move them only horizontally or vertically, and while scaling objects will scale them uniformly. Holding Ctrl and dragging objects will create a duplicate that can be placed with the mouse. Arrow keys will move selected objects a small fixed amount. To select more than one object, click and drag to perform an area selection; holding Shift/Ctrl will add objects to the selection.
Edit path. Use this tool to edit paths (lines and curves) that you have created. After clicking on a path to start editing it, small square "handle" buttons are displayed at each point (or "node") in the path. These handles can be dragged with the mouse to move the corresponding path nodes. You can select more than one node at a time by performing an area selection with this tool. Holding Shift while dragging selected nodes will move them only horizontally or vertically. Delete will delete the selected nodes, and double-clicking on a path will insert a new node at the clicked point. Arrow keys will move selected nodes a small fixed amount.
Duplicate in grid. Use this tool to quickly duplicate the selected objects in a line or grid. When activating this tool, the handles will change around the selected objects to appear as double-squares, which can be dragged in any direction to create duplicates. For example, dragging down and to the right will create a grid of object duplicates. Arrow keys will increase or decrease the spacing between rows and columns of the grid.
Duplicate in circle. Use this tool to quickly duplicate the selected objects in a circular pattern. When activating this tool, the handles will change around the selected objects to appear as double-circles, which can be dragged left and right or up and down to change the radius of the circle around which the duplicates are arranged. Arrow keys will increase or decrease the number of duplicated objects, and will increase or decrease the radius of the circle.
Auto-line. Use this tool to connect objects with straight lines or arrows. The objects must already be perfectly aligned, for example by using the snap-align guides, the alignment buttons or the Duplicate In Grid tool. Simply activate this tool, and move the mouse between the objects you wish to connect. A grey preview line will appear connecting the object, and clicking the mouse will create the line. Use the mouse wheel while the preview line is visible to cycle between arrowhead styles.
Line. Use this tool to create straight lines. Clicking the mouse will start a new line, and each click will then add another node onto the path. Right-clicking the mouse will finish the line, meaning the next click will begin a new one. Holding Shift will constrain you to creating horizontal or vertical lines only. Pressing Enter will "close" the path, automatically connecting the last node to the first node.
Curved line. Use this tool to create smooth curved lines (Bezier curves). Similar to the Line tool, clicking the mouse will start a new curve, and each click will then add another node onto the path. The curve will auto-smooth itself as you create it. Right-clicking the mouse will finish the path, meaning the next click will begin a new one. The curvature can be edited with the Edit Paths tool; extra circular handles will display for Bezier curves when editing them.
Arc. Click and drag with this tool to create circular or elliptical arcs. Arcs created will default to 90°, but can be modified to other degree amounts in the Object Properties region. Holding Shift while dragging will constrain you to creating circular arcs only. Pressing F while dragging will flip the orientation of the arc.
Rectangle. Click and drag to create a rectangle. Holding Shift will constrain you to creating squares only. Clicking the mouse once on an empty area will create a duplicate of the last rectangle you created, placed at the mouse position.
Ellipse. Click and drag to create an ellipse. Holding Shift will constrain you to creating circles only. Clicking the mouse once on an empty area will create a duplicate of the last ellipse you created, placed at the mouse position.
Polygon. Click and drag to create a polygon. Holding Shift will constrain you to creating circular polygons (i.e. symmetric) only. Clicking the mouse once on an empty area will create a duplicate of the last polygon you created, placed at the mouse position. Arrow keys while dragging will increase or decrease the number of points on the polygon.
Text. Click on an empty area to create a new text object. The text can be edited as usual, and styling properties (bold, font choice, font size, etc.) can be changed in the Object Properties region. The square handles that appear will resize the text box, wrapping long lines to fit inside the box if necessary.
Equation. Click on an empty area to create a new LaTeX equation object. A small editor window will appear, allowing you to edit the LaTeX for that equation object. Clicking on a previously created equation object will allow you to edit its LaTeX.

3. Style properties

The Style region allows you to change the inside (“fill”) and line color as well as line width and the dashed line style. Clicking on a color swatch will cause a color picker window to appear, from which you can fine-tune your color selection, or paste in a specific RGB value. Transparency or opacity can also be chosen from the color picker window. A red “x” through a color swatch indicates that the color is fully transparent. You can also use the Quick Colors region to easily apply a fill and line color.

The two small buttons by the “Style” header are the style copy and paste buttons. To apply a style from one object to another object, first select the object from which you want to copy the style, and click the Copy Style button. Then select one or more other objects and click the Paste Style button. This also works between objects of different types (for example, between rectangles and ellipses).

4. Object properties

The content of the Object Properties region changes depending on what object or objects are currently selected. With a single object selected, this region will have controls to manually edit specific properties of that object. For example, if you select a rectangle object, the properties region will contain several editable text boxes with the width, height, and rounded corner radius values of the selected rectangle, as in the following screenshot:

When multiple objects of the same type are selected, values you change in the Object Properties region apply to all selected objects. If multiple objects of different types are selected (for example, a rectangle and an ellipse), no properties are displayed to edit.

5. Align buttons

The Align region contains buttons for perfectly aligning multiple selected objects. Each button aligns a different side or center of the objects. Alignment is relative to the object that was selected first.

To align objects, first select the object to which you want the others to be aligned. Then, holding Shift, use the Select tool to select the other objects. Click the button corresponding to the alignment that you want. The first-selected object will not move, and the other objects will move to be aligned with it. If you had the following selected objects:

Clicking the “horizontal align centers” button would align the objects along their centerlines:

The small button next to the “Align” header is the “re-center previous” button, which is a shortcut for the common operation of re-centering objects. For example, suppose you have two circles which you center-align (i.e. two concentric circles) using the alignment buttons. If you were to resize one of the circles, they would no longer be center-aligned. Pressing the “re-center previous” button would perform a vertical and horizontal center alignment operation on the two circles, without having to reselect them. Remember that this operation is applied to whatever objects were last aligned with any alignment operation.

6. Spacing buttons

The buttons in the Spacing region allow you to evenly distribute selected objects either horizontally or vertically. These operations move the selected objects so that they are all separated by an even amount of horizontal or vertical space, even if the objects are different sizes.

One nice feature of the spacing buttons is the leftmost and rightmost objects when spacing horizontally (or topmost and bottommost when spacing vertically) do not move. Looking at an example, suppose you had the following selected objects:

Clicking the horizontal spacing button with these objects selected, we can easily make the squares between the two circles evenly spaced:

The leftmost and rightmost objects (here, the two larger circles) did not move, which is by design.

7. Arrange buttons

In Vexlio, each object has its own “depth” in the drawing. You can think of the drawing as a stack of objects, where the lowest ones can be overlaid by objects on top of them. The Arrange buttons simply move selected objects higher or lower in the stack.

Each Layer has its own stack of objects, meaning the Arrange buttons only affect objects within a single layer.

8. Rotate buttons

The buttons in the Rotate region are used to quickly rotate objects by increments of 90°, or to flip (mirror) them horizontally or vertically. You can fine-tune the rotation of objects by using the angle box (labeled “∠”) in the lower-right corner of the main window:

You can also modify the position of an object manually by editing the X and Y values shown here.

9. Layers

In this region, you can add, remove, reorder and rename layers in your drawing. Similar to the “stack of objects” visualization discussed in the Arrange section, you can visualize the layers in your drawing as a stack of transparent sheets laying atop one another. The content of each sheet is independent, and depending on the order of how you stack them, this changes which objects appear on top of others.

To add a layer, click the “+” button. To remove a layer, select it in the Layers list and click the “–” button. To move a layer up the stack, i.e. to make it display on top of other layers, click the up button. To rename a layer, double click on its name in the Layers list.

You can also move objects between layers. To do this, select the objects you wish to move, and use the “Object → Move selected objects to layer” menu.

10. Quick colors

The Quick Colors region contains a set of pre-defined colors to quickly style your drawing. You can click on a color swatch to change the fill of the selected objects to that color. To change the line color instead, Shift-click on the color swatch instead. As mentioned before, the red “x” swatch represents transparent.

11. Tip box

The Tip Box displays contextual tips or information, depending on what tool is active, the objects that are selected, and operations that can be performed. For example, when you activate a tool, the Tip Box will display a short description of the keyboard modifiers that can be used to control the behavior of the tool.

Working with Snapping

Snapping is one of the most useful and powerful features in Vexlio. Mastering the snapping system will allow you to rapidly create precise diagrams with little effort.

In Vexlio, there are two types of snapping: point snapping and align snapping.

Point snapping

Point snapping is when a point on an object, e.g. the center point of a circle, is snapped to another point on another object, e.g. the top left corner of a rectangle. Every object has at least four snap points (the corners of the object’s bounding box) but most objects have many more. For example, a rectangle object has 9 snap points: the four corners, the center point, and the four midpoints of each side. An ellipse also has 9: the center point, and at 45° increments. A path has a snap point for every node in the path.

Point snapping occurs when you are creating or moving objects, or editing paths. For example, the short animation below shows snapping the center point of the circle onto the center of the rectangle, just by dragging the circle to approximately the right position. A path is then created by snapping to the corner of the rectangle and the center of the circle.

When the circle is being dragged, you can see it make small jumps as it moves: this is point snapping in action, as the circle snaps its points to other objects’ points as it is being dragged. When creating the path, you can see the small white box that appears to indicate that the next point will be placed at a snap point.

You can disable point snapping at any time by using the “Edit → Snapping → Disable point snapping” menu.

Align snapping

Align snapping is when a snap point on an object is aligned to a snap point on another object, even if the two snap points do not touch. Align snapping is extremely useful in ensuring that the objects in your diagram are perfectly aligned, without having to continuously re-click the Align buttons.

Align snapping occurs when creating or moving objects, or creating paths. The short animation below shows align-snapping the smaller rectangle to the centerline of the larger rectangle by dragging it until the red dotted guide line appears.

The smaller rectangle is then duplicated (by Ctrl-dragging it) and moved to the right. The align snapping guide appears and indicates that as the duplicate is moving, it is staying align-snapped to the centerline of the first rectangle. Finally, a path is created between the two smaller rectangles, using a combination of point and align snapping to ensure it connects the rectangles perfectly.

You can disable align snapping at any time by using the “Edit → Snapping → Disable align snapping” menu.

Program Mode

In addition to the traditional tool palette approach for creating diagrams, Vexlio offers an alternative called “program mode.” In program mode, you create diagrams and drawings by writing Lua commands to create, transform, and style drawing elements. Lua is a popular open-source language commonly used in applications supporting scripting or plugin systems.

While you are working in program mode, your diagram live-updates as you type, making it fast and easy to refine your diagrams. Program-mode diagrams in Vexlio are “first class,” so you can even save and load your diagrams in program mode.

This section of the user guide will introduce you to program mode and get you started creating diagrams with it. If you’re just looking for the API reference to use in your diagrams, please see the program mode reference page.

We also assume brief familiarity with the Lua language. 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.

Switching modes

Switch from a normal mode drawing to program mode with the “File → Convert drawing to Program mode” menu item. The mode is independent for each drawing, so if you have multiple drawings open, converting one to program mode will not affect the others. If the drawing is already in program mode, the menu item will change to “File → Convert drawing to Normal mode”.

You can switch a drawing to program mode even if it already has content.

If you’ve finished using program mode to create or modify content in your drawing, you can switch the drawing back to normal mode. This will keep all of the changes made by your program, but will re-enable normal interacting using the tools and rest of the user interface.

Important: switching out of and then back to program mode will not preserve the commands you entered. Vexlio will treat it as a new program. This behavior may change in future versions.

Example walkthrough

For a drawing in program mode, creating content is as simple as using the Vexlio API in a normal Lua script.

Let’s look at the example from the Features page:

This Lua script has 6 lines by the time the animated image ends. We’ll look at them one by one.

  • Line 1: Create a point at x=50, y=90 and name it center.

  • Line 2: Start a loop at r=60, modifying r by -10 each iteration. This r variable stores the changing radius of the ellipses that are created.

  • Line 3: Create an ellipse named e with center point center and x and y radius r (an ellipse with the same x and y radii is a circle).

  • Line 4: Set the stroke (line) width of the newly created ellipse e to the given floating point value.

  • Line 5: Set the fill color of ellipse e to the given ARGB (alpha, red, green, blue) value.

  • Line 6: End the loop starting on Line 2.

As you type, your drawing live-updates with each keystroke, making it easy to refine your diagram interactively.

Modifying existing drawing elements

You can also access and modify drawing elements that already exist in the drawing, instead of creating new ones. This is particularly useful if you convert a drawing to program mode when it already has content.

Suppose your drawing has 2 objects in it: one rectangle and one LaTeX equation. To modify the equation in program mode, you might do this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
layer = Vexlio.drawing.currentLayer
obj0 = layer:getObject(0)
obj1 = layer:getObject(1)
newLatex = "x = y^2"
if obj0.type == Type.Equation then
    obj0.latex = newLatex
else
    -- obj1 must be the equation.
    obj1.latex = newLatex
end

Line 1 first gets the current drawing, use the field of the global Vexlio table called drawing. This is the Drawing object for the drawing in which your program is executing. To see a full list of the properties and methods available for objects of the Drawing type, see the API reference. It then gets the current layer of the drawing object, which is where we assume our two objects to be.

Lines 2 and 3 fetch the two objects from the current layer by invoking the getObject method on the layer object. The getObject method takes a 0-based index as its argument. (The total number of objects in the layer can be retrieved with the numObjects property on the Layer type.)

Line 4 defines new LaTeX code for the equation object. Especially for specifying LaTeX code with backslash (’\‘) characters, it’s helpful to use Lua’s literal string syntax [[...]]. So, if our newLatex string contained backslashes, such as for forming fractions, we can write it instead as:

1
newLatex = [[ x = \frac{y}{z} ]]

Without the [[...]] syntax, we’d have to double all backslashes like so:

1
newLatex = "x = \\frac{y}{z}"

Line 5 compares the type of obj0 to see if it is the equation object. Alternatively we could have tested to see if it was a rectangle by writing if obj0.type == Type.Rect.

Lines 6–10 change the LaTeX string value on the appropriate object.

Colons versus periods

If you are new to Lua, you may be wondering why the above example uses a colon character (’:‘) to invoke methods. The colon is used in Lua to make calls to instance methods, i.e. methods that are invoked on specific object instances. In the above example we called layer:getObject(0). The getObject method requires a Layer instance, otherwise you would have to specify which layer you are looking to fetch an object from.

In general, all methods in Vexlio’s Lua API will be instance methods and thus use the ‘:’ syntax, except those in the global Vexlio table. For example, to create a Point object, use the non-instance point() method in the global Vexlio table with the ‘.’ syntax:

1
p = Vexlio.point(10, 20)

But to create an ellipse on a particular layer, use the instance method ellipse() with the ‘:’ syntax:

1
e = Vexlio.drawing.currentLayer:ellipse(0, 0, 10, 20)

Method shortcuts

Typing out the full name of methods that create objects would be tedious. Vexlio offers several aliases for convenience, and you can easily create your own. For example, calling the global ellipse(...) function (as seen in the above animated example) is a synonym for calling Vexlio.drawing.currentLayer:ellipse(...). Here is a list of the aliases available by default:

Alias Equivalent to
pt(...) Vexlio:point(...)
arc(...) Vexlio.drawing.currentLayer:arc(...)
ellipse(...) Vexlio.drawing.currentLayer:ellipse(...)
eqn(...) Vexlio.drawing.currentLayer:equation(...)
line(...) Vexlio.drawing.currentLayer:path(...)
polygon(...) Vexlio.drawing.currentLayer:polygon(...)
rect(...) Vexlio.drawing.currentLayer:rect(...)
text(...) Vexlio.drawing.currentLayer:text(...)

You can easily create your own aliases for functions that you use frequently. Suppose the ellipse() function did not have an alias. At the top of your Lua script, you would simply add the following code:

1
2
3
4
function ellipse (...)
    local args = {...}
    return Vexlio.drawing.currentLayer:ellipse(table.unpack(args))
end

This is the same method that Vexlio uses internally to create the aliases available by default.

Plugins

Plugins offer a powerful way to extend and enhance Vexlio’s functionality and toolkit. Vexlio plugins use the same language and API as Program Mode, with additional hooks for intercepting drawing and mouse events, and creating simple GUIs. With plugins, Vexlio can be easily customized with new functionality to fit your specific workflow. You can also download and install plugins written by others.

We’ll look at plugins first as a user, and then as a plugin developer.

Using plugins

Vexlio comes with several preinstalled plugins that provide some useful extra functionality (and serve as examples to base your own plugins off of). Every plugin is given a separate menu item in the “Plugins” menu. To execute a plugin, simply click on the menu item with its name. Depending on the plugin, its GUI will appear in a new window (although not all plugins will have a GUI).

Installing and using new plugins is fast and easy. First, open the Plugin Manager with the “Plugins → Manage plugins…” menu item. You’ll see a window with a list of all of the plugins that you currently have installed. Click the “+” button at the bottom right of the window:

This will cause a dialog to appear allowing you to select the new plugin file on your computer. After selecting the plugin and pressing Open, a new entry will appear in the list of installed plugins in the Plugin Manager window, and a new menu item will appear in the Plugins menu with the name of the new plugin. That’s it — you don’t have to restart Vexlio to use your new plugin.

Note: some plugins may intercept mouse clicks in the drawing to perform their operations. Only plugins with an actively open window will be able to use mouse and other drawing events.

Creating plugins

The rest of this User Guide section is only relevant if you want to write your own plugins.

If you are familiar with the Vexlio Lua API from Program Mode, you will find it very easy to create plugins. In fact, a typical development process for a plugin will often begin as a Program Mode drawing, which is a great way to sketch out functionality.

The main differences between a plugin and a Program Mode drawing are the ability to create a graphical user interface (GUI) with buttons, text fields, and other elements, and the ability to intercept user events such as mouse clicks.

In addition, in every plugin there must be a description table named VexlioPlugin containing the name of the plugin (used for the menu item text), the author, and a unique identifier:

1
2
3
4
5
6
VexlioPlugin = {
    name = "Create spirals",
    author = "Vexlio",
    description = "Creates Archimedean spirals in the drawing.",
    id = "com.vexlio.create-spirals"
}

The identifier must adhere to the reverse domain name syntax, here com.vexlio.create-spirals. If your plugin does not have a VexlioPlugin table, or the identifier is empty or invalid, the plugin won’t be useable from Vexlio. The domain does not necessarily have to be a registered domain name, but you should be consistent in the plugins that you develop. These identifiers are used by Vexlio for cataloging and managing plugins. If you don’t have a .com domain that you use for identifiers of this sort, one option is to use a .name, e.g. name.firstlast.plugin-name.

Creating a GUI

Most likely, your plugin will be more useful if it has a user interface with descriptive labels, buttons, text fields, etc. A user can then customize the parameters of your plugin without having to edit the plugin code itself.

You create UI elements by implementing the pluginUI() function, which is called by Vexlio first when the plugin is executed. For example, the following snippet creates a window with a static label and a button.

1
2
3
4
5
6
7
-- Called by Vexlio: create UI elements here.
 function pluginUI()
    local win = Vexlio:window()
    win:label("This is a label", win:row(), 0, 12)
    win:row(10) -- Small empty vertical space for padding
    win:button("Click me", function() print("Clicked") end, win:row(), 4, 4)
end

The first thing to understand about this code is how the UI elements are positioned. Instead of positioning elements explicitly with X and Y coordinates, Vexlio plugins operate within a predefined grid system. This approach allows for rapid UI development with minimal effort spent on UI element alignment.

For grid placement, all UI element functions in the API follow this template: functionName(…, rowIndex, columnIndex, columnSpan).

The grid system for UI element positioning has 12 columns and an arbitrary number of rows. Initially, the grid has 0 rows. To append a new row, use the Window:row() function, which returns the index of the newly created row.

So, in the above code snippet, the label starts in the first row, in the leftmost column (column index 0) and spans 12 columns, i.e. the entire width of the grid. The button starts in a second row, column index 4 and spans 4 columns, which is the middle third of the grid.

The following illustration demonstrates the grid system visually, with three UI elements in three distinct rows with their column and span values:

If your plugin does not need a UI, implement the pluginShouldShowUI() function somewhere in your plugin and return false:

1
2
3
4
-- Called by Vexlio to determine if a UI should be shown.
function pluginShouldShowUI()
    return false
end

This function is called by Vexlio before pluginUI() is called: pluginUI() is only executed if pluginShouldShowUI() returns true (the default).

Callback functions

In the above snippet, we saw how to create a button UI element:

1
    win:button("Click me", function() print("Clicked") end, win:row(), 4, 4)

We already discussed the meaning of the win:row(), 4, 4 parameters when covering UI element positioning. The first parameter, “Click me” specifies the label of the button.

The middle parameter function() print(“Clicked”) end is the callback function. This is the Lua function, defined in your plugin, that is called when the user clicks the button. In this example we are taking advantage of Lua anonymous functions to define a compact anonymous function that prints a message to the plugin output window.

If you don’t wish to use an anonymous function, simply pass in the function to use as the callback:

1
    win:button("Click me", functionName, win:row(), 4, 4)

You can also pass nil as the callback function, in which case no callback is made.

Many different types of UI elements have callback function parameters for various events, such as the Slider’s value changed callback, made every time the user drags the slider handle.

Intercepting events

An important component of many plugins, beyond responding to UI element interaction by the user, is responding to events like mouse clicks, selection changes, or object creation in the drawing itself. For these cases, the Vexlio plugin API provides event hooks that you can implement in your plugin.

For example, to receive a callback whenever the user clicks the mouse in the drawing, simply implement the onMouseUp(point) somewhere in your plugin:

1
2
3
4
-- Called by Vexlio on every mouse up event in the drawing.
function onMouseUp(p)
    ellipse(p.x, p.y, 10, 10)
end

This will create a small ellipse in the drawing every time the mouse is clicked, at the point where the mouse was clicked.

The other events you can intercept are:

Hook Function Description
onMouseDown(point) The left mouse button was depressed at the given Point in the drawing.
onMouseUp(point) The left mouse button was released at the given Point in the drawing.
onMouseMove(point) The mouse moved at the given Point in the drawing.
onSelectionChange() The selection in the drawing (the list of selected objects) changed.
onObjectCreation(objects) One or more objects were created in the drawing. Use the each() function to iterate through the given List of new objects.
onObjectDeletion(objects) One or more objects were deleted in the drawing. Use the each() function to iterate through the given List of objects.

Note: your plugin will only intercept events as long as its window is visible to the user. This is to prevent user confusion with invisible plugins responding to mouse or drawing events. A plugin without a UI cannot intercept events.

Plugin output

All print() statements in plugins are sent to a per-plugin output window. This is mainly useful for debugging your plugin. To display the output window for a plugin, click the “…” (ellipsis) button at the top right of its UI window, next to its Reload button.

Prefab Library

Vexlio offers a convenient method to create your own reusable objects, or “prefabs,” which are saved to your computer and can be dragged-and-dropped into your drawings. You may have used a similar feature such as a shape library in other programs. Using prefabs can greatly increase your productivity if you frequently make drawings that reuse common shapes or objects.

While Vexlio comes with a small (but expanding) set of prefabs ready for you to use, the real utility comes from creating your own prefabs. There are two main ways to create prefabs.

Create prefabs from objects

Creating a new prefab from objects in a drawing is very easy. First, open the prefab library window with the “Object → Show prefab library” menu item. Then, select the object or objects in your drawing that you wish to make into a prefab. Finally, click the “+” button at the bottom right of the prefab library window:

This will create the new prefab in the “My Prefabs” category. Now you can simply drag-and-drop the prefab into a drawing to use it. You can rename the prefab by editing the textbox that appears when a prefab is selected (you cannot rename the built-in prefabs that come with Vexlio).

Create prefabs from files

You may already have a set of Vexlio or SVG documents that you wish to use as prefabs. You can simply drag-and-drop any .vex or .svg file into the My Prefabs tab, and it will be imported to the Prefab Library. Because Vexlio does not yet support all SVG features, some SVG files may fail to import as prefabs.

You can also drag-and-drop entire folders of documents onto the window: importing prefabs this way will create a new category (tab) with the same name as the folder.

Editing prefabs

To edit a prefab that you created, simply right click on it and choose “Edit prefab”. This will open the prefab in a new Vexlio tab, which you can then edit as a normal drawing. To save the changes to the prefab, simply save the drawing. You may have to click the Refresh button in the prefab library to see your changes take effect.

Vexlio from the Command Line

It is also possible with Vexlio to create PDF, PNG or SVG output from the command line, which can be useful for automating your diagram creation. When invoking Vexlio from the command line, the specified output file(s) are created from the given input file without opening the main Vexlio application or GUI.

Command line flags

The following table lists all of the command line flags available.

Flag Description
-h, --help Print a summary of the command line interface and exit.
-i, --input=PATH Path to the input file (.vex or .svg) to read.
-x, --execute=PATH Path to a Lua file that will be executed as a program-mode script to generate the input drawing. This cannot be combined with --input.
-o, --output=PATH[,PATH...] Comma-delimited list of output file(s) to create. The type of the output file is chosen separately for each file based on its extension.
-s, --size=N Size in pixels of .png output width. The height is determined automatically to preserve the input's aspect ratio.
-w, --overwrite Overwrite any existing output file(s) without prompting.

Examples

1. Create a PNG file from an existing .vex drawing:

Vexlio -i drawing.vex -o drawing.png

2. Create a PNG, PDF, and SVG file from an existing .vex drawing:

Vexlio -i drawing.vex -o drawing.png,drawing.pdf,drawing.svg

3. Create a PNG file with a width of 1024 pixels from an existing .vex drawing (the actual size will be 1024 pixels wide, but the height will be automatically adjusted to preserve the aspect ratio of the drawing, i.e. the output .png will not appear squashed):

Vexlio -i drawing.vex -o drawing.png -s 1024

4. Create a PDF and VEX file from a Lua script written for Program Mode:

Vexlio -x script.lua -o drawing.pdf,drawing.vex

Windows and macOS differences

The only command-line difference in the Windows and macOS versions of Vexlio is how to open the application with arguments.

Windows: Open cmd.exe and navigate to the directory where Vexlio is installed (typically C:\Program Files\Vexlio). Then simply call Vexlio.exe --arg1 --arg2 ….

macOS: Open Terminal and at the prompt, type /Applications/Vexlio.app/Contents/MacOS/Vexlio --arg1 --arg2 ….