What to Script

Scripting can be used to interact with XML elements, or to create variables and functions for custom applications. It is important to note that scripting in qdex is essentially programming; while open-ended, it is easy to compromise document stability. 

Call a Method

Methods are used to change the state of XML elements, and can include starting/stopping a simulation, resetting the axis range of a plot, or interacting with a button or toggle. Available methods can be found on the Scripting Reference page, and the Simulation Properties page.

The example below shows two ways to call a simulation Start() method from a button's onClick event. 

 
<button content="Start Simulation">
  <onClick>
    mySim:Start()
  </onClick>
</button>
 
<button content="Start Simulation" onClick="mySim:Start()" />

Alter a Property

Properties define how an XML element appears or works. Some properties that can be changed are style properties (color, visibility, margins, etc), the value of a slider, or the text in a paragraph. Some properties are read only, meaning that you can retrieve their value, but cannot alter it. 

It is important to note the type of value that a property is expecting to receive. For example, when assigning the value of a slider to a number taken from a textField, the value must first be converted from string to float using the Lua function tonumber().

Available properties can be found on the Scripting Reference page, and the Simulation Properties page.

In the example below, the Text property of a paragraph is updated each time the value of the slider changes.

 
<p name="myPar" />

<slider min="0" max="10">
  <onValueChanged>
    myPar.Text = string.format("Value of slider: %0.1f", value)
  </onValueChanged>
</slider>

Custom

The scripting engine that is included in the qdex framework is built on NLua which binds the Lua scripting language to .NET. Because of this, authors have the freedom to create code in their modules that go beyond altering XML elements. For more information on the basic structure and syntax of Lua check out the Reference Manual. Note that some elements of Lua are not accessible from qdex (e.g. I/O, print); post on the forum if you need clarification. 

The below example combines all three scripting types into a simple kinematic equation solver.

  1. Custom variables and a function are defined to calculate the value of a kinematic equation.
  2. The function also updates the Text property of a paragraph.
  3. The onActivePageChanged event calls the simulation Start() method.
 
<script>
  local vi = 10;
  local a = 1;
  
  local function launch(t)
    d = vi*t + 0.5*a*t*t
    myLabel.Text = string.format("Distance = %0.2f", d)
  end
</script>
    
<p name="myLabel" />
    
<simulation name="distSim" onActivePageChanged="distSim:Start()" onUpdate="launch(time)" duration="10" />

Where to Script

There are a few places where you can define a script, depending on the situation and what the script will do.

Events

The most common place to define a script is inside an event, where it will be triggered when that event is triggered. A common event is the onClick event inside of a button, which will execute the script when the button is tapped on by the user.

Events can be identified by the "on" prefix of their name. A list of events that can be accessed in qdex can be found below.

Script Tag

Another place where scripts can be defined is inside script tags. They are an ideal place to define any script that will be accessed by multiple elements, such as variables and functions. It is also where variables should first be initialized before being altered by a script inside of an event. 

In the below example, a variable is defined inside of a script tag. Each time a button is pressed in the app, the variable is incremented and a paragraph outputs the new value of the variable to a paragraph. 

<script>
  -- Defining and initialising the variable
  local myVariable = 5 
</script>

<button content="Tap this Button!">
  <onClick>
    -- Incrementing the value
    myVariable = myVariable + 1 
    -- Displaying the new value inside of a paragraph
    thisPar.Text = string.format("The value of myVariable is %d", myVariable)  
  </onClick>
</button>

<p name="thisPar"/>

The above example could also be written using a function, where the onClick event calls a function that performs the same actions.

<script>
  -- Defining and initialising the variable
  local myVariable = 5 
  
  --Defining a function to increment the variable and update the paragraph
  local function addValue()
    myVariable = myVariable + 1 
    thisPar.Text = string.format("The value of myVariable is %d", myVariable)  
  end
</script>

<button content="Tap this Button!">
  <onClick>
    addValue()
  </onClick>
</button>

<p name="thisPar"/>

It doesn't necessarily make sense to use a function in the above example, as the function performs a single action that is just as easily defined inside the onClick event. Functions are better used to define generic actions so that they can be used by multiple elements easily.

In the below example, a function is used to increment a specified variable by a specified number. Two different buttons can use this one function to perform different tasks by changing the arguments to the function. 

<script>
  -- Defining and initialising the variables
  local myVariable = 5 
  local myOtherVariable = 8
  
  --Defining a function to increment a variable by the specified number
  local function addValues(variableName, addNumber)
    variableName = variableName + addNumber 
  end
</script>

<button content="Tap this Button!">
  <onClick>
    -- Increment myVariable by 1 on each click
    addValue(myVariable, 1)
  </onClick>
</button>

<button content="Tap this Other Button!">
  <onClick>
    -- Increment myOtherVariable by -3 on each click
    addValue(myOtherVariable, -3)
  </onClick>
</button>

System Block

Although traditionally used to define a custom system with states in a simulation, the system block can also be used to pass Lua script between elements inside and outside of a simulation.

In the below example, the amplitude of a sine wave is output to a label in real time.

<label name="thisLabel" />

<simulation name="sim">
  <onActivePageChanged>
    if active then
    sim:Start()
    else
    sim:Stop()
    end
  </onActivePageChanged>
  <solver>
    <series>
      <sine />
      <system name="outputMySine">
        <input name="ampValue" width="1" />
        <onOutputs>
          thisLabel.Text = string.format("%0.2f", ampValue[1])
        </onOutputs>
      </system>
    </series>
  </solver>
</simulation>

The system block can also be used to send a value to a simulation so that it can be manipulated or streamed. In this example, the value of a toggle and a slider are put into a vector and brought into a simulation using a system. The vector is then sent to hardware over TCP/IP.

<client name="myStream" uri="tcpip://172.16.0.62:18000" />

<script>
  local valueVector = vector(2);
</script>

<toggle name="toggleName">
  <onValueChanged>
    valueVector[1] = toggleName.Value;
  </onValueChanged>
</toggle>

<slider name="mySlider" min="0" max="15" value="0">
  <onValueChanged>
    valueVector[2] = value;
  </onValueChanged>
</slider>

<simulation name="sim" period="0.01">
  <solver name="solver2">
    <series>
      <system name="mySystem">
        <output name="myOutput" width="2" />
        <onOutputs>
          return valueVector
        </onOutputs>
      </system>
      <probe ref="mySection.myStream" />
    </series>
  </solver>
</simulation>

Scope

Scope refers to the portion of the document structure where a particular piece of code can see other elements, or be seen by other elements. The general scoping rule for scripts is that the closer an element is to a top-level section, the more it can be seen other elements. When elements are declared deep inside of nested sections they are harder to see.

In the following example code and representative diagram, Parent A is a top-level section that contains four children: two buttons, a stack, and a section. Let's use the diagram to define who can see who: 

  • Children 1, 2, 3 & 4 can see each other
  • Children 1 & 2 cannot see the children inside Children 3 & 4 (i.e. Children 3a, 3b, 3c & 4a)
  • Children 3a, 3b & 3c can see each other
  • Children 3a, 3b & 3c can can also see Children 1, 2, 3 & 4 
  • Child 4a can see Children 1, 2, 3 & 4 
scope-parent-children.jpg 
<sectionNoTitle name="parentA">
  
  <button name="child1" />
  
  <button name="child2" />
  
  <stack name="child3">
    <button name="child3a" />
    <button name="child3b" />
    <button name="child3c" />
  </stack>
  
  <sectionNoTitle name="child4">
    <button name="child4a" />
  </sectionNoTitle>

</sectionNoTitle>

If Child 1 contains a script to control Child 3a it will first need to specify where to look for it, i.e. inside Child 3. 

<button name="child1">
  <onClick>
    child3.child3a.Text = "New Text on Button"
  </onClick>
</button>
<button name="child1">
  <onClick>
    child3a.Text = "New Text on Button"
  </onClick>
</button>

This script would not work

This script works

 

For variables that are declared in Lua, if you specify that the variable is local then it's scope is limited to elements in the same level or higher, as outlined above. If you declare a variable without the local modifier, then it is treated as global and is open to the entire document. To avoid issues with shared names, or other conflicts, we recommend that all variables be declared as local unless absolutely necessary.

Alerts

Alerts are typically used to notify your user that a change of state has occurred in a module (a simulation has started/ended, a communications connection has been established, etc). They can also be used to debug pesky issues within your scripts.

Alerts can quickly become annoying to the user; we recommend using the below alerts sparingly in your modules.

Notification

To send a popup notification to the user simply call the notification in an appropriate location. The below example displays a notification each time a user presses a button. 

<button content="Press Me">
  <onClick>
    notify('Button pressed')
  </onClick>
</button>
 
 

Vibrate

The vibrate function vibrates a user's device for the specified duration (in milliseconds). If a user's device does not have the ability to vibrate, a beep may sound instead. 

In the below example, a simulation is started when the page is loaded. When the simulation reaches duration, the device will vibrate for 400 ms.

<simulation name="sim" duration="5">
  <onActivePageChanged>
    if active then sim:Start() else sim:Stop() end
  </onActivePageChanged>
  <onDuration>
    application.vibrate(400);
  </onDuration>
</simulation>

Beep

The beep function will emit a tone from the user's device when called. The volume of the beep depends on the device's ringtone/notification volume settings. 

In the below example, a simulation is started when the page is loaded. When the simulation reaches duration, the device will beep. 

<simulation name="sim" duration="5">
  <onActivePageChanged>
    if active then sim:Start() else sim:Stop() end
  </onActivePageChanged>
  <onDuration>
    application.beep();
  </onDuration>
</simulation>

Child Method

The Child method allows you to access the child elements of stacks, sections, and tables without having to explicitly name each element. For example,

<stack name="myStack">
  <p name="par1">Words in the first paragraph</p>
  <p>Words in the second paragraph</p>
</stack>

The above stack contains two paragraphs, which can be referenced using myStack:Child(1) and myStack:Child(2), respectively. To change the text of the first paragraph, use myStack:Child(1) in the same way that you would use the name and scope of the paragraph element, i.e. 

<script>
   myStack.par1.Text = "New words in the first paragraph"
   -- is the same as
   myStack:Child(1).Text = "New words in the first paragraph"
</script>

The child method helps to reduce code when altering many child elements programmatically. See below for two common use cases.

Tables

The first use case allows you to access the cells of a table through a function. In the below example, a function is used to fill out the table cells.  A similar method can be used to read the table cell values. 

<script>
  function fillOutTable()
   for i = 2,3 do
    for j = 1,3 do
      myTable:Child(i):Child(j):Child(1).Text = string.format("(%d, %d)", i-1,j)
    end
   end
  end
</script>

<table name="myTable" widths="33% 33% 34%">
  <head>
    <column>
      <p>Column 1</p>
    </column>
    <column>
      <p>Column 2</p>
    </column>
    <column>
      <p>Column 3</p>
    </column>
  </head>
  <row>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
  </row>
  <row>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
    <column>
      <p />
    </column>
  </row>
</table>

Calling the fillOutTable() method from a button results in

 
table-script.jpg
 

The index i in the above example starts at 2 because the <head> element is the first child in the table. 

Radio Buttons

The second use case allows you to create radio-like buttons by altering the colour of the selected and deselected buttons.

<style name="setButtons">
  <foreground color="white" />
  <background color="gainsboro" />
</style>

<script>
  local priorSelection = -1;

  function chooseButton(i)
    if priorSelection > 0 then
      stack:Child(priorSelection).Style.BackgroundColor = color.gainsboro;
    end
    stack:Child(i).Style.BackgroundColor = color.seaGreen;
    priorSelection = i;
  end
</script>

<stack name="stack" orientation="horizontal">
  <button content="One" style="setButtons">
    <onClick>
      chooseButton(1)
    </onClick>
  </button>
  <button content="Two" style="setButtons">
    <onClick>
      chooseButton(2)
    </onClick>
  </button>
  <button content="Three" style="setButtons">
    <onClick>
      chooseButton(3)
    </onClick>
  </button>
</stack>

Note that children elements are 1-indexed, where the first element is Child(1) and not Child(0). Styles do not count as children.

Vectors

It is important to note that the calls that are referenced in this section are made using the standard vector tools, but can alternatively be made using the vectorf tools to utilize the floating point library. The float versions of the operations are more computationally efficient, but less accurate.

Constructors

  • Create a vector from a one-dimensional Lua table
    • d = vector({1, 2, 3, 4});
  • Create a vector using a delegate to initialize the elements
    • d = vector(3, function (i) return i*i; end);
  • Create a vector with all elements initialized to the given value
    • d = vector(3, 0.5);
  • Create a vector with all elements initialized to zero
    • d = vector(3);
  • Create a dense vector from a one-dimensional Lua table
    • d = vector.dense({1, 2, 3, 4, 5, 6, 7, 8, 9});
  • Create a dense vector using a delegate to initialize the elements
    • d = vector.dense(3, function (i) return i; end);
  • Create a dense vector with all elements initialized to the give value
    • d = vector.dense(3, 0.5);
  • Create a dense vector with all elements initialized to zero
    • d = vector.dense(3);
  • Create a random vector
    • d = vector.random(3)
  • Create a random vector with the specified length, uniformly distributed between the minimum and maximum values
    • d = vector.random(3, 0, 1)
  • Create a random vector with the specified length, minimum and maximum values, and random seed
    • d = vector.random(3, 0, 1, 1234)
  • Create a vector containing a linear range with specified start, step, and stop values
    • d = vector.linearRange(0, 2, 8)
  • Create a linearly spaced vector with the specified start, stop, and length
    • d = vector.linearSpaced(0, 14, 3)
  • Create a complex vector from a one-dimensional Lua table
    • c = vectorc({1 + 2*complex.i, 2, 3, 4, 5, 6, 7, 8, 9})
  • Create a complex vector using a delegate to initialize the elements
    • c = vectorc(3, function (i) return i*complex.i; end)
  • Create a complex vector with all elements initialized to the give value
    • c = vectorc(3, 0.5 + complex.i)
  • Create a random complex vector with the specified length, uniformly distributed between the minimum and maximum values
    • c = vectorc.random(3, 0, 1)

Subvectors

  • Return the subvector starting at the specified index and including the rest of the vector
    • v = d:subvector(index)
  • Return the subvector starting at the specified index and having the given length
    • v = d:subvector(index, count)
  • Modify current vector by setting subvector stating at the given index to new value
    • d:subvector(index, valueVector)
  • Modify current vector by setting subvector stating at the given index and including specified number of elements to new value
    • d:subvector(index, count, valueVector)

Miscellaneous 

  • Return number of vector elements
    • n = d.count
  • Clone a vector
    • v = d:clone()
  • Return a vector whose elements have been cycled by the given integer, e.g. for d = {1,2,3,4}, set v = {3,4,1,2} using
    • v = d:cycle(2)
  • Convert vector to vectorf
    • v = d:toFloat()
  • Convert vectorf to vector
    • v = d:toDouble()
  • Convert vectorc to real and imaginary vectors
    • r, i = c:toCartesian()
  • Convert vectorc to magnitude and phase vectors
    • m, p = c:toPolar()
  • Return a complex vector containing the Fast Fourier Transform of the input vector
    • c = d:fft()
  • Return a complex vector containing the inverse Fast Fourier Transform of the input vector
    • c = d:ifft()

Math

  • Return the absolute maximum value of the elements
    • n = d:absmax()
  • Return the absolute minimum value of the elements
    • n = d:absmin()
  • Return the maximum value of the elements
    • n = d:max()
  • Return the minimum value of the elements
    • n = d:min()
  • Return a vector of the ceiling of each element
    • v = d:ceiling()
  • Return a vector of the floor of each element
    • v = d:floor()
  • Return the dot product of two vectors (d and c)
    • n = d:dot(c)
  • Return the p-norm of a vector, specify p
    • n = d:norm(p)
  • Return the infinity-norm of a vector
    • n = d:normInf()
  • Return the L1-norm of a vector
    • n = d:normL1()
  • Return the L2-norm of a vector
    • n = d:normL2()
  • Return the outer product of two vectors (d and c)
    • m = d:outerProduct(c)
  • Return the point-wise division of each element (d by c)
    • v = d:pdiv(c)
  • Return the exponential of each vector element
    • v = d:pexp()
  • Return the logarithm of each vector element
    • v = d:plog()
  • Return the point-wise modulus of each element (d and c) 
    • v = d:pmod(c)
  • Return the point-wise multiplication of each element (d and c)
    • v = d:pmul(c)
  • Return each vector element to the specified exponent
    • v = d:ppow(e)
  • Return the point-wise remainder of each element (d and c)
    • v = d:prem(c)
  • Return the point-wise trigonometric function result of each vector element 
    • v = d:psin()
    • v = d:pcos()
    • v = d:ptan()
    • v = d:pasin()
    • v = d:pacos()
    • v = d:patan()
    • v = d:psinh()
    • v = d:pcosh()
    • v = d:ptanh()

Comparison

  • Return a vector of 1's and 0's for the less-than comparison (d < e, where e is a vector or a number) 
    • v = d:less(e)
  • Return a vector of 1's and 0's for the less-than or equal to comparison (d <= e, where e is a vector or a number)
    • v = d:lessOrEqual(e)
  • Return a vector of 1's and 0's for the greater-than comparison (d > e, where e is a vector or a number) 
    • v = d:greater(e)
  • Return a vector of 1's and 0's for the greater-than or equal to comparison (d >= e, where e is a vector or a number)
    • v = d:greaterOrEqual(e)
  • Return a vector of 1's, -1's and 0's denoting the sign of each vector element
    • v = d:sign()

Indexing

  • local n = vectorName[1];
  • ans = myVector.at(1);

Operators

  • Addition (+)
  • Subtraction (-)
  • Multiplication (*)
  • Division(/)

Matrices

It is important to note that the calls that are referenced in this section are made using the standard matrix tools, but can alternatively be made using the matrixf tools to utilize the floating point library. The float versions of the operations are more computationally efficient, but less accurate.

Constructors

  • Create a matrix from a two-dimensional Lua table
    • d = matrix({{1, 2, 3}, {4, 5, 6}, {7, 8, 9}});
  • Create a matrix from a one-dimensional Lua table
    • d = matrix(3, {1, 2, 3, 4, 5, 6, 7, 8, 9});
  • Create a matrix with all elements initialized to the given value
    • d = matrix(3, 3, 0.5);
  • Create a matrix with all elements initialized to zero
    • d = matrix(3, 3);
  • Create an identity matrix of the order specified
    • d = matrix.eye(3);
  • Create a matrix using a delegate to initialise elements
    • d = matrix(3, 3, function (i,j) return i+(2*j); end);
  • Create a sparse matrix from a dense Lua table 
    • d = matrix.sparse({{0, 0, 0}, {0, 1, 0}, {5, 0, 0}});
  • Create a sparse matrix from a Lua table using {[row]={[col]=#, ... }, ... }, e.g. to create {{1,0,0}, {0,0,0}, {0,5,7}} do
    • d = matrix.sparse(3, 3, {{1}, [3]={[2]=5, [3]=7}});
  • Create a diagonal matrix given a Lua table, e.g. to create {{1,0,0}, {0,2,0}, {0,0,1}} do
    • d = matrix.diagonal({1, 2, 1})
  • Create a diagonal matrix given a Lua table, e.g. to create {{1,0,0,0}, {0,2,0,0}, {0,0,1,0}} do
    • d = matrix.diagonal(3, 4, {1, 2, 1})
  • Create a diagonal matrix with the diagonal initialized to the given value, e.g. to create {{5,0,0,0}, {0,5,0,0}, {0,0,5,0}} do
    • d = matrix.diagonal(3, 4, 5);
  • Create a dense matrix from a one-dimensional Lua table
    • d = matrix.dense(3, {1, 2, 3, 4, 5, 6, 7, 8, 9});
  • Create a dense matrix from a two-dimensional Lua table
    • d = matrix.dense({{1, 2, 3}, {4, 5, 6}, {7, 8, 9}});
  • Create a dense matrix using a delegate to initialize the elements
    • d = matrix.dense(3, 3, function (i,j) return 3*i+j; end);
  • Create a dense matrix with all elements initialized to the give value
    • d = matrix.dense(3, 3, 0.5);
  • Create a dense matrix with all elements initialized to zero
    • d = matrix.dense(3, 3);
  • Create a double-precision sparse matrix using a delegate to initialize the elements
    • d = matrix.dense(3, 3, function (i,j) return 3*i+j; end);
  • Create a random matrix
    • d = matrix.random(3, 3);
  • Create a random matrix with the specified size, minimum and maximum values, and random seed
    • d = matrix.random(3, 3, 0, 1, 1234)
  • Create a random matrix with the specified size, uniformly distributed between the minimum and maximum values
    • d = matrix.random(3, 3, 0, 10)

Submatrices

  • Return the submatrix starting at the given row and column and including the rest of the rows and columns
    • new = d:submatrix(row, column)
  • Return the submatrix starting at the given row and column and including the given number of rows and columns
    • new = d:submatrix(startRow, numRows, startColumn, numColumns)
  • Modify current matrix by setting submatrix starting at the given row and column, and including the rest of the rows and columns, to new value
    • d:submatrix(row, column, value)
  • Modify current matrix by setting submatrix starting at the given row and column, and including the given number of rows and columns, to new value
    • d:submatrix(startRow, numRows, startColumn, numColumns, value)

Miscellaneous

  • Access number of rows/columns
    • numR = d.rowCount
    • numC = d.columnCount
  • Set the value in the specified row and column
    • d:at(1, 1, 8.53)
  • Return number of elements in specified row
    • n = d[2].count
  • Clone a matrix
    • m = d:clone()
  • Clone the specified row as a vector
    • v = d[1]:clone()
  • Return a matrix whose row and column elements have been cycled by the given integers, e.g. for d = {{1,2}, {3,4}, {5,6}}, set m = {{4,3}, {6,5}, {2,1}} using
    • m = d:cycle(1,1)
  • Convert a matrix to a matrixf
    • m = d:toFloat()
  • Convert a matrixf to a matrix 
    • m = d:toDouble()

Math

  • Return a matrix of the ceiling of each element
    • m = d:ceiling()
  • Return a matrix of the floor of each element
    • m = d:floor()
  • Return the condition number of a matrix
    • n = d:cond()
  • Return the determinant of a matrix
    • n = d:det()
  • Return the power of a matrix
    • m = d:pow(2)
  • Return the trace of a matrix
    • n = d:trace()
  • Return the transpose of a matrix
    • m = d:transpose()
  • Return the infinity-norm of a matrix
    • n = d:normInf()
  • Return the L1-norm of a matrix
    • n = d:normL1()
  • Return the L2-norm of a matrix
    • n = d:normL2()
  • Return the point-wise division of each element (d by c)
    • m = d:pdiv(c)
  • Return the point-wise exponent of each element
    • m = d:pexp()
  • Return the point-wise logarithm of each element
    • m = d:plog()
  • Return the point-wise modulus of each element (d by c)
    • m = d:pmod(c)
  • Return the point-wise multiplication of each element (d and c)
    • m = d:pmul(c)
  • Return each matrix element to the specified exponent
    • m = d:ppow(2)
  • Return the point-wise remainder of each element (d by c)
    • m = d:prem(c)
  • Return the point-wise square root of each element
    • m = d:psqrt()
  • Return the point-wise trigonometric function result of each matrix element
    • m = d:psin()
    • m = d:pcos()
    • m = d:ptan()
    • m = d:pasin()
    • m = d:pacos()
    • m = d:patan()
    • m = d:psinh()
    • m = d:pcosh()
    • m = d:ptanh()

Comparison

  • Return a matrix of 1's and 0's for the less-than comparison (d < e, where e is a matrix or a number) 
    • m = d:less(e)
  • Return a matrix of 1's and 0's for the less-than or equal to comparison (d <= e, where e is a matrix or a number)
    • m = d:lessOrEqual(e)
  • Return a matrix of 1's and 0's for the greater-than comparison (d > e, where e is a matrix or a number)
    • m = d:greater(e)
  • Return a matrix of 1's and 0's for the greater-than or equal to comparison (d >= e, where e is a matrix or a number)
    • m = d:greaterOrEqual(e)
  • Return a matrix of 1's, -1's and 0's denoting the sign of each matrix element
    • m = d:sign()

Indexing

  • local var = d[1][2];
  • ans = d.at(1,2);

Operators

  • Equality comparison (==)
  • Inequality comparison (!=)
  • Addition (+)
    • Including the addition of matrices and scalars
  • Subtraction (-)
    • Including the subtraction of matrices and scalars, and negation
  • Multiplication (*)
    • Including multiplication of matrices and vectors, and scalars
  • Division of a matrix and a scalar (/)
  • Modulus (%)
    • Including the modulus of matrices and scalars

Color

As was mentioned in other guides, the color tools can be used to generate a color that can be assigned to style elements in a document.

  • Specify a color using its red, green, and blue value
    • elementName.Style.ForegroundColor = color.rgb(10,10,10);
  • Specify a color using its red, green, blue, alpha
    • elementName.Style.BackgroundColor = color.rgba(10,10,10,10);
  • Specify a color using its X11 color name
    • elementName.Style.ForegroundColor = color.lightSlateGray; 

Constructors 

  • Create a vector from a one-dimensional Lua table
    • d = colors({color.blue, color.red, color.rgb(50, 50, 20)});
  • Create a vector using a delegate to initialize the elements
    • d = colors(3, function (i) return color.rgb(64 * i, 0, 0); end);
  • Create a vector with all elements initialized to the given value
    • d = colors(3, color.blue);
  • Create a vector with all elements initialized to transparent
    • d = colors(3);
  • Create a dense vector from a one-dimensional Lua table
    • d = colors.dense({color.blue, color.magenta, color.green});
  • Create a dense vector using a delegate to initialize the elements
    • d = colors.dense(3, function (i) return color.rgb(64*i, 0, 20); end);
  • Create a dense vector with all elements initialized to the given value
    • d = colors.dense(3, color.blue);
  • Create a dense vector with all elements initialized to zero
    • d = colors.dense(3);

Subvectors

  • Return the color subvector starting at the specified index
    • v = d:subvector(3)
  • Return the color subvector starting at the specified index and having the given length
    • v = d:subvector(3, 2)

Miscellaneous

  • Return number of color vector elements
    • n = d.count
  • Return the red component of a color
    • n = color.redComponent(d)
  • Return the green component of a color
    • n = color.greenComponent(d)
  • Return the blue component of a color 
    • n = color.blueComponent(d)
  • Return the alpha component of a color
    • n = color.alphaComponent(d)
  • Set the value at the specified index
    • d:at(1, color.blue)
  • Clone a color vector
    • v = d:clone()

Indexing

  • local n = colorVectorName[1];
  • ans = myColorVector.at(1);

Scripting Reference

Properties, methods, and events for document elements that can be manipulated from script. 

Shared Members

These members are shared by all elements that are accessible using Lua.

Properties

  • Name: local elementName = element.Name;

  • Parent: local parent = element.Parent

  • ReferenceString: local ref = element.ReferenceString;

  • Style:

    • ForegroundColor

      • elementName.Style.ForegroundColor = color.blue;

      • styleName.ForegroundColor = color.white;

    • BackgroundColor

      • elementName.Style.BackgroundColor = color.rgb(15, 125, 64);

      • styleName.BackgroundColor = color.red;

    • MarginLeft, MarginRight, MarginTop, MarginBottom

      • elementName.Style.MarginLeft = 0.5;

      • styleName.MarginRight = 20;

    • Bold, Italic, Underline

      • elementName.Style.Bold = true;

      • styleName.Italic = false;

    • Visibility (visible, hidden, collapsed)

      • elementName.Style.Visibility = "collapsed";

      • if elementName.Style.Visibility == "Collapsed" then...

    • Subscript, Superscript

      • elementName.Style.Subscript = true;

    • TextAlignment (left, right, center)

      • elementName.Style.TextAlignment = "right"

    • FontSize

      • elementName.Style.FontSize = 2;

      • styleName.FontSize = 0.8;

Accelerometer

Properties

  • Value (vector)

    • local accelData = myAccelerometer.Value;

  • X

    • local xValue = myAccelerometer.X;

  • Y

    • local yValue = myAccelerometer.Y;

  • Z

    • local zValue = myAccelerometer.Z;

  • Reorient

    • myAccelerometer.Reorient = true;

Events

  • onValueChanged

    • Inherent vector value

  • onActivePageChanged

    • Inherent variable active

      • if active then ...

Methods

  • Start: myAccelerometer:Start()

  • Stop: myAccelerometer:Stop()

Button

Properties

  • AlternateText

    • local altText = myButton.AlternateText;

    • myButton.AlternateText = "This is a button.";

  • Text

    • local butText = myButton.Text;

    • myButton.Text = "Button";

Methods

  • Click: myButton:Click();

Events

  • onClick

Client

Properties

  • Uri

    • clientName.Uri = "tcpip://192.168.0.11:5020"

Events

  • onConnected

  • onDisconnected

  • onReceive

Device

Properties

  • CurrentOrientation

    • if application.device.CurrentOrientation == enum.DeviceOrientation.Portrait then...

    • if application.device.CurrentOrientation == enum.DeviceOrientation.Landscape then...

    • if application.device.CurrentOrientation == enum.DeviceRotation.Rotated0 then...

    • if application.device.CurrentOrientation == enum.DeviceRotation.Rotated90 then...

    • if application.device.CurrentOrientation == enum.DeviceRotation.Rotated180 then...

    • if application.device.CurrentOrientation == enum.DeviceRotation.Rotated270 then...

  • IsNetworkAvailable

    • if application.device.IsNetworkAvailable then...

  • IsTablet

    • if application.device.IsTablet then...

Document

Properties

  • Title

    • myDocument.Title = "This is the name of the document";

    • local docTitle = myDocument.Title;

Footer

Properties

  • Level: local footLevel = theFooter.Level;

  • Title

    • theFooter.Title = "This is the footer";

    • local footTitle = theFooter.Title;

Gyroscope

Properties

  • Value (vector)

    • local gyroData = myGyro.Value;

  • X

    • local xValue = myGyro.X;

  • Y

    • local yValue = myGyro.Y;

  • Z

    • local zValue = myGyro.Z;

  • Reorient

    • myGyro.Reorient = true;

Events

  • onValueChanged

    • Inherent vector value

  • onActivePageChanged

    • Inherent variable active

      • if active then ...

Methods

  • Start: myGyro:Start()

  • Stop: myGyro:Stop()

Header

Properties

  • Level: local headLevel = theHeader.Level;

  • Title

    • theHeader.Title = "This is the header";

    • local headTitle = theHeader.Title;

Fields

  • References: local refs = theHeader.References;

Image

Properties

  • AlternateText

    • local altText = myImage.AlternateText;

    • myImage.AlternateText = "This is an image.";

  • ImageSource

    • local image = myImage.ImageSource;

    • myImage.ImageSource = "images/image1.png";

Location

Properties

  • Value (vector)

    • local locData = myLocation.Value;

  • Latitude

    • local latValue = myLocation.Latitude;

  • Longitude

    • local longValue = myLocation.Longitude;

  • Altitude

    • local altValue = myLocation.Altitude;

  • Speed

    • local speedValue = myLocation.Speed;

  • Bearing

    • local bearValue = myLocation.Bearing;

  • Timestamp

    • local timeValue = myLocation.Timestamp;

Events

  • onValueChanged

    • Inherent vector value

  • onActivePageChanged

    • Inherent variable active

      • if active then ...

Methods

  • Start: myLocation:Start()

  • Stop: myLocation:Stop()

Magnetometer

Properties

  • Value (vector)

    • local magData = myMagnetometer.Value;

  • X

    • local xValue = myMagnetometer.X;

  • Y

    • local yValue = myMagnetometer.Y;

  • Z

    • local zValue = myMagnetometer.Z;

  • Reorient

    • myMagnetometer.Reorient = true;

Events

  • onValueChanged

    • Inherent vector value

  • onActivePageChanged

    • Inherent variable active

      • if active then ...

Methods

  • Start: myMagnetometer:Start()

  • Stop: myMagnetometer:Stop()

Paragraph (p)

Properties

  • FormattedText

    • myParagraph.FormattedText = "Here is a paragraph";

    • local pText = myParagraph.FormattedText;

  • Text

    • myParagraph.Text = "Here is text without formatting";

    • local pText = myParagraph.Text;

Plot

Properties

  • Axis Minimum

    • local myMin = plotName.YAxis.Min;

  • Axis Maximum

    • local myMax = plotName.YAxis.Max;

  • Scaling Mode

    • local xScaling = plotName.XAxis.Scaling;

    • plotName.YAxis.Scaling = "growAndShrink"

  • Series Capacity

    • local myCap = plotName.seriesName.Points.Capacity;

  • Series Count

    • local myCount = plotName.seriesName.Points.Count;

  • Draw Mode

    • plotName.seriesName.DrawMode = enum.DrawMode.RadialFill;

  • Visibility

    • plotName.seriesName.Visible = true

Methods

  • Axis Reset to Defaults: plotName.XAxis:SetDefaults();

  • Axis Range: plotName.YAxis:SetRange(y1, y2)

  • Add Point: plotName.seriesName:Add(x, y)

    • Add point without defining series: plotName.Series[1]:Add(x,y)

  • Add nx2 Matrix: plotName.seriesName:Add(matrixName)

  • Clear Series: plotName.seriesName:Clear()

  • Plot Reset to Defaults: plotName:Reset()

Section

Properties

  • Level: local secLevel = theSection.Level;

  • Title

    • theSection.Title = "This is a section";

    • local secTitle = theSection.Title;

Simulation

For the properties of simulation elements refer to Simulation Properties. 

Properties

  • Time

    • local simTime = mySim.Time

  • Duration

    • local simDuration = mySim.Duration

  • Period

    • local simPeriod = mySim.Period

  • Running (onStateChanged)

    • local checkState = mySim.Running

  • Paused (onStateChanged)

    • local checkState = mySim.Paused

  • Stopped (onStateChanged)

    • local checkState = mySim.Stopped

Events

  • onUpdate

  • onDuration

  • onActivePageChanged

    • Inherent variable active

      • if active then ...

  • onStateChanged

    • variable state

      • if state == mySim.Running then ...

      • if state == mySim.Paused then ...

      • if state == mySim.Stopped then ...

Methods

  • Start: mySim:Start()

  • Stop: mySim:Stop()

  • Pause: mySim:Pause()

  • Resume: mySim:Play()

  • IsRunning: local trueFalse = mySim:IsRunning()

  • IsPaused: local checkPaused = mySim:IsPaused()

  • IsStopped: local stopped = mySim:IsStopped()

Slider

Properties

  • InitialValue

    • mySlider.InitialValue = 5.0;

    • local initVal = mySlider.InitialValue;

  • MaxValue

    • mySlider.MaxValue = 10.0;

    • local maxVal = mySlider.MaxValue;

  • MinValue

    • mySlider.MinValue = 0.0;

    • local minVal = mySlider.MinValue;

  • Value

    • mySlider.Value = 3.0;

    • local slideVal = mySlider.Value;

Fields

  • DefaultMaxValue: local defaultMax = mySlider.DefaultMaxValue;

  • DefaultMinValue: local defaultMin = mySlider.DefaultMinValue;

  • DefaultValue: local defaultVal = mySlider.DefaultValue;

Events

  • onValueChanged

    • Inherent variable value

Table

Properties

  • ColumnWidths

    • myTable.ColumnWidths = 0.5;

    • local colWidth = myTable.ColumnWidths;

  • GridLines

    • myTable.GridLines = true;

    • local gridLines = myTable.GridLines;

  • HasHeaderRow: local myTable.HasHeaderRow;

TableData

Properties

  • ColumnSpan

    • myTable.ColumnSpan = 2;

    • local colSpan = myTable.ColumnSpan;

  • RowSpan

    • myTable.RowSpan = 3;

    • local rowSpan = myTable.RowSpan;

TableRow

Properties

  • NumberOfColumns: local colNum = myRow.NumberOfColumns;

TextField/TextInput

Properties

  • PlaceholderText

    • myField.PlaceholderText = "Enter text here...";

    • local phText = myInput.PlaceholderText;

  • Text

    • myInput.Text = "This is text that was input";

    • local inText = myInput.Text;

  • Spelling

Events

  • OnTextChanged

Toggle

Properties

  • Value

    • myToggle.Value = false;

    • local togVal = myToggle.Value;

Methods

  • Toggle: myToggle:Toggle();

Events

  • onValueChanged

Video

Properties

  • Loop

    • myVideo.Loop = true

  • Source

    • myVideo.Source = "resources/newVideo.mp4"

  • Controls Enabled

    • myVideo.ControlsEnabled = false

Methods

  • Play: myVideo:Play()

  • Pause: myVideo:Pause()

  • Stop: myVideo:Stop()

  • SeekToTime: myVideo:SeekToTime(34)

  • SeekToPercent: myVideo:SeekToPercent(0.4)

Simulation Element Properties

Sources

Constant

  • Value

    • simName.solverName.constantBlockName.Value = vector({num})

Sine/Square/Triangle/Sawtooth/signalGenerator

  • Amplitude

    • simName.solverName.blockName.Amplitude = vector({num})

  • Bias

    • simName.solverName.blockName.Bias = vector({num})

  • Frequency

    • simName.solverName.blockName.Frequency = vector({num})

  • Phase

    • simName.solverName.blockName.Phase = vector({num})

Step

  • Initial

    • simName.solverName.stepName.InitialValue = vector({num})

  • Final

    • simName.solverName.stepName.FinalValue = vector({num})

  • Time

    • simName.solverName.stepName.Time = vector({num})

Ramp

  • Amplitude

    • simName.solverName.rampName.Amplitude = vector({num})

  • Bias

    • simName.solverName.rampName.Bias = vector({num})

 

Models

Transfer Function

  • Numerator

    • simName.solverName.transferFunctionName.Numerator = vector({num})

  • Denominator

    • simName.solverName.transferFunctionName.Denominator = vector({num1, num2})

State Space

  • A, B, C, D

    • simName.solverName.stateSpaceName.A = matrix({{num1, num2}, {num3, num4})

 

Other

Saturation

  • Minimum

    • simName.solverName.saturationName.Mininum = vector({num})

  • Maximum

    • simName.solverName.saturationName.Maximum = vector({num})

Gain

  • Value

    • simName.solverName.gainName.Value = vector({num})

Switch

  • Selection

    • simName.solverName.switchName.Selection = vector({num})