Masking Subsystems

Masking a subsystem allows you to create a custom user interface for a Subsystem block that hides the underlying schematic, making it appear as an atomic component with its own icon and dialog box. Many of the components in the PLECS component library are in fact masked subsystems.

To mask a subsystem, select the Subsystem block, then choose Create mask… from the Edit > Subsystem menu or the block’s context menu. The mask editor appears. The mask editor consists of five tabbed panes that are described in detail below.

Example Model

• The example model “Subsystem Masks” accompanies the explanations in this section.

• Find it in PLECS under Help > PLECS Documentation > List of Example Models.

Mask Icon

The Icon pane enables you to create icons that show descriptive text or labels, graphics and images.

Fig. 35 Mask Editor Icon Tab

Mask Icon Drawing Language

The Language selector lets you choose the programming language used for the drawing commands. Choose Lua to create dynamic icons that can change depending on user input or if you would like to make use of the PLECS Icon Library. Choose Legacy to select the syntax used by PLECS 4.1 and older.

Mask Icon Drawing Commands

The drawing commands available in the Lua language are described below. If you enter more than one command, the graphic objects are drawn in the order in which the commands appear. In case an error occurs during evaluation of the commands, PLECS displays three question marks (? ? ?) in the mask icon; if you hover the mouse over the subsystem block, a tooltip will show the error message.

Text

The commands

Icon:text('text')
Icon:text(x, y, 'text')

display text in the center of the icon or centered around the coordinates x, y. The text does not rotate with the icon; it is always displayed from left to right.

The second command can be followed by parameter/value pairs to specify additional properties listed in the table below.

Table 4 Text Properties

Property	Description
FontSize	An integer specifying the font size of the text.
TextFormat	Specify the string PlainText to display the text as is (the default) or RichText to enable HTML markup such as <b></b> or <sup></sup>.
Color	A string specifying the color name (preferred). All appearance-sensitive PLECS Colors are allowed. A vector {r, g, b} of three integers in the range from \(0\) to \(255\) specifying the color in RBG format. This color applies in light mode and is automatically transformed in dark mode (similar hue, inverted lightness). A table {light = {r, g, b}, dark = {r2, g2, b2}} assigning custom colors in RGB format to each appearance. Note The table’s dark mode color defaults to the light mode color, such that {light = {r, g, b}} results in a fixed color for all appearances.

Line

The command

Icon:line(xvec, yvec)

draws the line specified by the vectors xvec and yvec. Both vectors must have the same length. Note that vectors are entered using curly braces, e.g. {1, 2, 3}. The vectors may contain non-finite values such as 0/0 or 1/0. When non-finite values are encountered, the line is interrupted and continued at the next point that has finite values.

Patch

The command

Icon:patch(xvec, yvec)

draws a solid polygon with vertices specified by the vectors xvec and yvec. Both vectors must have the same length. Note that vectors are entered using curly braces, e.g. {1, 2, 3}.

Circle

The command

Icon:circle(x, y, r)

draws a circle with the center coordinates x, y and the radius r.

Ellipse

The command

Icon:ellipse(x, y, rx, ry)

draws an ellipse with the center coordinates x, y and the radii rx and ry.

Arc

The command

Icon:arc(x, y, rx, ry, start, span)

draws an elliptical arc with the center coordinates x, y and the radii rx and ry beginning at the start angle (in degrees) and extending span degrees counter-clockwise. The 0 degree angle is at 3 o’clock. Clockwise arcs can be drawn using a negative span angle.

Color

The commands

Icon:color('colorname')
Icon:color(r, g, b)
Icon:color({r, g, b})
Icon:color({light = {r, g, b}, dark = {r', g', b'}})

change the current drawing color. The new color can be defined by:

• A string colorname specifying the color name (preferred). All appearance-sensitive PLECS Colors are allowed.

• Three integers r, g and b or a vector {r, g, b} of three integers in the range from 0 to 255 specifying the color in RBG format. This color applies in light mode and is automatically transformed in dark mode (similar hue, inverted lightness).

• A table {light = {r, g, b}, dark = {r', g', b'}} assigning custom colors in RGB format to each appearance.

Note

The table’s dark mode color defaults to the light mode color, such that {light = {r, g, b}} results in a fixed color for all appearances.

Image

The commands

Icon:image(xvec, yvec, 'filename')
Icon:image(xvec, yvec, 'filename', 'on')

read an image from the file filename and display it on the mask icon.

The parameter filename must be either an absolute filename (e.g. C:/images/myimage.png) or a relative filename that is appended to the model’s directory (e.g. images/myimage.png). The recommended path separator is the forward slash (/). If you want to use the backslash (\) instead, note that the backslash is also used as an escape character, so you must enter two consecutive backslashes for a single path separator (e.g. C:\\images\\myimage.png). Supported image formats are BMP, GIF, JPG and PNG.

The two-element vectors xvec and yvec specify the minimum and maximum coordinates of the image’s extent. Note that vectors are entered using curly braces, e.g. {-10, 10}.

Use the optional flag 'on' to indicate that the image should rotate or flip together with the mask icon. By default, this is set to 'off', and the image orientation remains fixed.

Only one image can be displayed on a mask icon; if you use multiple image commands, only the last one will be effective.

Querying Parameter Values

The command

Dialog:get('variable')

returns the string value of the mask parameter associated with the variable variable. Note that the parameter values are not evaluated. Thus, if the user enters e.g. 2*2, the return value will be '2*2' and not '4'. The return value for a Combo Box parameter is a string containing the integer value of the chosen option or the expression entered by the user.

Querying Preferences

The command

Preferences:get('Appearance')

returns the current app appearance as a string, either "light" or "dark". This can be used for appearance-sensitive drawing commands beyond the normal color transformation.

The command

Preferences:get('DrawANSI')

returns true if the Symbol format setting is set to ANSI instead of DIN. This can be used for drawing commands which differ between these formatting conventions.

Legacy Command Syntax (PLECS 4.1 and older)

The legacy command syntax is listed in the following table. The meaning of the command arguments is analogous to the Lua syntax above. Vector parameters are entered using square brackets with optional commas for separating the elements, e.g. [1, 2, 3] or [3 4 5]. Single-line comments start with a percent sign (%). Note that the legacy syntax does not support all commands and options.

Table 5 Legacy Command Syntax

Command	Syntax
Text	text('text') text(x, y, 'text')
Line	line(xvec, yvec)
Patch	patch(xvec, yvec)
Circle	circle(x, y, r)
Color	color(r, g, b)
Image	image(xvec, yvec, imread('filename')) image(xvec, yvec, imread('filename'), 'on')

Mask Icon Coordinates

All coordinates used by the mask drawing commands are expressed in pixels. The origin of the coordinate system is always the center of the block icon; it is adjusted when the block is resized. In an unrotated and unflipped block, the x-axis stretches from the left towards the right, and the y-axis stretches from the top towards the bottom.

Use the icon frame and/or the terminal locations as reference points in order to position graphic elements. Both the frame and the terminals snap to a grid of \(10\) by \(10\) pixels.

Note

PLECS expects you to confine icon drawings to the boundaries of the subsystem frame. PLECS will not clip your drawings to the subsystem frame, but if you draw outside the frame, the drawings will not be erased properly e.g. when the subsystem is moved.

Mask Icon Properties

Show subsystem frame

The subsystem frame is the rectangle that encloses the block. It is drawn if this property is set, otherwise it is hidden.

Hide terminal labels

This property controls whether the terminal labels underneath the icon are shown or hidden. A terminal label is only shown if this property is unset and the name of the corresponding port block is visible.

Icon rotates

If drawing commands are provided, this property determines whether the drawn icon rotates when the component is rotated. The drawn icon remains stationary if this property is unchecked.

PLECS Colors

The PLECS palette contains all available appearance-sensitive colors which all PLECS components use for drawing their block/mask icon. They can be used in the Mask Icon Drawing Commands.

Table 6 PLECS Palette

Color name	Light	Dark	Description
"text"			default text color
"electrical"			electrical domain color
"signal"			signal connection color
"axis"			axis color for icons
"thermal"			thermal domain color
"thermalBg"			thermal domain background
"magnetic"			magnetic domain color
"magneticBg"			magnetic domain background
"rotational"			rotational domain color
"rotationalBg"			rotational domain background
"translational"			translational domain color
"translationalBg"			translational domain background
"event"			event connection color
"normalFg"			normal foreground
"normalBg"			schematic background (configurable in dark mode)

PLECS Icon Library

PLECS comes with a preinstalled Lua library for drawing basic electrical components. A selection of the available icons is displayed in Fig. 36.

Fig. 36 A selection of the built-in component icons of the PLECS Icon Library.

To gain access to this icon library, start by including the PLECS Icon Library via local IconLib = require('PlecsIconLib'). To reproduce the above image, you can copy the following code:

local IconLib = require('PlecsIconLib')
-- Passive elements
IconLib.resistor(-140, 0)
IconLib.capacitor(-100, 0, {rotate=270, flip=true, showPolarity=true})
IconLib.inductor(-60, 0, {showArrow=true})
IconLib.transformer(-20, 0, {showCore=true, showPolarity=true, polarity="+-"})

-- Semiconductor elements
IconLib.diode(20, 0)
IconLib.mosfet(60, 0, {deviceType="n"})
IconLib.bjt(100, 0, {deviceType="pnp"})
IconLib.igbtDiode(140, 0, {deviceType="n", shiftGate=true})

In the above code, each line draws exactly one icon. Each function follows the same syntax rules:

IconLib.component(x0, y0, params)

Here, component stands for the component icon to be drawn, x0 and y0 are the coordinates of the origin of the icon (see Fig. 37), and params = {key1=val1, key2=val2} is a table containing additional settings to customize the rendering of the icon (see Additional Parameters.).

The PLECS Icon Library supports drawing the following icons:

Component	Function Call
Node	IconLib.node(x0, y0)
Resistor	IconLib.resistor(x0, y0, params)
Capacitor	IconLib.capacitor(x0, y0, params)
Inductor	IconLib.inductor(x0, y0, params)
Ideal Transformer	IconLib.transformer(x0, y0, params)
Diode	IconLib.diode(x0, y0, params)
Thyristor	IconLib.thyristor(x0, y0, params)
MOSFET	IconLib.mosfet(x0, y0, params)
MOSFET with Diode	IconLib.mosfetDiode(x0, y0, params)
IGBT	IconLib.igbt(x0, y0, params)
IGBT with Diode	IconLib.igbtDiode(x0, y0, params)
Bipolar Junction Transistor	IconLib.bjt(x0, y0, params)
Junction Field Effect Transistor	IconLib.jfet(x0, y0, params)

Note

Legacy variants with function names that start with a capital letter are deprecated and should not be used anymore.

Icon Geometry

The PLECS Icon library uses the coordinate system introduced in section Mask Icon Coordinates. Icons rotate around their origin in clockwise direction and are, by default, drawn identically to the corresponding PLECS component. The geometric properties of the supported icons are summarized in the following figure:

Fig. 37 Icon origin and size. The origin of each icon component is indicated with a red dot. The maximal size in upright position (i.e., rotate=0 or rotate=180) is displayed above each icon.

Additional Parameters

Additional parameters are passed via a table of key = value entries. The following table summarizes the available options.

Keyword	Data Type	Description	Elements
rotate	Number	Specifies the rotation angle (clockwise rotation). Must be an integer multiple of 90.	all elements
flip	Boolean	Flips the unrotated icon about the x-axis.	all elements
wireLength	Number Table of Numbers	Specifies the additional length of the terminal wires. Can be either a number or a table of numbers (one number per terminal). The default value of 0 reproduces the standard icons used in the PLECS library browser.	all elements
showArrow	Boolean	Adds an arrow decoration to indicate the direction of positive current flow.	inductor
showPolarity	Boolean	Adds an annotation for the polarity of the device.	capacitor transformer
polarity	String	Sets the polarity of the transformer. Available options are "+", "-", "+-" and "-+". Note that the annotation is only shown if showPolarity is enabled.	transformer
showCore	Boolean	Adds a magnetic core decoration.	transformer
deviceType	String	Defines the transistor type. For a MOSFET, JFET or IGBT, use "n" and "p" to indicate the channel type. For a BJT, the available options are "npn" and "pnp". By default, "n" and "npn" are assumed, respectively.	mosfet mosfetDiode igbt igbtDiode bjt jfet
shiftGate	Boolean	Shifts the gate terminal towards the source terminal (MOSFET, JFET) or the emitter terminal (IGBT). By default, the gate terminal is centered.	mosfet mosfetDiode igbt igbtDiode jfet

Rotating and Flipping

You can flip and rotate basic component icons to create your own composite images. Icons are always flipped first and then rotated. We use the x-axis as mirroring axis in the unrotated coordinate system. As a consequence, this means that the mirroring axis rotates together with the icon. You can find an illustration of the combined effect of rotating and flipping icons in Fig. 38. The corresponding Lua code is listed below.

Fig. 38 Illustration of the effect of the rotate and flip keywords for a MOSFET with Diode.

local IconLib = require('PlecsIconLib')

-- 0° Rotation
IconLib.mosfetDiode(-90, -30, {rotate=0, flip=false})
IconLib.mosfetDiode(-90, 30, {rotate=0, flip=true})

-- 90° Rotation
IconLib.mosfetDiode(-30, -30, {rotate=90, flip=false})
IconLib.mosfetDiode(-30, 30, {rotate=90, flip=true})

-- 180° Rotation
IconLib.mosfetDiode(30, -30, {rotate=180, flip=false})
IconLib.mosfetDiode(30, 30, {rotate=180, flip=true})

-- 270° Rotation
IconLib.mosfetDiode(90, -30, {rotate=270, flip=false})
IconLib.mosfetDiode(90, 30, {rotate=270, flip=true})

-- Add annotations
Icon:text(-90, -70, "0°")
Icon:text(-30, -70, "90°")
Icon:text(30, -70, "180°")
Icon:text(90, -70, "270°")
Icon:text(150, -30, "normal")
Icon:text(150, 30, "flipped")

-- Draw the frame
Icon:color('axis')
Icon:line({-60, -60}, {-60, 60})
Icon:line({0, 0}, {-60, 60})
Icon:line({60, 60}, {-60, 60})
Icon:line({-120, -120}, {-60, 60})
Icon:line({120, 120}, {-60, 60})
Icon:line({-120, 120}, {0, 0})
Icon:line({-120, 120}, {-60, -60})
Icon:line({-120, 120}, {60, 60})

Additional Wire Length

At times, you may want to separate two elements by a distance larger than the combined wire length. You can extend the length of the terminal wires via the wireLength parameter. You may either specify a single number to extend (or decrease) every terminal wire by the same amount. Or, you can control the length of each terminal individually by providing a list of numbers. The length of that list must match the number of terminals. The order used in this list is defined for the component in the original coordinate system, according to Fig. 39.

Fig. 39 Identification of the terminal oder for the wireLength parameter.

Mask Dialog

The Dialog pane enables you to define the parameters that will appear in the dialog box of the masked subsystem.

Fig. 40 Mask Editor Dialog Tab

Prompts and Associated Variables

Mask parameters are defined by a Prompt, a Variable and a Type. The prompt provides information that helps the user identify the purpose of a parameter. The variable name specifies the variable that will be assigned the parameter value. The possible parameter types are described in the table below.

Type	Description
Edit	Shows a line edit field. The entered text is interpreted as a MATLAB/Octave expression and is evaluated when a simulation is started.
String	Shows a line edit field and a selector that controls whether the entered text is interpreted as a literal string or as a MATLAB/Octave expression that evaluates to a string.
Combo Box	Shows a pop-up menu that allows the user to select an item from a list of possible options. Use the Combo box values editor below the parameter list to enter the list of possible options and their associated integer values that are assigned to the parameter variable. The values must be unique integers.
String-Valued Combo Box	Shows a pop-up menu that allows the user to select an item from a list of possible options. Use the String-valued combo box values editor below the parameter list to enter the list of possible options and their associated string values that are assigned to the parameter variable.
Thermal	Shows a thermal parameter editor that allows the user to specify a thermal description (see Thermal Description Parameter for details). If you enter a text in the Device type filter editor below the parameter list, the thermal parameter editor will show only thermal descriptions that have the matching device type. Otherwise, all thermal descriptions will be shown.

Mask parameters appear on the dialog box in the order they appear in the prompt list. You can add or remove parameters or change their order by using the four buttons to the left of the prompt list.

Note

In PLECS Standalone, the maximum length of variable names is 63 characters. This is due to the way in which a mask workspace is stored in PLECS and exchanged with Octave. It is advisable to observe this limit also in PLECS Blockset to ensure that a model can be exchanged with PLECS Standalone.

Tab Names

You can group parameters into separate tabs shown in the parameter dialog by assigning a tab name in the Tab column. All parameters that have the same tab name will appear on the same tab page in the parameter dialog.

Tunable Parameters

By default, mask parameter values cannot be modified during a simulation. However, if you check the box in the Tunable column, the corresponding parameter will be made tunable so that you can in fact modify it interactively during a simulation by entering a new value in the parameter dialog. Whenever you change the parameter, PLECS will re-evaluate the parameter variable and the mask initialization commands and propagate the new variable values to the underlying components, which in turn must have tunable parameters. If a changed variable is used in a non-tunable component parameter, the change will have no effect until the simulation is restarted.

Dialog Callback

The dialog callback is a Lua function that is executed whenever the user changes a mask parameter. You can use it to disable or hide a parameter or change its value depending on the value of another parameter.

Querying Parameter Values

The command

Dialog:get('variable')

returns the string value of the mask parameter associated with the variable variable. Note that the parameter values are not evaluated. Thus, if the user enters e.g. 2*2, the return value will be '2*2' and not '4'. The return value for a Combo Box parameter is a string containing the integer value of the chosen option or the expression entered by the user.

Setting Parameter Properties

The command

Dialog:set('variable', 'property', value, ...)

changes one or more properties of the mask parameter associated with the variable variable. The properties are listed in the following table.

Property	Description
Value	A string specifying the parameter value
Enable	A boolean (i.e. true or false) specifying the enable state of the parameter. A disabled parameter is greyed out in the dialog and cannot be modified.
Visible	A boolean (i.e. true or false) specifying the visibility of the parameter in the dialog

Note

Parameters that are disabled or invisible are not evaluated, and the parameter variables are assigned a NaN value (not a number).

Hiding, Showing and Moving Terminals

The command

Block:showTerminal('name', flag)

shows or hides the terminal named name depending on the boolean value flag. The companion port of a hidden terminal acts in the same way as if the terminal was shown but unconnected.

The command

Block:moveTerminal('name', x, y)

moves the terminal named name to the relative coordinates x, y with respect to the unrotated and unflipped block. Note that the terminal rotation is not changed.

Mask Workspace

Variable Scope

PLECS associates a local variable workspace with each masked subsystem that has one or more mask parameters defined. Components in the underlying schematics can access only variables that are defined in this mask workspace.

Initialization Commands

Fig. 41 Mask Editor Initialization Tab

Mask initialization commands are defined on the Initialization pane. They are evaluated in the mask workspace when a simulation is started. You can enter any valid MATLAB/Octave expression, consisting of MATLAB/Octave functions, operators, and variables defined in the mask workspace. Variables defined in the base workspace cannot be accessed. The dialog parameter variables are listed on the left hand side of the tab.

You can use mask initialization commands to check the user input, e.g. whether a variable value is within a certain range, or to define additional workspace variables that may be derived from mask parameters.

To show an error message in the Diagnostics window, e.g. that a certain mask parameter value is not valid, use the commands:

plecs('error', '<error message>')
return

Notice that the plecs('error', '<error message>') command by itself does not cause an early exit of the execution of the mask initialization commands, so it should generally be followed by a return statement to avoid subsequent errors.

To show a warning message in the Diagnostics window, use the command:

plecs('warning', '<warning message>')

To show information in the Diagnostics window, use the command:

plecs('info', '<info message>')

Note

In PLECS Standalone, the maximum length of variable names is 63 characters. This is due to the way in which a mask workspace is stored in PLECS and exchanged with Octave. It is advisable to observe this limit also in PLECS Blockset to ensure that a model can be exchanged with PLECS Standalone.

Mask Probe Signals

The Probes pane enables you to define the probe signals that the masked subsystem will provide to the PLECS Probe. Mask probe signals appear in the probe editor in the order they appear in the mask signal list. You can add or remove signals or change their order by using the four buttons to the left of the signal list.

Fig. 42 Mask Editor Probes Tab

Mask probe signals are defined as vectors of probe signals from components below the subsystem mask. For this reason the controls in the lower half of the dialog are identical to those of the probe editor. In order to define a mask signal, select the signal in the list and then drag the desired components into the dialog window. The new components are added to the bottom of the list of probed components. Next, select the components one by one and enable the desired component signals in the list on the right side by using the check boxes.

Mask Documentation

The Documentation pane enables you to define the descriptive text that is displayed in the dialog box of the masked subsystem.

Fig. 43 Mask Editor Documentation Tab

Mask Type

The mask type is a string used only for purposes of documentation. PLECS displays this string in the dialog box and appends “(mask)” in order to differentiate masked subsystems from built-in components.

Mask Description

The mask description is informative text that is displayed in the dialog box in the frame under the mask type. Long lines of text are automatically wrapped to fit into the dialog box. You can force line breaks by using the Enter or Return key.

Mask Help

The mask help is a URL that provides documentation in addition to that provided by the mask description. This documentation is shown in a separate window when the user clicks the Help button in the dialog box of the masked subsystem. Currently, the following URL types are supported:

Remote URL

A URL of the form https://www.plexim.com is opened using the default browser of your operating system.

Local HTML File

A local HTML file is specified with an absolute path (e.g. file:///C:/absolute/path/helpdoc.html) or with a relative path (e.g. file:relative/helpdoc.html). A relative path is resolved relative to the parent folder of the model file containing the subsystem. If the subsystem is a library link or model reference, the relative path is resolved relative to the parent folder of the source library or model file. Local HTML files are also opened using the default browser of your operating system.

Unprotecting Masked Subsystems

If you define a mask icon for a Subsystem block, PLECS automatically protects the block and the underlying schematic. You can no longer resize the Subsystem block or modify the sub-schematic. The purpose of this protection is to prevent the user from making unintentional changes that might render the icon useless.

If you want to change a masked Subsystem block, you can unprotect it by choosing Unprotect from the Edit > Subsystem menu or the block’s context menu. You can later protect it again by choosing Protect from the same menus.

Getting Started with Lua

Lua is a simple yet powerful open-source scripting language. This section introduces you to the basic concepts that you are likely to need in order to create dynamic subsystem masks. For a full reference please visit the Lua site.

Types and Variables

Lua is a dynamically typed language, which means that types are not associated with variables but only with values. To define a variable, you simply assign a value to it.

By default, Lua declares all variables as global. However, PLECS executes Lua code in a protected environment that forbids the creation or modification of global variables. Therefore, you must explicitly declare variables as local using the local keyword, e.g.:

local a = "a string"

The most basic types in Lua are: nil, boolean, number, string and table. You can query the type of a value with the function type which returns the type name as a string.

Nil

Nil is a type with the single value nil. It is used to represent the absence of a useful value.

Booleans

The Boolean type has two values false and true. It can be used in conditional expressions. If you use other types in conditional expressions, beware that Lua considers only the Boolean false and nil as false and anything else as true. In particular, both the numerical 0 and the empty string '' or "" are considered true in conditional tests.

Lua supports the logical operators and, or and not.

Numbers

Lua differentiates between (double-precision) floating point numbers and (64-bit) integer numbers. Numerals with a decimal point or an exponent are considered floats; otherwise, they are treated as integers.

Strings

String literals in Lua can be delimited by single or double matching quotes:

local a = "a string"
local b = 'another string'

The difference between the two kinds is that inside one kind of quotes you can use the other kind of quote without needing to escape it. The escape character is the backslash (\), and the common C escape sequences such as \n for newline are supported.

Long string literals are delimited with matching double square brackets that enclose zero or more equal signs, e.g. [[...]] or [==[...]==]. They can span several lines and do not interpret escape sequences.

Tables

Tables are Lua’s generic data structuring mechanism. They are used to represent e.g. arrays, sets or records. A table is essentially an associative array that accepts as keys not only numbers or strings but any other value except nil. A table is constructed with curly braces and a sequence of key/value pairs, e.g.:

a = { x = 10, y = 20 }

A numerical vector as used in the mask icon drawing commands is just a table with 1-based consecutive integer keys and numeric values. It can be constructed using the shorthand form of omitting the keys and just specifying the values:

a = { 1, 2, 3 }

Alternatively, a numerical vector can be constructed using the following PLECS specific syntax extension:

a = Vector{ 1, 2, 3 }

A vector constructed in this way can be added to or multiplied with a scalar value. This is especially helpful in icon drawing functions if the graphic object shall be displaced or scaled:

a_x = Vector{ 1, 2, 3 }*zoom_factor + x_offset
a_y = Vector{ 4, 5, 6 }*zoom_factor + y_offset

Comments

A simple comment starts anywhere with two consecutive hyphens (--) and runs until the end of the line. Long comments start with two hyphens followed by two square brackets (--[[) and continue until the first occurrence of two closing square brackets (]]).

A common trick is to use --]] to end a long comment to quickly comment and uncomment a block of code:

--[[
Icon:line({-10, 10}, {-10, 10})      -- commented out
--]]

To un-comment the code block, prepend another hyphen to the first line:

---[[
Icon:line({-10, 10}, {-10, 10})      -- will be executed
--]]

In the first example, the --[[ starts a long comment that continues until (and including) the ]] in the third line. In the second example, the first two hyphens start an ordinary single-line comment, and so the second line is not commented out. The two hyphens at the beginning of the third line again start a single-line comment. Without these hyphens, the unpaired closing square brackets in the third line would cause a syntax error.

Statements

Lua does not need an explicit separator between consecutive statements, but you can use a semicolon if you wish. Also, line breaks are treated like ordinary white space, so you can split a single statement into multiple lines without having to use a special continuation mark.

Relational Operators

Lua supports the following relational operators:

<   >   <=   >=   ==   ~=

Relational operators always return a Boolean value. The == operator tests for equality and the ~= operator for inequality. They can be applied to any two values. If the values have different types, Lua considers them not equal. Otherwise, they are compared according to their type.

Functions

A function is defined as follows:

local function drawTriangle(x, y)
  Icon:line(Vector{0, 8.66, -8.66, 0}+x,
            Vector{-10, 5, 5, -10}+y)
end

As with variables, the local keyword is required because without it the function would be declared globally, which PLECS forbids. A function definition consists of the keyword function, a name (drawTriangle), a list of parameters (x, y), a body, i.e. a list of statements, and the terminator end. Parameters are local variables that are initialized with the values of the arguments passed in the function call.

The example above defines a function that draws a triangle with the center point \(x, y\). The function can be called as follows:

drawTriangle(-10, 0)
drawTriangle(10, 0)

A function can also return values using the return statement:

local function sum(values)
  local result = 0
  for i = 1, #values do
    result = result + values[i]
  end
  return result
end

local x = sum({1, 2, 3})    -- x will be 6

Control Structures

Lua provides control structures for conditional execution and iteration.

if, then, else

The if statement tests its condition and executes the then branch if the condition is true and otherwise the else part. The condition can result in any value, but as mentioned earlier, Lua treats all values other than nil and false as true. In particular, both the numerical 0 and the empty string ('') are treated as true.

if Dialog:get('choice') == '1' then
  Icon:text('+')
else
  Icon:text('-')
end

Multiple conditions can be tested with the elseif statement. It is similar to an else followed by an if but avoids the need for and extra end:

if Dialog:get('choice') == '1' then
  Icon:text('+')
elseif Dialog:get('choice') == '2' then
  Icon:text('-')
else
  Icon:text('+/-')
end

for

The for statement has the following form:

for x = -10, 10, 5 do
  Icon:line({x, x}, {-10, 10})
end

The loop variable, x, which is implicitly local to the loop, is successively assigned the values from -10 to 10 with an increment of 5, and for each value the loop body is executed. The result of the example will be five parallel vertical lines. The step value is optional; if it is omitted, Lua will assume a step value of 1.

Lua also provides other control structures (iterator-based for, while, repeat). However, these are not relevant for dynamic masks.