--- title: "13.1.6 Internal Functions" canonical: "https://manual.cimon.com/space/CCANVAS/4341858305/13.1.6%20Internal%20Functions" format: markdown --- > đź“ť 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/](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](https://doc.qt.io/qt-5/qt.html#Key-enum) 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' ``` | *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](https://cimon.atlassian.net/wiki/spaces/CCANVAS/pages/4337401857/13.1.5+Keywords+Statements+and+Control+Flow#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](https://cimon.atlassian.net/wiki/spaces/CCANVAS/pages/4337401857/13.1.5+Keywords+Statements+and+Control+Flow#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](https://cimon.atlassian.net/wiki/spaces/CCANVAS/pages/4336812066/13.1.3+Program+Structure#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.