Canvas uses JavaScript ES5 for scripting. Nearly all objects and functions that are supported in ES5 are available. For a complete list of supported features, see the ES5 specification: https://262.ecma-international.org/5.1/.

Canvas does not support the use of console.log. Instead, it is recommended that you use notification.send or write the desired output to a string tag.

Canvas provides a set of utility functions and objects for interacting with the project and with the Xpanel device.

For example, the built-in datalog object includes the functions start, stop, and addRow. These can be accessed in a script to start a data log model, stop a model, or add a row to a model, respectively.

Below is a list of the built-in functions provided by Canvas.

alarm

Provides a way to interact with Gateway alarms.

Function Name

Description

Arguments

Returns

alarm.createAllCsv(enum storageType)

Creates a CSV file of all alarms in the specified location.

enum storageType: see the Storage section below.

undefined

alarm.createCsv(string label, Storage type)

Creates a CSV file of all alarms with the specified label in the specified location.

string label: the name of an alarm label to use as a filter.

Storage type: see the Storage section below.

undefined

Examples:

// Write an alarm CSV to the HMI's hard drive
alarm.createAllCsv(Storage.Local);

// Write a CSV to a USB drive. Only contains alarms with the label "myLabel"
alarm.createCsv("myLabel", Storage.Usb);

datalog

Provides a way to interact with Gateway data log models.

Function Name	Description	Arguments	Returns
`datalog.start(string modelName)`	Causes the specified logging model to begin logging.	string modelName: the name of the data log model to target.	`undefined`
`datalog.stop(string modelName)`	Causes the specified logging model to stop logging.	string modelName: the name of the data log model to target.	`undefined`
`datalog.addRow(string modelName)`	Adds a single row to the specified logging model.	string modelName: the name of the data log model to target.	`undefined`
`datalog.createCsv(string modelName, enum storageType)`	Creates a CSV file of the specified logging model in the specified location.	string modelName: the name of the data log model to target. enum storageType: see the Storage section below.	`undefined`
`datalog.createCsvForRange(string modelName, Date start, Date end, enum storageType)`	Creates a CSV file of the specified logging model, in the specified location, within some time bound.	string modelName: the name of the data log model to target. Date start: a JavaScript Date object specifying the beginning of the time range. Date stop: a JavaScript Date object specifying the end of the time range. enum storageType: see the Storage section below.	`undefined`

Examples:

// Enable the model, add one row of data, then disable the model again
datalog.start("myModel");
datalog.addRow("myModel");
datalog.stop("myModel");

// Store a CSV with all data for the model
datalog.createCsv("myModel", Storage.Local);

// Store a CSV with the past hour of data to an SD card
var current = new Date(Date.now());
var past = new Date(current);
past.setHours(past.getHours() - 1);
datalog.createCsvForRange("myModel", past, current, Storage.Sd);

keyboard

Allows for sending keyboard events and bringing up keyboard popups for inputting values.

Function Name

Description

Arguments

Returns

keyboard.sendKeyEvent(keyCode)

Simulates a keyboard press for integer code keyCode. See here for a list of supported key codes (provided in hexadecimal format). Note that certain key codes may not work on all platforms.

Text Field objects will receive key events sent by this function.

Example:

keyboard.sendKeyEvent(0x48); // H
keyboard.sendKeyEvent(0x45); // E
keyboard.sendKeyEvent(0x4c); // L
keyboard.sendKeyEvent(0x4c); // L
keyboard.sendKeyEvent(0x4f); // O
keyboard.sendKeyEvent(0x01000004); // Return
// 'H' 'E' 'L' 'L' 'O' <Return>

keyCode: a number indicating which key to simulate. May be either hexadecimal or decimal. For example,
keyboard.sendKeyCode(0x20)
is the same as
keyboard.sendKeyCode(0x32).

undefined

keyboard.launchKeypad(tagName, properties)

Creates a popup numeric keypad that will set a tag to the user input value. Only accepts valid floating-point numbers.

Note: This function does not wait for user input, nor does it return the entered value. The rest of the script will be executed immediately.

tagName: the name of the tag to set.

object properties (optional): an object specifying optional properties to be used for the popup. See the properties section below for details.

undefined

keyboard.launchKeyboard(tagName, properties)

Creates a popup keyboard that will set a tag to the user input value.

Note: This function does not wait for user input, nor does it return the entered value. The rest of the script will be executed immediately.

tagName: the name of the tag to set.

object properties (optional): an object specifying optional properties to be used for the popup. See the properties section below for details.

undefined

properties

For keyboard.launchKeypad and keyboard.launchKeyboard, the properties argument is a JavaScript object that supports the following properties:

Property	Description
header	Sets the header.
subheader	Sets the subheader.
x	Sets the x position on the screen.
y	Sets the y position on the screen.
format	Sets the initialized numeric format. Having a hexadecimal format enables the hexadecimal keys.
min	Sets the minimum value the keypad will accept.
max	Sets the maximum value the keypad will accept.

Examples:

// Open a numerical keypad to edit the value of "numericTag"
keyboard.launchKeypad("numericTag");

// Edit a numerical tag using custom display options
keyboard.launchKeypad("numericTag", {"x": 100, "y": 200, "format": "HH"});

// Open a text keyboard to edit a string tag
keyboard.launchKeyboard("stringTag");

// Edit a string tag with custom display options
keyboard.launchKeyboard("stringTag", {"header": "Setting OtherTag", "x": 100, "y": 200});

notification

Provides a way to interact with the notifications system.

Function Name

Description

Arguments

Returns

notification.send(string msg, int dismissInterval = -1)

Sends a popup notification to the screen using the specified string.

string msg: the string to display.

int dismissInterval (optional): the approximate number of seconds to wait before automatically dismissing the notification. A value of less than zero means to stay in the notification system indefinitely. Default -1.

0

Examples:

// Send a notification to the screen
notification.send("Hello.");

// Send a notification that automatically dismisses itself after 3 seconds
notification.send("Hello for a moment.", 3000);

page

Allows for manipulation of project pages and the current page.

Function Name	Description	Arguments	Returns
`page.open(string name)`	Opens the page with name name. Note: If the specified page is not a popup page, it will replace (close) the current page.	string name: the name of the page to open	`undefined`
`page.openIndex(number index)`	Opens the page with index index. Note: If the specified page is not a popup page, it will replace (close) the current page.	number index: the index of the page to open	`undefined`
`page.close(string name)`	Closes the page with name name. Note: With this function, it is possible to accidentally close all pages in the project. This function should be used primarily for popup pages.	string name: the name of the page to open	`undefined`
`page.closeIndex(number index)`	Closes the page with index index. Note: With this function, it is possible to accidentally close all pages in the project. This function should be used primarily for popup pages.	number index: the index of the page to open	`undefined`
`page.isOpen(string name)`	Returns whether a page with name name is open.	string name: the name of the page to open	`undefined`
`page.currentName()`	Gets the name of the currently opened page.	N/A	A string containing the name of the currently opened page.
`page.currentIndex()`	Gets the index of the currently-opened page.	N/A	A number containing the index of the currently opened page.

Examples:

// If the page "WarningPage" is currently open, open the page "WarningPopupPage"
// Otherwise, open the page with index 1
if (page.currentName() == "WarningPage") {
	page.open("WarningPopupPage");
} else {
	page.openIndex(1);
}

schedule

Provides a way to enable and disable schedules.

Function Name

Description

Arguments

Returns

schedule.isEnabled(string title)

Returns whether or not schedule title is enabled.

string title: the name of the schedule to check.

true if the schedule is enabled, otherwise false.

schedule.setEnable(string title, bool enable)

Enables schedule title if enable is true; otherwise turns schedule off.

string title: the name of the schedule to check.

bool enable: whether to enable (true) or disable (false) the specified schedule.

undefined

Examples:

// Toggle whether the schedule "mySchedule" is enabled
schedule.setEnable("mySchedule", !schedule.isEnabled("mySchedule"));

Storage

The Storage object allows you to specify a location for saving various data within scripts. Either the numerical value (0, 1, 2, 3) or the enum value (Storage.Invalid, Storage.Local, Storage.Usb, Storage.SdCard) may be used whenever a storageType argument is required.

Note that the specific file path depends on the script being used.

Constant	Value	Description
`Storage.Invalid`	0	Invalid storage type
`Storage.Local`	1	The root storage device
`Storage.Usb`	2	Removable storage device
`Storage.SdCard`	3	Removable memory card

Examples:

// Store an alarm CSV to the USB drive
alarm.createCsv("Level 1", Storage.Usb);

// Store an alarm CSV to the SD card
alarm.createCsv("Level 1", Storage.Sd);

// Store a data log CSV to the HMI
datalog.createCsv("model", Storage.Local);

system

Provides a way to interact with the runtime application.

Function Name	Description	Arguments	Returns
`system.importScript(string scriptName)`	Executes a script in the current project named scriptName on the current thread. Any variables and functions declared in the target script will become accessible in the calling script. Note: The calling script will not continue to execute until the target script finishes executing. For more details, see the Built-In Functions for Script Importing and Execution section.	string scriptName: the name of the script to execute.	The value of the last expression of the specified script. For example, if the external script “myScript“ contains the following: notification.send("In external script..."); 7; then `system.importScript("myScript");` would return `7`. This can be used to pass information from the target script to the calling script.
`system.runScript(scriptName)`	Executes a script named scriptName from the current project. Note: The target script will run on a separate thread. Execution of the calling script will immediately continue. The target script will not be able to access any variables defined in the calling script, and vice-versa. For more details, see the Built-In Functions for Script Importing and Execution section.	string scriptName: the name of the script to execute.	`undefined`
`system.openConfig()`	Opens the runtime config (3 touch) menu.	N/A	`undefined`
`system.openXpanelManager()`	Opens the Xpanel Control Center (desktop). Note: This function does nothing in the simulator.	N/A	`undefined`
`system.setLanguage(string language)`	Sets the language used by the runtime translation feature.	string language: the name of the language to use. This should be one of the column names defined in the Translation Editor window.	`undefined`
`system.login(string username, string password)`	Immediately logs in as the specified user for the runtime IAM feature. Note: Do not store user passwords using tags that can be accessed by other devices or by non-authorized users.	string username: the name of the IAM user to log in. string password: the password for the specified user. If the user does not have a password, you may omit this argument or use an empty string `""`.	`true` if the user was successfully logged in, `false` otherwise. Note: a return value of `false` typically indicates that the provided password was incorrect.
`system.openLoginWindow(properties)`	Opens the built-in dialog for logging in a user for the IAM system. Note: This function does not wait for user input, nor does it return whether the user was logged in. The rest of the script will be executed immediately.	object properties (optional): an object specifying optional properties to be used for the popup. See the properties section below for details.	`undefined`
`system.openAuthWindow(properties)`	Opens the built-in dialog for authenticating a user. The user will be required to re-enter their password. If no user is specified, the current user will be used instead. If no user is logged in, the function will return false. Note: This function blocks the event loop. The calling script will not continue executing until the dialog is closed.	object properties: an object specifying optional properties to be used for the popup. See the properties section below for details.	`true` if the user is successfully logged in, `false` otherwise.
`system.logout()`	Logs out the current user from the IAM system.	N/A	`undefined`
`system.hasPermission(string permission)`	Checks to see if the current user has the specified permission.	string permission: the name of the permission to check.	`true` if the current user has the specified permission, `false` if not.
`system.exit()`	Closes the current project and the runtime application. The gateway will also be closed if running on the same device.	N/A	`undefined`

properties

For system.openLoginWindow, the properties argument is a JavaScript object that supports the following properties:

Property	Description
listUsers	Sets whether the username input should be a combo box (`true`) or a text input box (`false`).

For openAuthWindow, the properties argument is a JavaScript object that supports the following properties:

Property	Description
username	Sets the desired user to authenticate. If no user is provided, the current user will be used. If no user is logged in, return false immediately.

Examples:

// Run a script in the same thread
system.importScript("someSequentialScript");

// Run a script in a different thread
system.runScript("someLoopingScript")

// Open the 3-touch config menu
system.openConfig();

// Set the translation language to Spanish
system.setLanguage("Spanish");

// Login as a user named "guest" that has no password
system.login("guest");

// Open the login window and show the list of users in the project
system.openLoginWindow({"listUsers": true});

// Open the authorization window and request the password for the user "myUser"
system.openAuthWindow({"username": "myUser"});

// Logout the current user
system.logout();

// Check if the current user has the "Admin" permission
if (system.hasPermission("Admin")) {
    tag.write("someImportantTag", true);
} else {
    notification.send("Error: insufficient permissions.");
}

// Exit the runtime and stop the project
system.exit();

tag

Allows for the manipulation of tags.

Function Name

Description

Arguments

Returns

tag.read(string name)

Gets the current value of the tag with name name.

string name: the name of the tag.

Note: tags in groups can be accessed using the forward slash character /. Example: "Outer Group/Inner Group/Tag Name"

The value of the tag. STRING tags return strings, BOOL tags return booleans, and all numeric tag types return numbers.

tag.write(string name, value)

Sets the value of the tag with name name to value.

string name: the name of the tag.

Note: tags in groups can be accessed using the forward slash character /. Example: "Outer Group/Inner Group/Tag Name"

value: the value to set the tag to. STRING tags expect strings, BOOL tags expect booleans, and all numeric tag types expect numbers.

undefined

Examples:

// Set the value of "MyTag" to be 20 more than the value of "MyOtherTag"
tag.write("MyTag", tag.read("MyOtherTag") + 20);

Note: See the Reading and Writing Tag Values section for more information.

thread

Pauses the script for a specified amount of time. Only affects the calling script’s thread.

Note: The functions provided by this class do not guarantee accuracy. The application may sleep longer than the desired time under heavy load conditions.

Function Name	Description	Arguments	Returns
`thread.msleep(number msecs)`	Suspends the current thread for msecs milliseconds.	number msecs: the number of milliseconds to sleep for.	`undefined`
`thread.sleep(number secs)`	Suspends the current thread for secs seconds.	number secs: the number of seconds to sleep for.	`undefined`

Examples:

// Check the value of a tag once per second
// If true, increment a different tag value
while (true) {
    if (tag.read("doIncrement")) {
        tag.write("mytag", tag.read("myTag") + 1);
    }
    thread.sleep(1);
}

// Gradually increase a tag value from 0 to 10 over the course of 1 second
var value = 0;
while (value < 10) {
    tag.write("myTag", value);
    value += 1;
    thread.msleep(100);
}

Rapidly writing tag values may reduce the performance, especially when using tags that are not local to the runtime.

13.1.6 Internal Functions

alarm

datalog

keyboard

properties

notification

page

schedule

Storage

system

properties

tag

thread