# 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.

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

 4.   newLatex = [[ x = \frac{y}{z} ]]


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

 4.   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:

p = Vexlio.point(10, 20)


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

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:

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.

### 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.