Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The following table lists keywords and The following table lists keywords and statements that can be used in a script for better control flow.

what if does not match any cases

Name

Description

ifelse

The if statement executes some specified instructions if the condition is true. Otherwise, the else statement can be used to execute a different set of instructions. else if can be used to specify an alternative condition with different instructions. Once an if or else if statement is executed, any following else if statements will not be executed.

while

A while loop will repeatedly execute until the condition expression becomes false.

dowhile

The do statement allows you to execute the contents of a while loop at least once before the condition is evaluated. If the condition is true, the loop will repeat as usual until the while condition becomes false.

for

A for loop repeats until a specified condition becomes false. Below is the standard syntax used by a for loop:

Code Block
languagejs
for (<initialExpression>; <conditionExpression>; <incrementExpression>) {
    // instruction code
}

A for loop can also be used to iterate over arrays and objects, as explained below.

break

Terminates a switch statement, a while loop, or a for loop completely. The break statement prevents the execution of the following cases in a switch statement. Adding a break statement to each case is good practice.

continue

The continue statement terminates the execution of the current iteration in a loop and then executes the next iteration. Unlike break, this statement does not terminate the loop completely.

switchcase

The switch statement lets you compare an input value to the value of each case. If matched, the instruction code for that case is executed. Otherwise, the default instruction code is executed. Each case statement should usually be followed by a break statement.

default

The default statement specified

something that should happen

in a switch statement

regardless of the

case. A break statement is not required. Note that if a case is matched and that case does not contain a break statement, then both the case and the default will come into effect. If a matched case does have a break statement, then the default will be ignored.

function

A function is a block of code designed to perform a particular task. Functions can take in a set of arguments and can return a value. Functions are one of the primary methods for organizing and re-using code.

return

Ends the function execution, and the function will return the specified value to the caller.

arguments

Can be used within a function to get a list of values that were passed into the function call.

trycatch

The try statement lets you execute a block of code which might fail. If it does fail, you can specify what to do in the catch block. You can also reference the exception from the try block and handle it in a custom way.

throw

Throws an Error object, which terminates the script with a popup error. This is typically used within a try block so that different issues can be handled without immediately terminating the script.

Examples for ifelse and else if:

In this example, a notification saying “boolTag is true” will be displayed if the tag’s value is true.

...

In the example below, if tag “A” equals 1, we assign 100 to tag “B”. If “A” equals 2, we assign 200 to “B”. Otherwise, we assign 500 to “B”.

Code Block
languagejs
var value = tag.read("A");
if (value == 1) {
    tag.write("B", 100);
} else if (value == 2) {
    tag.write("B", 200);
} else {
    tag.write("B", 500);
}

Note that the conditions for if and else if conditions must be enclosed in parentheses.

Examples forwhile:

The tag "A" will be incremented from 0 to 100 over the course of A while loop is like an if statement that keeps executing the specified code until the condition becomes false.

In the example below, the tag "A" will be incremented from 0 to 100 over the course of about one second:

Code Block
languagejs
var val = 0;
while (val <= 100) {
	tag.write("A", val);
	val = val + 1;
	thread.msleep(10);
}

Example for dowhile:

The tag “boolTag” will be toggled A do while loop is a while loop that always executes the specified code at least once. If the tag “doLoop” is true after one second, “boolTag” will

This can be useful for buttons that perform some looping action while being held down. Even if the button is immediately released, the action will be performed at least once.

When the script below is executed, the tag “boolTag” will be toggled at least once. If the tag “doLoop” is true after one second, “boolTag” will continue to toggle once per second. Once “doLoop” becomes false, the toggling will stop and the script will end.

Code Block
do {
    tag.write("boolTag", !tag.read("boolTag"));
    thread.sleep(1);
} while (tag.read("doLoop"));

Examples for for

A for loop lets you provide 3 expressions that define the In practice, the script above might be tied to a button’s “On Press” action. Then, for the “On Release” action, you would just need to set the “doLoop” tag to false:

Code Block
tag.write("doLoop", false);

This would cause the while loop in the “On Press” script to end.

Examples for for

A for loop lets you provide 3 expressions that define the behavior of the loop.

  • The first expression will be run once before the loop first executes. Typically, this is used to initialize a counter variable like i or j.

  • The second expression is a condition that will be checked before each execution of the loop. If the condition is false, the loop will not execute, and the for loop will end. TypicallyOften, this is used to check if the counter variable has reached some value.

  • The third expression is run at the end of each execution of the loop. Typically, this is used to increment the counter variable.

In this example, the initial value of i is 0. When i is less than or equal to 100, i will increment by 1 and store the result in the tag “FOR_VAL” “myTag” every iteration until i equals 100. Once i equals 100, the for loop will execute one more time, then end.

Code Block
languagejs
for (var i = 0; i <= 100; i++) {
	tag.write("FOR_VALmyTag", i)
	thread.msleep(100)
}

Looping Over Arrays

A for loop can also be used to iterate through arrays using the array index.

...

Note: the first element in an array uses index 0. The last element will use the index array.length - 1.

Code Block
// Define an array
var myArray = [
    "val1",
    "val2",
    "val3"
]

// Get the indices
for (var index in myArray) {
	notification.send(index);
} // 0, 1, 2

// Get the values
for (var index in myArray) {
	var value = myArray[index];
    notification.send(value);
} // val1, val2, val3

Looping Over Objects

A for loop can also be used to iterate through objects using keys.

Code Block
// Define an object
var myObject = {
  "key1": "val1",
  "key2": "val2",
  "key3": "val3"
}

// Get the keys
for (var key in myObject) {
    notification.send(key);
} // key1, key2, key3

// Get the values
for (var key in myObject) {
    var value = myObject[key];
    notification.send(value);
} // val1, val2, val3

Example forcontinue

The continue keyword can be used in a while or for loop to move to the next iteration without breaking out of the loop. This can be used to skip specific items.

In this example, a notification will be shown for each number from 0 to 9, except for 5:

Code Block
languagejs
for (var i = 0; i < 10; i++) {
    if (i == 5) {
        continue;
    }
    notification.send(i);
} // 0, 1, 2, 3, 4, 6, 7, 8, 9

Examples for switchcase, break, and default

In this example, when the script executes, the tag "REPLY" will be assigned the string value "Hello, <name>" by default. If the name entered is empty, the “REPLY” tag will be set to "Could not load name." instead.

...

languagejs

...

Using a while loop instead:

Code Block
var i = 0;
while (i < 10) {
    if (i == 5) {
        i++;  tag.write("REPLY", "Could not load name.")
  // Don't forget to increment the counter before continuing!
     break;   continue;
 default:   }
     tagnotification.write("REPLY", "Hello, " + String(name) + ".");
}

The break statement is used to break out of the switch statement and prevent any other cases from executing. If break is not used, then multiple cases may be executed. This can lead to unexpected behavior, so in most cases, each case should have a break statement.

...

This example defines a function called multiply which takes in two arguments a and b, then returns the product a * b. The function is then called in order to set the value of x to the product of 4 and 3.

Code Block
languagejs
function multiply(a, b) {
	return a * b;
}
var x = multiply(4, 3); // x is now equal to 12

Optional Arguments

Functions do not need to have any arguments. For example, here is a function that outputs a message, waits for 3 seconds, then exits the project.

Code Block
function fancyExit() {
    notification.send("Closing the project in 3 seconds..send(i);
    i++;
} // 0, 1, 2, 3, 4, 6, 7, 8, 9

Examples for switchcase, break, and default

In this example, when the script executes, we will send the notification "Hello, <name>" by default. If the name value is empty, we send "Could not load name." instead. Finally, if the name is "admin", then the admin console page will be opened.

The script below could be bound to the “Value Changed” property for the “name” tag.

Code Block
languagejs
var name = tag.read("name");
switch (name) {
    case false:
        notification.send("Could not load name.");
    thread.sleep(3);    break;
    case "admin":
        notification.send("Loading admin console.");
      system  page.exitopen("adminConsole");
}

Function calls are not required to have the same number of arguments as the function definition. Any missing arguments will be set to undefined. This can be used to make certain arguments optional by providing a default value.

In the example below, the function multiplyDefault returns a * b if both a and b are specified. If b is not specified, the function instead returns a * 10.

Code Block
function multiplyDefault(a, b) {
        break;
    default:
       if (b === undefined) {
        b = 10;
    }
	return a * b;
}
multiplyDefault(2, 3); // 6
multiplyDefault(2); // 20

The arguments keyword

There is also a special keyword arguments, which gives an array containing the values passed into the function call. This allows functions to use a variable number of arguments.

Code Block
function returnFirstArg( notification.send("Hello, " + String(name) + ".");
}

The break statement is used to break out of the switch statement and prevent any other cases from executing. If break is not used, then multiple cases (including the default) may be executed. This can lead to unexpected behavior, so usually, each case should have a break statement.

Examples for function,return, and arguments

This example defines a function called multiply which takes in two arguments a and b, then returns the product a * b. The function is then used to set the value of x.

Code Block
languagejs
function multiply(a, b) {
	return arguments[0] a * b;
}
returnFirstExtraArg("a", "b", "c")
var x = multiply(4, 3); // "a"

You can also use arguments in a function definition, in which case arguments will only include values not covered by the named arguments. This is useful when you know that the first few arguments are required, but any additional arguments are optional.

Code Block
function returnFirstExtraArg(x, y, arguments) {
	return arguments[0];
}
returnFirstExtraArg("a", "b", "c"); // "c"

Examples for trycatch and throw

A trycatch statement can be used to gracefully handle situations that would normally cause the script to terminate. If the code in the try block fails, this error is returned to the catch block, which either makes use of or ignores the error.

In the catch statement, you must give a name for the error from the try block. It is common practice to use the name error.

The throw statement can be used to manually create an error. This is mainly useful when used within a try block, since the custom Error object can then be used by the catch block.

...

 x is now equal to 12

Optional Arguments

Functions do not need to have any arguments. For example, here is a function that outputs a message, waits for 3 seconds, then exits the project.

Code Block
function fancyExit() {
    notification.send("Closing the project in 3 seconds...");
    thread.sleep(3);
    system.exit();
}

Function calls are not required to have the same number of arguments as the function definition. Any missing arguments will be set to undefined. This can be used to set default values and optional arguments.

In the example below, the function multiplyDefault returns a * b if both a and b are specified. If b is not specified, the function instead returns a * 10.

Code Block
function multiplyDefault(a, b) {
    if (b === undefined) {
        b = 10;
    }
	return a * b;
}
multiplyDefault(2, 3); // 6
multiplyDefault(2); // 20

Note: when checking if a value is undefined, you should use === instead of ==. This is because undefined, 0, and "" all evaluate to false when using the == operator. So for example, 0 == undefined will return true.

The arguments keyword

There is also a special arguments keyword, which returns an array containing the values which were passed into the function. This allows functions to use a variable number of arguments.

For example, we can access the nth argument which was passed to the function:

Code Block
function returnThirdArg() {
	return arguments[2];
}
returnThirdArg("a", "b", "c"); // "c"

You can also use arguments in a function definition, in which case arguments will not include any of the named arguments. This is useful when you have a fixed number of required arguments and a variable number of optional arguments.

Code Block
function returnFirstExtraArg(x, y, z, arguments) {
	return arguments[0];
}
returnFirstExtraArg("a", "b", "c", "d"); // "d"

Examples for trycatch and throw

A trycatch statement can be used to gracefully handle situations that would normally cause the script to terminate. If the code in the try block fails, this error is returned to the catch block, which can then use (or ignore) the error.

In the catch statement, you must give a name for the error from the try block. It is common practice to use the name error.

In the example below, the script is able to continue executing even though the function thisFunctionDoesNotExist does not exist. Without the trycatch block, the script would instead throw an error.

Code Block
try {
    thisFunctionDoesNotExist();
} catch (error) {
    // Do nothing
}
notification.send("Executing the rest of the script...");
// Perform more actions

Checking Whether a Tag is Loaded or Not

When a project first starts, some tags may not be loaded yet, in which case tag.read or tag.write will throw an error. Remote tags may take a few seconds to load, depending on the polling rate, communication method, and the size of the project.

The example script below would run on project startup and wait for a remote tag to load ( become readable). Once we know that the tag can be read, we can run the rest of our the startup actions (which might make use of depend on the tag being loaded).

Code Block
// Inside main startup script "Startup1"
var loading = true;
var waited = 0;
while (loading) {
	try {
		tag.read("remoteTag");
		loading = false;
	} catch (error) {
		if (waited > 10000) {
			throw Error('Could not load tag "remoteTag" after 10 seconds. Please check the connection and restart the project.');
		}
		thread.msleep(100);
		waited += 100;
	}
}
// Now do any other startup actions

...

 load tag "remoteTag" after 10 seconds. Please check the connection and restart the project.');
		}
		thread.msleep(100);
		waited += 100;
	}
}
// Now do any other startup actions

Checking an Error Code From a Tag

The throw statement can be used to manually create an error. This is typically used within a try block, so that the custom Error object can then be handled by a catch block.

The throw statement can also be used outside of a try block, in which case the entire script will terminate with an error. This can be useful for scripts that are expected to be called via system.importScript, or when you wish to immediately terminate a script.

The example below checks the value of an error code tag “errorCode” before attempting to turn a motor on using the tag “motorOn”. Depending on the error encountered (if any)code, the script will display a different notification. If there is a problem with tag.read or tag.write, this will also be handled using the notification instead of terminating the script.

Code Block
try {
    var errorCode = tag.read("errorCode");
    switch (errorCode) {
    	case 0:
    		tag.write("motorOn", true);
    		break;
    	case 1:
    		throw Error("Power Disconnected");
    		break;
    	case 2:
    		throw Error("Mechanical Failure")
    		break;
        case 3:
            throw Error("Invalid Operation Mode")
            break;
    	default:
    		throw Error("Unrecognized Error Code")
    }
} catch (error) {
	var errorString = "Could not turn on motor: "
    errorString += error.message;
    notification.send(errorString)
}

Built-In Functions for Script Importing and Execution

Canvas also provides built-in functions which allow you to utilize scripts from within other scripts.

Name

Description

system.importScript

Calls another script in the project directly by name. This pauses the calling script until the target script finishes executing. This can also be used to import functions and variables from other scripts.

system.runScript

When an external program is called directly, the caller will be in standby mode until the called program (the external program) ends its operation. However, if an external program is called using runScript(), the caller will not wait until the end of the called program. Both the caller and called program will be executed in parallelReturns the value of the last expression in the target script.

system.runScript

Runs another script immediately in a separate thread. Both the calling and the target script will be executed simultaneously.

Returns undefined.

Note: Up to 100 scripts can run at the same time. Additional scripts will display a warning and fail to run. Once the scripts finish executing, more can be run.

Examples forsystem.importScript and system.runScript

Both system.importScript and system.runScript can be used to execute scripts in the project from within another script. The difference is that importScript runs the script in the same thread, and runScript runs the script in a different thread.

To compare illustrate the two functionsdifference, consider these the scripts “A”, “B”, and “C” below:

Code Block
// A
thread.sleep(1);
notification.send("In A");
Code Block
// B
notification.send("In B");
thread.sleep(1);
notification.send("Stil in B")
Code Block
// C
notification.send("In C");

Running Scripts in Order

We can use system.importScript to execute the scripts in order, like so:

Code Block
system.importScript("A(1);
notification.send("Stil in B")
Code Block
// C
notification.send("In C");

Running Scripts in Order

We can use system.importScript to execute the scripts in order, like so:

Code Block
system.importScript("A");
system.importScript("B");
system.importScript("C");

The result would be:

  1. sleep for 1 second

  2. display “In A”

  3. display “In B”

  4. sleep for 1 second

  5. display “Still in B”

  6. display “In C”

With system.importScript, the calling script is paused until the target scripts finishes. If there is an error in the target script, the calling script will throw an error as well.

Running Scripts Immediately

Using system.runScript lets you run scripts in parallel. The target script will immediately begin running on another thread.

If we try calling the 3 scripts defined above using runScript

Code Block
system.runScript("A");
system.runScript("B");
system.importScriptrunScript("B");
system.importScript("C");

The result would be:

  1. sleep for 1 second

  2. display “In A”

  3. display “In B”

  4. sleep for 1 second

  5. display “Still in B”

  6. display “In C”

While the target script is running, the calling script is paused. If there is an error in the target script, the calling script will have an error as well.

Running Scripts Immediately

Scripts can also be run in parallel using system.runScript. This immediately begins running the script on another thread.

If we try calling the 3 scripts defined above using runScript

Code Block
system.runScript("A");
system.runScript("B");
system.runScript("C");

The result would be:

  1. display “In B”

  2. display “In C”

  3. sleep for 1 second

  4. display “In A”

  5. display “Still in B”

With runScript, as soon as the target script begins, the calling script resumes execution.

...

C");

The result will be:

  1. display “In B”

  2. display “In C”

  3. sleep for 1 second

  4. display “In A”

  5. display “Still in B”

With runScript, the calling script continues executing, and the target script begins shortly after.

Note that with runScript you cannot guarantee the order of execution. In this case, the order of steps 1 and 2 may be reversed, as well as steps 4 and 5.

Note: in general, running multiple script threads is slower than running multiple actions in a single script. This is because it takes time for the operating system to switch between threads.

Communicating between Script Threads

Currently, there is no way to directly pass values between script threads.

However, scripts can read and write tag values. This can be used as a simple way to send messages between scripts.

For example, consider the following scripts:

Code Block
// Event Loop, runs on startup
while (true) {
    if (tag.read("triggerTag")) {
        notification.send("The event was recognized!");
        tag.write("triggerTag", false);
    }
    thread.msleep(100);
}
Code Block
// Trigger script, runs on button press, page load, etc.
tag.write("triggerTag", true);

When the trigger script is executed, the event loop script will see the changed tag value and display a notification. Then it will set the trigger tag to false again so that future events can be processed.

Note that reading and writing to a tag using multiple loops can significantly reduce project performance. In general, you should avoid having more than one loop running at any given time.

Importing Functions and Variables

system.importScript can be used to import functions and variables from other scripts. In this example, we have a script called "myFunctionScript", which has a function fib that returns the Fibonacci sum:

...

We could then load the variable x from another script as followsshown below:

Code Block
system.importScript("myVariableScript");
notification.send(x); // 7

Getting a Return Value From a Script

system.importScript returns the value of the last expression in the target script.

Here is a simple example where the target script returns the value 12. This value is then used in the calling script.

Code Block
//targetScript
var x = 7;
x + 5;

...