Javascript Guide
chevron down
 

Javascript Guide

Overview

The application logic written in JavaScript (.js) files, and can interact with the user interface using document object events and functions. JavaScript running on the device uses the Device API.

import document from "document";

let img = document.getElementById("image");
img.href = "another-image.jpg";

Interacting with Elements

To manipulate or interact with an element in JavaScript, you first need to assign an id or class to it.

<svg>
  <text id="demo">Hello!</text>
  <text class="red">Red Text</text>
  <text class="red">Also Red Text</text>
</svg>

Use the document object to get a reference to the elements, then manipulate them.

getElementById()

For example, to change the text inside a <text> element by its id:

import document from "document";

let demo = document.getElementById("demo");
demo.text = "Hello World!";

You can also use a parent element to get one of it's child elements:

<svg>
  <svg id="demoparent">
    <text id="demochild" />
  </svg>
</svg>
import document from "document";

let parent = document.getElementById("demoparent");
let demo = parent.getElementById("demochild");
demo.text = "Hello World!";

getElementsByClassName()

To manipulate multiple elements, you also can get a reference by using a common class name. This method will return an array of elements which match the specified class name.

import document from "document";

let elements = document.getElementsByClassName("red");
elements.forEach(function(element) {
  element.text = "Hey Red!";
});

getElementsByTagName()

To manipulate multiple elements, you also can get a reference by using their tag name. This method will return an array of elements which match the specified tag name.

import document from "document";

let elements = document.getElementsByTagName("circle");
elements.forEach(function(element) {
  element.style.fill = "blue";
});

Element Styling

Once you have a reference to an element, you can change its .style properties.

import document from "document";

let demo = document.getElementById("demo");
demo.style.fill = "red";
demo.style.fontSize = 20;
demo.style.fontFamily = "System-Regular";

Move an Element

You can reposition an object by changing its x and y coordinates, but you can only use pixel coordinates, you cannot use percentage values e.g. 100%.

import document from "document";

let demo = document.getElementById("demo");
demo.x = 42;
demo.y = 90;

Resize an Element

You can resize an object by changing its width and height properties, but you can only use pixel sizes, you cannot use percentage values e.g. 100%.

import document from "document";

let demo = document.getElementById("demo");
demo.width = 348;
demo.height = 250;

Layer Stacking Order (z-index)

By default, elements are rendered bottom upwards, based on the order in which they appear within the .gui file. You can dynamically affect the stacking order of elements, by changing the .layer property. Elements with a higher layer value will appear on top of elements with an undefined or lower layer value. This is similar to the behavior of z-index in CSS.

import document from "document";

let demo = document.getElementById("demo");
demo.layer = 2;

Hiding/Showing an Element

import document from "document";

let demo = document.getElementById("demo");
demo.style.display = "none";
demo.style.display = "inline";

// Toggle Show/Hide
function toggle(ele) {
  ele.style.display = (ele.style.display === "inline") ? "none" : "inline";
}

toggle(demo); // hidden
toggle(demo); // visible

You can also use the visibility attribute:

import document from "document";

let demo = document.getElementById("demo");
demo.style.visibility = "hidden";  // hidden
demo.style.visibility = "visible"; // visible

Note:

  • display can be changed from inline to none to hide an element. e.g. demo.style.display = "none";
  • Elements cannot be programmatically created, they must exist within the .gui file when the application is launched.

Events

Many UI elements can generate events, for example when the user taps on it. To generate events, you will need to set the pointer-events property to visible within the .gui file.

<svg fill="black">
  <rect id="myRect" pointer-events="visible" />
</svg>

Click Event

You can attach a handler to the onclick event for any elements which have pointer-events="visible". If you're using one of the button type elements, you should use the activate event instead.

import document from "document";

let myRect = document.getElementById("myRect");

myRect.onclick = function(e) {
  console.log("click");
}

Activate Event

You can attach a handler to the onactivate event for button elements (square-button, combo-button etc). Buttons may exhibit behavior where the raw click event is not desirable, for example the button may not be enabled.

Buttons don't need the pointer-events="visible" property added in order to raise events.

import document from "document";

let mybutton = document.getElementById("mybutton");

mybutton.onactivate = function(e) {
  console.log("click");
}

Enable/Disable

To toggle the state of the enabled/disabled state of a button, set the enabled property to either true (enabled) or false (disabled).

import document from "document";

let mybutton = document.getElementById("mybutton");
mybutton.enabled = false; // disabled
mybutton.enabled = true;  // enabled

Touch Events

You can attach a handler to the onmouseup, onmousedown and onmousemove events. These occur when the display is touched. Each event callback includes the screenX and screenY coordinates for any element which is visible for pointer events (pointer-events="visible").

<svg>
  <rect id="myButton" width="100%" height="100%"
        fill="red" pointer-events="visible" />
</svg>
import document from "document";

let myButton = document.getElementById("myButton");

myButton.onmousemove = function(evt) {
  console.log("Mouse moved: " + evt.screenX + ' ' + evt.screenY);
}

See the SVG 1.1 specification for more information on the pointer-events property.

Using the Physical Buttons

The document object emits keypress events when the user presses one of the physical buttons. Long press button events are reserved for system use only.

import document from "document";

document.onkeypress = function(e) {
  console.log("Key pressed: " + e.key);
}

The possible values for e.key are down, up, and back.

Triggering Animations

JavaScript can be used to trigger animations on the instance of a Template Symbol using elementinstance.animate("EVENT-NAME").

For more information see JavaScript Animations in the Animations Guide.

JavaScript Animations

The requestAnimationFrame() method can be used to perform frame based animations in JavaScript. The method takes a single callback function as an argument which is invoked before the screen is repainted.

function callback(timestamp) {
  // Perform animation frame logic here

  // Request next frame
  requestAnimationFrame(callback);
}

requestAnimationFrame(callback);

The animation frame requests are only invoked while the display is on, so a developer does not need to perform additional logic to optimize for changes in the display state.