Piu JavaScript Reference

Copyright 2017-2023 Moddable Tech, Inc.
Revised: August 31, 2023

Piu is a user interface framework designed to run on microcontrollers. The programming interface to Piu is a JavaScript API of global constructors, functions, and objects that define the containment hierarchy, appearance, behavior, and flow of applications. This document provides details on the objects that define the Piu API and important related concepts.

• Inheritance Hierarchy
• Introduction to Important Concepts
  • Containment Hierarchy and Appearance
  • Behavior and Flow
• Global Properties
  • Built-in Properties
  • Adding Additional Properties
• Descriptions of Properties
  • Anchor
  • Color
  • Coordinates
  • Duration, Fraction, Interval, Loop, and Time
  • Font
  • Tiles
  • Variant, Variants, State, and States
• Piu Object Reference
  • Application Object
  • Behavior Object
  • Column Object
  • Container Object
  • Content Object
  • Die Object
  • Image Object
  • Label Object
  • Layout Object
  • Port Object
  • Row Object
  • Scroller Object
  • Shape Object
  • Skin Object
  • Sound Object
  • Style Object
  • Text Object
  • Texture Object
  • Timeline Object
  • Transition Object

Figure 1 summarizes the inheritance hierarchy for the objects described in this document.

Figure 1. Piu Inheritance Hierarchy

The basic relationship between these objects in the context of a Piu application is as follows:

• Graphical parts of the user interface are all content objects
• skin, style, and texture objects customize the look (colors, fonts, etc.) of content objects
• behavior objects are bound to content objects to handle events
• timeline and transition objects animate content objects

This section explains important concepts related to Piu applications and defines some of the terms used throughout the rest of this document.

The graphical user interface elements of Piu applications are composed of a hierarchy of content objects. The basic structure is as follows:

• The application object is the root of the containment hierarchy
• container objects are branches of the containment hierarchy
• content objects are leaves of the containment hierarchy

Applications use constructors to define content and container objects. These objects are attached to the containment hierarchy using the add, insert, and replace functions, and are removed from the containment hierarchy using the remove and replace functions. See Functions in the section Container Object for descriptions of these properties.

Contents that are not attached to the containment hierarchy are called unbound contents; contents attached to the containment hierarchy, bound contents. Only objects that are part of the containment hierarchy appear on screen.

Unbound contents do not participate in layout. They are neither measured nor fitted; consequently, their position and size are undefined and cannot be changed.

let content = new Content();
let before = content.position;	// undefined
application.add(content);
let after = content.position;	// {x: 160, y:120} (assuming the application is 320x240)

The coordinates of an object define implicit constraints on its position and size.

For example, centered content and contents whose sizes/position are dependent on their container's size/position cannot move.

// Cannot move
let centeredContent = new Content(null, {
	width: 10, height: 10
});
let dependentOnContainerContent = new Content(null, {
    top: 0, left: 0, bottom: 100, right: 100,
});

// Can move
let unconstrainedContent = new Content(null, {
    top: 0, left: 0, height: 100, width: 100
});

All contents have a measured width and measured height, which are the default width and height computed by the content itself. For example, the measured width of the following content object will be 100.

let sampleContent = new Content(null, {
	width: 100
});

The measured width of the following content will be 0, because the content has no default width.

let sampleContent = new Content(null, {
	left: 0, right: 0
});

The coordinates property of a content object reflect the content's measured size. This property can be changed at any time.

sampleContent.coordinates = {
	left: 0,
	width: 100,
	top: 0,
	height: 100
};

All contents also have a fitted width and fitted height, which are the effective width and height of the content computed by its container.

If both left and right coordinates are defined, the content stretches horizontally with its container, and the fitted width of the content depends on the fitted width of its container. Similarly, if both top and bottom coordinates are defined, the content stretches vertically with its container, and the fitted height of the content depends on the fitted height of its container. For example, the fitted width and fitted height of the sampleContent object here will both be 100.

let sampleContent = new Content(null, {
	left: 0, right: 0
});
let sampleContainer = new Container(null, {
	height: 100, width: 100,
	contents: [
		sampleContent
	]
});

If a left or right coordinate (but not both) is defined, or if neither left nor right is defined, the fitted width equals the measured width. Similarly, if a top or bottom coordinate (but not both) is defined, or if neither top nor bottom is defined, the fitted width equals the measured height. For example, the fitted width and fitted height of the sampleContent object here will both be 50.

let sampleContent = new Content(null, {
	left: 0, top: 0, width: 50, height: 50
});
let sampleContainer = new Container(null, {
	height: 100, width: 100,
	contents: [
		sampleContent
	]
});

The width and height properties of a content object reflect the content's fitted size. A content's measured width and height are available immediately after the content is created; the fitted width and height are not available until its onDisplaying event has been triggered.

let sampleContent = new Content(null, {
	left: 0, right: 0, top: 0, height: 50,
	Behavior: class extends Behavior {
		onCreate(content) {
			let measuredHeight = content.coordinates.height; // 50
			let measuredWidth = content.coordinates.width; // undefined
			let fittedWidth = content.width; // undefined
			let fittedHeight = content.height; // 50
		}
		onDisplaying(content) {
			let fittedWidth = content.width; // 320 (assuming the application is 320x240)
			let fittedHeight = content.height; // 50
		}
	}
});
application.add(sampleContent)

Templates are a tool that reduce the script code needed to instantiate contents and build the containment hierarchy. Templates are often used to create objects that are similar, but have a few slightly different properties.

For example, consider the following screens:

The code for these screens without templates is unnecessarily repetitive. The only difference between screen1 and screen2 here is the header background color and string.

let screen1 = new Column(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "blue" }), style: sampleStyle,
	contents: [
		Label(null, {
			top: 0, height: 40, left: 0, right: 0,
			string: "Screen 1"
		}),
		Content(null, {
			top: 0, bottom: 0, left: 0, right: 0,
			skin: new Skin({ fill: "white" })
		}),
	]
});

let screen2 = new Column(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "red" }), style: sampleStyle,
	contents: [
		Label(null, {
			top: 0, height: 40, left: 0, right: 0,
			string: "Screen 2"
		}),
		Content(null, {
			top: 0, bottom: 0, left: 0, right: 0,
			skin: new Skin({ fill: "white" })
		}),
	]
});

Using templates significantly reduces the amount of code needed to define the two screens.

let BasicScreen = Column.template($ => ({
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: $.headerColor }), style: sampleStyle,
	contents: [
		Label(null, {
			top: 0, height: 40, left: 0, right: 0,
			string: $.title
		}),
		Content(null, {
			top: 0, bottom: 0, left: 0, right: 0,
			skin: new Skin({ fill: "white" })
		}),
	]
}));

let screen1 = new BasicScreen({ title: "Screen 1", headerColor: "blue" });
let screen2 = new BasicScreen({ title: "Screen 2", headerColor: "red" });

As seen in the example above, the constructor has one parameter, $, which applications use to pass data to the template. The data may have any prototype; it is often a string, number, or JSON object. In their attributes, content and container objects use $ to access data properties. The $ parameter is referred to as “the data” or “the instantiating data.”

The template function for most Piu objects returns a constructor and a template function; the only exceptions are the Skin and Texture objects, which simply return constructors. These template functions allow constructors to be further specialized. In the example below, a HeaderWithBehavior instance would have all the properties of a BasicHeader instance in addition to being active and having a behavior.

let headerStyle = new Style({ font:"600 28px Open Sans", color: "white", horizontal: "left" });
let headerSkin = new Skin({ fill: "blue" });
let BasicHeader = Label.template($ => ({
	top: 0, height: 40, left: 0, right: 0,
	skin: headerSkin, style: headerStyle, string: $
}));

class HeaderBehavior extends Behavior {
	onTouchEnded(header) {
		trace("Header tapped\n");
	}
}
let HeaderWithBehavior = BasicHeader.template($ => ({
	active: true, Behavior: HeaderBehavior
}));

Piu delivers events to the containment hierarchy of applications, and content objects can reference behavior objects, which contain functions that respond to events. Piu uses events extensively.

When a content object receives an event, it checks whether its behavior object has a corresponding function to respond to that event (either directly or indirectly in its prototype chain). If it does, the content object calls the function, passing itself as the first parameter. If it does not, nothing happens.

Piu defines low-level events that are useful on a wide range of target devices. For example, onTouchBegan and onTouchEnded are useful for target devices with touch screens.

Applications can also define their own higher-level events. To help efficiently implement common event propagation patterns, contents have delegate, distribute, bubble, firstThat, and lastThat properties. See Functions in the section Content Object for descriptions of these properties.

There are multiple ways to create time-based animation behaviors. One way is to use content objects as clocks, as described in the Duration, Fraction, Interval, Loop, and Time section of this document. This method is commonly used to animate a single content in response to events (to show touch feedback, for example) and to animate a single content for long periods of time.

The simplest way to create complex behaviors that animate several contents or properties is using the timeline object. The timeline object provides a mechanism for sequencing and running a collection of tweens, making it the best method for staggered animations of multiple content objects (to transition graphical elements of a screen in and out, for example). For more information, see the Timeline Object section of this document.

Piu transition objects are best for simple animations to move between screens or swap content objects. They often modify the containment hierarchy by adding or removing contents. They can also modify properties of objects as timeline objects do, but creating a sequence of animations is more complicated. For more information, see the Transition Object section of this document.

Animations that linearly modify the properties of content objects often appear awkward. Using easing equations is a common way to implement animations that feel more natural.

Piu extends the JavaScript Math object with Robert Penner’s open source easing equations (see the Easing section of Robert Penner’s Programming Macromedia Flash MX). The source code is in piuTransition.c.

The Piu implementations of these easing equations all take a single argument: a number in the range [0, 1]. The return value is a number in the range [0, 1] that maps the input to the eased output. These equations are used extensively in all types of animations. They are commonly used to map the fraction property of content objects or the fraction argument of a transition object's onStep function, and as an argument to many timeline object functions.

Properties of the Piu global object can be used anywhere in an application.

• Source code: xsGlobal.c

Traces the specified string in the virtual machine of the hosted application.

Note: Strings will not be traced until a line break ("\n") has also been traced.

trace("Hello world\n");

let sampleVariable = 2;
trace(`sampleVariable value is: ${sampleVariable}\n`);    // "sampleVariable value is 2"

Additional properties can be added by setting a property of the global object.

global.application = new Application(null, {
	displayListLength: 2048, commandListLength: 2048
});
export default global.application;

This section provides descriptions of select properties referenced throughout the Piu Object Reference section below.

Each content object can have an optional anchor property. When the template is instantiated, a reference to the created content object is assigned to a property of the instantiating data; the identifier of the property is the value of the anchor property.

Anchors allow applications to directly access specific contents and containers in a containment hierarchy instantiated from a template. This can make it easier to access objects to modify while the application is running—for example, to change the label of a string, disable a button, or add lines to a column in a table.

let sampleStyle = new Style({ font:"600 28px Open Sans", color: "white" });
let SampleContent = Label.template($ => ({
	anchor: "ANCHORED_CONTENT", top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: $.color }), style: sampleStyle,
	string: $.title
}));
let SampleContainer = Container.template($ => ({
	active: true, top: 0, bottom: 0, left: 0, right: 0,
	contents: [
		new SampleContent($)
	],
	Behavior: class extends Behavior {
		onCreate(container, data) {
			this.data = data;
		}
		onTouchEnded(container) {
			this.data["ANCHORED_CONTENT"].string = "Hello!"
		}
	}
}));
application.add(new SampleContainer({ title: "Tap to update", color: "blue" }));

A color parameter can be passed into the dictionaries of skin and style constructors.

To specify a color, you can use CSS names (Level 2) or hexadecimal notations ("#RGB", "#RGBA", "#RRGGBB", "#RRGGBBAA"):

const whiteSkin = new Skin({ fill:"white" });
const redSkin = new Skin({ fill:"#F00" });
const halfRedSkin = new Skin({ fill:"#F008" });
const greenSkin = new Skin({ fill:"#00FF00" });
const halfGreenSkin = new Skin({ fill:"#00FF0088" });

To specify a color with an alpha channel, you can also use a mere hexadecimal number 0xRRGGBBAA:

const blueSkin = new Skin({ fill:0x0000FFFF });
const halfBlueSkin = new Skin({ fill:0x0000FF88 });

To build such hexadecimal numbers, Piu exports functions similar to the CSS functional notations:

import { rgb, rgba, hsl, hsla } from "piu/All";
const yellowSkin = new Skin({ fill:rgb(255, 255, 0) });
const halfYellowSkin = new Skin({ fill:rgba(255, 255, 0, 0.5) });
const cyanSkin = new Skin({ fill:hsl(180, 1, 0.5) });
const halfCyanSkin = new Skin({ fill:hsla(180, 1, 0.5, 0.5) });

In dictionaries, colors can be a single color or an array of 2, 3, or 4 colors. The skin and style objects blend a color based on the state of the content object that uses them. See Variant, Variants, State, and States for more information.

All content objects have a coordinates property. The coordinates property is an object with left, width, right, top, height, and bottom properties, all of which can be undefined. The coordinates of contents determine their position and size relative to their container and their previous and next properties (other content objects in the same container).

When a content's container is an application, container, scroller, or layout object:

• top, bottom, left, and right coordinates are all relative to their container
• If width, left, and right coordinates are all specified, the left and right coordinates will be overruled
• If left and right are both unspecified, the content will be centered horizontally in its container with the width specified (or a width of 0, if unspecified)
• If height, top, and bottom coordinates are all specified, the top and bottom coordinates will be overruled
• If top and bottom are both unspecified, the content will be centered vertically in its container with the height specified (or a height of 0, if unspecified)

When a content's container is a column object:

• top and bottom coordinates are relative to their previous and next properties
• left and right coordinates are relative to their container
• If width, left, and right coordinates are all specified, the left and right coordinates will be overruled

When a content's container is a row object:

• left and right coordinates are relative to their previous and next properties
• top and bottom coordinates are relative to their container
• If height, top, and bottom coordinates are all specified, the top and bottom coordinates will be overruled

Every content in the containment hierarchy can be used as a clock to control time-based animation behaviors using its duration, fraction, interval, and time properties.

• The duration property is the duration of the animation, expressed in milliseconds.
• The time property provides the current time of the content’s clock.
• The fraction property is the ratio of the clock’s current time to the content’s duration.
• The interval property is the time between frames (frame rate) of the animation, expressed in milliseconds.

The content’s start and stop functions control when the clock is running. The clock is automatically stopped when its current time reaches its duration. If the content's loop property is set to true, the clock will restart.

When a clock is running, the onTimeChanged function of its content is triggered at the interval specified by the content's interval property. When the content's time is equal to its duration, the onFinished function is triggered.

let animatedContent = new Content(null, {
	height: 100, width: 100, loop: true,
	skin: new Skin({ fill: ["red", "yellow", "blue"] }),
	Behavior: class extends Behavior {
		onCreate(content) {
			this.startAnimation(content);
		}
		startAnimation(content) {
			content.duration = 3000;
			content.time = 0;
			content.start();
		}
		onTimeChanged(content) {
			content.state = content.fraction*2;
		}
	}
});
application.add(animatedContent);

The interval property sets the desired frame rate for an object's clock, but be aware that it may not be exact if the application is overloaded. It is not safe to assume, for instance, that if a content's interval is 2 and its duration is 100 that it will trigger the onTimeChanged event exactly 50 times before it triggers the onFinished event. Therefore, it is recommended that applications use the fraction or time properties to determine which frame to display for animations.

For example, consider two implementations of a button that expands and contracts 10 pixels in both directions when tapped.

The following implementation is not recommended, as it assumes that onTimeChanged will be triggered exactly 20 times before onFinished. While this may work most of the time, it is possible that the content will trigger its onFinished event before it shrinks down to its original size.

class ExpandingBehavior extends Behavior {
	onTouchEnded(content) {
		this.index = 0;
		content.interval = 5;
		content.duration = 100;
		content.time = 0;
		content.start();
	}
	onTimeChanged(content) {
		this.index++;
		if (this.index < 10) content.sizeBy(1, 1);
		else content.sizeBy(-1, -1);
	}
}

let expandingButton = new Content(null, {
	active: true, height: 50, width: 100,
	skin: new Skin({ fill: "blue" }),
	Behavior: ExpandingBehavior
});

The following implementation is better because it makes no assumptions about the number of frames that will draw and ensures that the content shrinks down to the correct size when onFinished is called.

class ExpandingBehavior extends Behavior {
	onTouchEnded(content) {
		this.startingSize = { h: content.height, w: content.width };
		content.interval = 5;
		content.duration = 100;
		content.time = 0;
		content.start();
	}
	onTimeChanged(content) {
		let startingSize = this.startingSize;
		let fraction = content.fraction;
		if (fraction > 0.5) fraction = 1-fraction;
		fraction *= 20;
		content.height = startingSize.h + fraction;
		content.width = startingSize.w + fraction;
	}
	onFinished(content) {
		let startingSize = this.startingSize;
		content.height = startingSize.h;
		content.width = startingSize.w;
	}
}

let expandingButton = new Content(null, {
	active: true, height: 50, width: 100,
	skin: new Skin({ fill: "blue" }),
	Behavior: ExpandingBehavior
});

A font parameter must be passed into the dictionary of style constructors.

Piu uses bitmap fonts. The metrics are provided by binary FNT files, the glyphs are provided by PNG files.

Fonts are assets and must be defined in the resources of your manifest. Use the default target or the -alpha or -color pseudo targets for fonts.

The binary FNT file format was defined by AngelCode, which also released the BMFont generator on Windows. On Mac you can for instance use Glyph Designer or bmGlyph to generate such files.

One bitmap font corresponds to one style, one weight, one stretch, one size and one family. You will need separate bitmap fonts for each variation.

The Style constructor uses the font property of its dictionary to lookup its font. You can just set the font property to the name of a binary FNT file:

const popStyle = new Style({ font:"popFont" });

The popStyle object will use the popFont.fnt file in your assets.

The lookup happens only when label or text objects that use the style are bound to the displayed containment hierarchy, or when the Style.prototype.measure method is called.

In order to cascade styles, you may want to use something similar to the CSS font shortcut. Note that if you use this method of defining fonts in an application, you should not define other fonts in the application using just the font name as described above.

const style = new Style({ font:"italic bold 16px Open Sans" });

In Piu, the font property has five optional parts, in that order:

1. style: italic | normal | inherit
2. weight: 100 | ultralight | 200 | thin | 300 | light | 400 | normal | 500 | medium | 600 | semibold | 700 | bold | 800 | heavy | 900 | black | lighter | bolder | inherit
3. stretch: condensed | normal | inherit
4. size: xx-small | x-small | small | medium | large | x-large | xx-large | smaller | larger | [1-9][0-9]+px | [1-9][0-9]+% | inherit
5. family: the rest of the font property if any.

The inherit value is the default value and is useful only to disambiguate a font property. By default the style of a content object inherits the style of its container objects.

All parts are optional and are cascaded separately. So you can for instance define a generic style for the application and specific styles for its contents:

const appStyle = new Style({ font:"16px Fira Sans" });
const menuStyle = new Style({ font:"bold" });

Styles are only cascaded when label or text objects that use them are bound to the displayed containment hierarchy.

For Piu to find the corresponding bitmap font files in your assets, you have to adopt the following convention, based on common practices:

• the family, without spaces,
• -,
• the capitalized name of the stretch, if not normal,
• the capitalized name of the computed weight, if not normal,
• the capitalized name of the style, if not normal,
• Regular, if the stretch, the computed weight and the style are all normal,
• -,
• the computed size in pixels without units.

Here above style will look for OpenSans-BoldItalic-16.fnt, appStyle will look for FiraSans-Regular-16.fnt and menuStyle will look for FiraSans-Bold-16.fnt.

Applications can tile skins using their tiles property. The size of the tiles is determined by left, right, top, and bottom values, as follows:

• If the tiles property is undefined or if its left, right, top and bottom values are all undefined, the skin is just an image, for instance an icon.
• Else if only the left or right values are defined, the skin becomes a horizontal 3-part pattern. The left part is drawn at the left of the content, the right part is drawn at the right of the content, and the center part is repeated to fill the center of the content.
• Else if only the top or bottom values are defined, the skin becomes a vertical 3-part pattern. The top part is drawn at the top of the content, the bottom part is drawn at the bottom of the content, and the middle part is repeated to fill the middle of the content.
• Else the skin becomes a 9-part pattern. Corner parts are drawn in the corresponding corners of the content, side parts are repeated in the sides, and the middle part is repeated to fill the middle. The left, right, top and bottom values can all be defined to 0 to fill the content with the skin.

Tiling skins allows content objects of different sizes to share a single asset. Here is an example that uses this 30x30 pixel background to fill arbitrarily sized contents.

let roundedRectangleTexture = new Texture("roundedRectangle.png");
let roundedRectangleSkin = new Skin({
	texture: roundedRectangleTexture,
	x: 0, y: 0, width: 30, height: 30,
	tiles: { left: 5, right: 5, top: 5, bottom: 5 }
});

let sampleStyle = new Style({ font:"600 28px Open Sans", color: "white" });

let smallText = new Label(null, {
	skin: roundedRectangleSkin, top: 20, left: 20, height: 30, width: 30,
	style: sampleStyle, string: "Hi"
});
let bigText = new Text(null, {
	skin: roundedRectangleSkin, top: 70, left: 20, height: 120, width: 100,
	style: sampleStyle, string: "This is a long string"
});

application.add(smallText);
application.add(bigText);

Applications often use the state and variant properties of content objects to update their appearance. Because they can change dynamically, they can be used to animate content objects and provide visual feedback to touch events, for example.

A common way that the state property is used is to update the color of contents. As described in the Color section of this document, the fill property of a skin or style object can be an array of colors. The state property of a content object using the skin determines the index of the array. If the state is not an integer, colors from surrounding states are blended.

let multiColoredSkin = new Skin({ fill: ["black", "white", "red"] });
let blackContent = new Content(null, {
	top: 20, left: 20, width: 80, height: 80,
	skin: multiColoredSkin, state: 0,
});
let redContent = new Content(null, {
	top: 20, left: 120, width: 80, height: 80,
	skin: multiColoredSkin, state: 2
});
let grayContent = new Content(null, {
	top: 20, left: 220, width: 80, height: 80,
	skin: multiColoredSkin, state: 0.5
});
application.add(blackContent);
application.add(redContent);
application.add(grayContent);

It is often convenient to store several icons or other user interface elements in a single image. Specifying states and variants properties in the dictionary of skin constructors enables you to reference different sections of the same texture. This prevents an application from having to reference similar images and create multiple skins.

The states and variants properties of a skin are numerical values used to define the size of a single element in the texture. The states property represents the vertical offset between states, and the variants property represents the horizontal offset between variants. Here is an example of an asset that includes ten 28x28 pixel icons in one image, and a skin that will allow applications to reference each icon separately.

const wiFiStripTexture = new Texture({ path:"wifi-strip.png" });
const wiFiSkin = new Skin({
	texture: wiFiStripTexture,
	width: 28, height: 28,
	states: 28, variants: 28
});

The states and variants properties of texture objects should not be confused with the state and variant properties of content objects, although they are related. The state and variant of a content object are used to select which area of their skin to render. Here is a visualization of the state and variant properties a content would use to reference different portions of the skin object from the last example.

The state and variant of a content can be updated at any time. This is often done when an event is triggered.

let WiFiStatusIcon = Content.template($ => ({
    skin: wiFiSkin, state: $.passwordProtected, variant: 0,
    interval: 500, duration: 2500, loop: true,
    active: true,
    Behavior: class extends Behavior {
    	onDisplaying(content) {
    		content.start();
    	}
        onTimeChanged(content) {
        	let variant = content.variant;
        	variant++;
        	if (variant > 4) variant = 0;
        	content.variant = variant;
        }
    }
}));
application.add(new WiFiStatusIcon({ passwordProtected: false }, { top: 20, right: 20 }));
application.add(new WiFiStatusIcon({ passwordProtected: true }, { top: 58, right: 20 }));

This section provides details on the objects that define the Piu API. For each object, the following information is presented if relevant:

• Source Code: A link to the source code for the object

• Relevant Examples: Links to example apps that demonstrate how to use the object

• Constructor Description: A description of the object's constructor(s)

• Dictionary: Present when additional information is needed regarding the dictionary passed to the object's dictionary-based constructor; describes the properties that the dictionary may contain. Dictionary parameters set properties having the same name (unless noted otherwise) in the created instance.

• Prototype Description: The prototype from which this object's prototype inherits and descriptions of any properties and functions specific to this object's prototype

• Events: Descriptions of the events that the object triggers

For the complete JavaScript programming interface, see piuAll.js.

• Source code: piuApplication.c
• Relevant Examples: all

All Piu applications must have an application object at the root of their containment hierarchy. All other content objects must be added to the application to appear on screen.

There is no default object, so you have to create one yourself and export it in the main module.

export default new Application();

Alternatively, you can export a function that returns an application object.

export default function() {
	return new Application();
}

Returns an application instance, an object that inherits from Container.prototype.

export default new Application(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "blue" }),
});

Returns a constructor, a function that creates instances of Application.prototype. The prototype property of the result is Application.prototype. The result also provides a template function.

// Taken from the balls example app

...

let BallApplication = Application.template($ => ({
	skin:backgroundSkin,
	contents: [
		Content(6, { left:0, top:0, skin:ballSkin, variant:0, Behavior: BallBehavior } ),
		Content(5, { right:0, top:0, skin:ballSkin, variant:1, Behavior: BallBehavior } ),
		Content(4, { right:0, bottom:0, skin:ballSkin, variant:2, Behavior: BallBehavior } ),
		Content(3, { left:0, bottom:0, skin:ballSkin, variant:3, Behavior: BallBehavior } ),
	]
}));

export default new BallApplication(null, { displayListLength:4096, touchCount:0 });

Same as for container object (see Dictionary in the section Container Object), plus:

Prototype inherits from Container.prototype.

• Source code: piuBehavior.c
• Relevant Examples: balls, drag

The behavior object contains functions corresponding to events triggered by a content object. A content object checks whether its behavior owns or inherits a function property with the name of the event, and if so calls that function, passing itself as the first parameter.

Applications define their own constructors for behavior objects, which inherit from Behavior.prototype and assign them to content objects when they are constructed. When a content object is constructed, it creates an instance of the behavior class assigned to it and triggers the behavior's onCreate event. This function does nothing by default; a behavior can use it to initialize its properties, for example.

class SampleBehavior extends Behavior {
	onCreate(content, data) {
		this.name = data.name;
	}
	onTouchEnded(content) {
		trace(`Name is: ${this.name}\n`);	// "Name is: Moddable"
	}
}

let sampleContent = new Content({ name: "Moddable" }, {
    active: true, height: 100, width: 100,
    skin: new Skin({fill: "blue"}),
    Behavior: SampleBehavior
});
application.add(sampleContent);

Prototype inherits from Object.prototype.

• Source code: piuColumn.c
• Relevant Examples: keyboard, weather

The column object is a container object that arranges its contents vertically.

Returns a column instance, an object that inherits from Column .prototype

let ColoredSquare = Content.template($ => ({
	left: 0, right: 0, top: 0, bottom: 0,
	skin: new Skin({ fill: $ })
}));

let sampleColumn = new Column(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	contents: [
		new ColoredSquare("red"),
		new ColoredSquare("blue"),
		new ColoredSquare("black"),
	]
});
application.add(sampleColumn);

Returns a constructor, a function that creates instances of Column.prototype. The prototype property of the result is Column.prototype. The result also provides a template function.

let ColoredSquare = Content.template($ => ({
	left: 0, right: 0, top: 0, bottom: 0,
	skin: new Skin({ fill: $ })
}));

let SampleColumn = Column.template($ => ({
	top: 0, bottom: 0, left: 0, right: 0,
	contents: [
		new ColoredSquare($.firstColor),
		new ColoredSquare($.secondColor),
	],
}));
application.add(new SampleColumn({ firstColor:"red", secondColor:"blue" }));

Prototype inherits from Container.prototype.

Same as for container object (see Events in the section Container Object)

• Source code: piuContainer.c
• Relevant Examples: drag, transitions

The container object is a content object that can contain other content objects. In a container, content objects are stored in a doubly linked list. The content objects can also be accessed by index or by name using the content property, for instance container.content(0) or container.content("foo").

Returns a container instance, an object that inherits from Container.prototype.

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({fill: "white"}),
	contents: [
		new ColoredSquare("blue", { left: 0, top: 0 }),
		new ColoredSquare("red", { right: 0, top: 50 }),
		new ColoredSquare("black", { left: 100, bottom: 0 }),
	]
})
application.add(sampleContainer);

Returns a constructor, a function that creates instances of Container.prototype. The prototype property of the result is Container.prototype. The result also provides a template function.

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));

let SampleContainer = Container.template($ => ({
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: $.backgroundColor }),
	contents: [
		new ColoredSquare( $.squareColor ),
	]
}));
application.add(new SampleContainer({ backgroundColor: "white", squareColor: "blue" }));

Same as for content object (see Dictionary in the section Content Object), plus:

Prototype inherits from Content.prototype.

Same as for content object (see Properties in the section Content Object), plus:

add(content)

Adds the specified content object to this container. The content object becomes the last content object in this container.

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));
let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
});

sampleContainer.add(new ColoredSquare("black", {bottom: 10, left: 15}));
sampleContainer.add(new ColoredSquare("blue", {left: 100}));
sampleContainer.add(new ColoredSquare("green", {top: 10, left: 10}));
application.add(sampleContainer);

content(at)

Returns the specified content object, or undefined if no content with the index or name specified is in this container

let sampleContainer = new Container(null, {
	contents: [
		new Content(null, { name: "Moddable" }),
		new Content(),
	]
});
let namedContent = sampleContainer.content("Moddable");
let unnamedContent = sampleContainer.content(1);
let nonexistentContent = sampleContainer.content("Nonexistent");	// undefined

empty([start, stop])

Removes content objects from this container, starting at index start and stopping at index stop. If start or stop is less than 0, it is an offset from this.length.

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
	contents: [
		new ColoredSquare("blue", { top: 0, left:0 }),
		new ColoredSquare("red", { top: 0, right: 0 })
	]
});

sampleContainer.empty();
application.add(sampleContainer);

firstThat(id [, ...])

Causes all content objects in this container to trigger an event named by the value of id. The order of traversal is from the first to the last. Traversal halts when a distributed event returns true. Note that the first parameter of a distributed event is the content object that triggers the event, not this container. Additional parameters, if any, of the event are the extra parameters of the firstThat function.

class SampleBehavior extends Behavior {
	sampleEvent(content) {
		trace(content.name+" triggered\n");
		return true;
	}
}

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
	contents: [
		Content(null, { name: "firstContent" }),
		Content(null, { name: "secondContent", Behavior: SampleBehavior }),
		Content(null, { name: "thirdContent", Behavior: SampleBehavior }),
	],
	Behavior: class extends Behavior {
		onDisplaying(container) {
			container.firstThat("sampleEvent");	// "secondContent triggered" will be traced here
		}
	}
});
application.add(sampleContainer);

insert(content, before)

Inserts one content object before another in this container as specified by the parameters

let ColoredSquare = Content.template($ => ({
    height: 100, width: 100,
    skin: new Skin({ fill: $ })
}));

let sampleContainer = new Container(null, {
    top: 0, bottom: 0, left: 0, right: 0,
    skin: new Skin({ fill: "white" }),
    contents: [
        new ColoredSquare("blue", { top: 0, left:0 }),
    ]
});
let redSquare = new ColoredSquare("red", { top: 20, left: 20, });
sampleContainer.insert(redSquare, sampleContainer.first);
application.add(sampleContainer);

lastThat(id [, ...])

Causes all content objects in this container to trigger an event named by the value of id. The order of traversal is from the last to the first. Traversal halts when a distributed event returns true. Note that the first parameter of a distributed event is the content object that triggers the event, not this container. Additional parameters, if any, of the event are the extra parameters of the lastThat function.

class SampleBehavior extends Behavior {
	sampleEvent(content) {
		trace(content.name+" triggered\n");
		return true;
	}
}

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
	contents: [
		Content(null, { name: "firstContent" }),
		Content(null, { name: "secondContent", Behavior: SampleBehavior }),
		Content(null, { name: "thirdContent", Behavior: SampleBehavior }),
	],
	Behavior: class extends Behavior {
		onDisplaying(container) {
			container.lastThat("sampleEvent");	// "thirdContent triggered" will be traced here
		}
	}
});
application.add(sampleContainer);

remove(content)

Removes the specified content object from this container

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));

let redSquare = new ColoredSquare("red");
let blueSquare = new ColoredSquare("blue");

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
	contents: [
		redSquare,
		blueSquare,
	],
});
sampleContainer.remove(redSquare);
application.add(sampleContainer);

replace(content, by)

Replaces one content object with another in this container as specified by the parameters

let ColoredSquare = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({ fill: $ })
}));

let redSquare = new ColoredSquare("red");
let blueSquare = new ColoredSquare("blue");

let sampleContainer = new Container(null, {
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: "white" }),
	contents: [
		blueSquare,
	],
});
sampleContainer.replace(blueSquare, redSquare);
application.add(sampleContainer);

run(transition [, ...])

Runs the specified transition object in this container, binding that object to this container for the duration of the transition. The extra parameters are passed to the onBegin and onEnd functions of the transition object. The container triggers the onTransitionBeginning event before the transition starts and the onTransitionEnded event after the transition ends.

import CombTransition from "piu/CombTransition";
class SwitchScreenBehavior extends Behavior {
	onCreate(content, data) {
		this.data = data;
	}
	onTouchEnded(content) {
		let data = this.data;
		let transition = new CombTransition(250, Math.quadEaseOut, "horizontal", 4);
		let nextScreen = new ColoredScreen({ color: data.nextColor, nextColor: data.color })
		application.run(transition, application.first, nextScreen);
	}
}
let ColoredScreen = Container.template($ => ({
	top: 0, bottom: 0, left: 0, right: 0,
	skin: new Skin({ fill: $.color }),
	contents: [
		Content($, {
			active: true, height: 100, width: 100,
			skin: new Skin({ fill: $.nextColor }),
			Behavior: SwitchScreenBehavior
		})
	]
}));
application.add(new ColoredScreen({ color: "red", nextColor: "blue" }));

swap(content0, content1)

Swaps the specified content objects in this container

let ColoredSquare = Content.template($ => ({
    height: 100, width: 100,
    skin: new Skin({ fill: $ })
}));

let sampleContainer = new Container(null, {
    active: true, top: 0, bottom: 0, left: 0, right: 0,
    skin: new Skin({ fill: "white" }),
    contents: [
        new ColoredSquare("blue", { top: 0, left:0 }),
        new ColoredSquare("red", { top: 50, left:50 }),
    ],
    Behavior: class extends Behavior {
    	onTouchEnded(container) {
    		container.swap(container.first, container.last);
    	}
    }
});
application.add(sampleContainer);

Same as for content object (see Events in the section Content Object), plus:

onTransitionBeginning(container)

This event is triggered when a transition object starts in the specified container object.

onTransitionEnded(container)

This event is triggered when a transition object ends in the specified container object.

• Source code: piuContent.c
• Relevant Examples: balls, love-js

Applications use content objects for graphical parts of their user interface, such as buttons, icons, sliders, switches, and tabs.

Returns a content instance, an object that inherits from Content.prototype

let sampleContent = new Content("Hello", {
	top: 0, right: 50, height: 100, width: 100,
	skin: new Skin({fill: "blue"}),
	Behavior: class extends Behavior {
		onCreate(content, data) {
			trace(`${data}\n`);		// Prints "Hello" to console
		}
	}
})
application.add(sampleContent);

Returns a constructor, a function that creates instances of Content.prototype. The prototype property of the result is Content.prototype. The result also provides a template function.

let SampleContent = Content.template($ => ({
	height: 100, width: 100,
	skin: new Skin({fill: $.color}),
	Behavior: class extends Behavior {
		onCreate(content, data) {
			trace(`This box is ${data.color}\n`);		// Prints "This box is red" to console
		}
	}
}));
application.add(new SampleContent({color: "red"}, {top: 0, right: 50}));
application.add(new SampleContent({color: "blue"}));

Prototype inherits from Object.prototype.

bubble(id [, ...])

Causes this content and all container objects upward in the containment hierarchy to trigger an event named by the value of id. The bubbling halts when a bubbled event returns true. Note that the first parameter of a bubbled event is the container object that triggers the event, not this content. Additional parameters, if any, of a bubbled event are the extra parameters of the bubble function.

let NamedContainer = Container.template($ => ({
	name: $.name, active: true, top: 20, bottom: 20, left: 20, right: 20,
	skin: new Skin({ fill: $.color }),
	Behavior: class extends Behavior {
		printName(container) {
			trace(`${container.name} triggered\n`);
		}
		onTouchEnded(container) {
			trace("\n");
			container.bubble("printName");
		}
	}
}));
let outerContainer = new NamedContainer({ name: "outerContainer", color: "red" });
let middleContainer = new NamedContainer({ name: "middleContainer", color: "blue" });
let innerContainer = new NamedContainer({ name: "innerContainer", color: "black" });
outerContainer.add(middleContainer);
middleContainer.add(innerContainer);
application.add(outerContainer);

captureTouch(id, x, y, ticks)

Causes this content to capture the touch named id, meaning that only this content will trigger the remaining onTouchMoved and onTouchEnded events related to that touch. Other content objects concerned with the captured touch trigger the onTouchCancelled event when the captureTouch function is called.

class BlueBehavior extends Behavior {
    onTouchBegan(content, id, x, y, ticks) {
    	trace("Blue touch began\n");
        content.captureTouch(id, x, y, ticks);		// With this line, the redContainer behavior's onTouchCancelled method is called; without this line, its onTouchBegan and onTouchEnded methods would be called
    }
    onTouchEnded(content, id, x, y, ticks) {
    	trace("Blue touch ended\n");
    }
}
let blueCapturingContent = new Content(null, {
    active: true, top: 25, left: 25, height: 50, width: 50,
    skin: new Skin({fill: "blue"}),
    Behavior: BlueBehavior
});

class RedBehavior extends Behavior {
    onTouchBegan(content, id, x, y, ticks) {
        trace("Red touch began\n");
    }
    onTouchCancelled(content) {
    	trace("Red touch cancelled\n");
    }
    onTouchEnded(content, id, x, y, ticks) {
    	trace("Red touch ended\n");
    }
}
let redContainer = new Container(null, {
    active: true, backgroundTouch: true,
    top: 0, left: 0, height: 100, width: 100,
    skin: new Skin({fill: "red"}),
    contents: [
    	blueCapturingContent
    ],
    Behavior: RedBehavior
});

application.add(redContainer);

defer(id [, ...])

The defer function is similar to the delegate function; both cause this content to trigger an event named by the value of id. The difference is in their timing. The delegate function sends the event immediately while the defer functions posts the event. The event will be triggered at the following iteration of the main event loop.

The first parameter of the deferred event is this content. Additional parameters, if any, of the deferred event are the extra parameters of the defer function.

delegate(id [, ...])

Causes this content to trigger an event named by the value of id. The first parameter of the delegated event is this content. Additional parameters, if any, of the delegated event are the extra parameters of the delegate function.

let NamedContainer = Container.template($ => ({
	name: $.name, active: true, top: 20, bottom: 20, left: 20, right: 20,
	skin: new Skin({ fill: $.color }),
	Behavior: class extends Behavior {
		printName(container) {
			trace(`${container.name} triggered\n`);
		}
		onTouchEnded(container) {
			trace("\n");
			container.delegate("printName");
		}
	}
}));
let outerContainer = new NamedContainer({ name: "outerContainer", color: "blue" });
let middleContainer = new NamedContainer({ name: "middleContainer", color: "black" });
let innerContainer = new NamedContainer({ name: "innerContainer", color: "red" });
outerContainer.add(middleContainer);
middleContainer.add(innerContainer);
application.add(outerContainer);

focus()

Focuses this content so that it triggers keyboard events. Only one content object at a time is focused.

distribute(id [, ...])

Causes this container and all content objects downward in the containment hierarchy to trigger an event named by the value of id. The order of traversal is depth first. Traversal halts when one of the triggered event-handling functions returns true. Note that the first parameter of a distributed event is the content object that triggers the event, not this container. Additional parameters, if any, of the event are the extra parameters of the distribute function.

let NamedContainer = Container.template($ => ({
	name: $.name, active: true, top: 20, bottom: 20, left: 20, right: 20,
	skin: new Skin({ fill: $.color }),
	Behavior: class extends Behavior {
		printName(container) {
			trace(`${container.name} triggered\n`);
		}
		onTouchEnded(container) {
			trace("\n");
			container.distribute("printName");
		}
	}
}));
let outerContainer = new NamedContainer({ name: "outerContainer", color: "red" });
let middleContainer = new NamedContainer({ name: "middleContainer", color: "blue" });
let innerContainer = new NamedContainer({ name: "innerContainer", color: "black" });
outerContainer.add(middleContainer);
middleContainer.add(innerContainer);
application.add(outerContainer);

hit(x, y)

Returns this content if this content is active, bound, and contains the position, and undefined otherwise. If this content is a container instance, returns either one of its contents or itself if the content or itself is active, bound, and contains the position, or undefined.

Note that this function should only be used after a content has been measured and fitted; otherwise it will always return undefined.

let sampleContent = new Content(null, {
    active: true, top: 0, left: 0, height: 100, width: 100,
    skin: new Skin({fill: "blue"}),
    Behavior: class extends Behavior {
        onDisplaying(content) {
			let x = content == content.hit(10, 10);		// true
			let y = content.hit(200, 200);			// undefined
        }
    }
});

measure()

Returns the measured size of this content, as an object with width and height parameters.

Example 1:

let sampleContent = new Content(null, {
    top: 0, left: 0, height: 100, width: 100,
    skin: new Skin({fill: "blue"})
});
application.add(sampleContent);

let measuredSize = sampleContent.measure(); 	// {height: 100, width: 100}
let fittedHeight = sampleContent.height;		// 100
let fittedWidth = sampleContent.width;			// 100

Example 2:

let sampleContent = new Content(null, {
    top: 0, bottom: 0, left: 0, right: 0,
    skin: new Skin({fill: "blue"})
});
application.add(sampleContent);

let measuredSize = sampleContent.measure(); 	// {height: 0, width: 0}
let fittedHeight = sampleContent.height;		// 320 (assuming running on 240x320 screen)
let fittedWidth = sampleContent.width;			// 240 (assuming running on 240x320 screen)

moveBy(x, y)

Moves this content as specified by the parameters. If the content's coordinates constrain its position, the moveBy function ignores the corresponding horizontal or vertical deltas.

let unconstrainedContent = new Content(null, {
    top: 0, left: 0, height: 100, width: 100,
    skin: new Skin({fill: "blue"}),
});
application.add(unconstrainedContent);
unconstrainedContent.moveBy(100,100);	// Moves unconstrainedContent 100 pixels in the x and y directions

let constrainedContent = new Content(null, {
    top: 0, left: 0, bottom: 140, right: 220,
    skin: new Skin({fill: "red"}),
});
application.add(constrainedContent);
constrainedContent.moveBy(100,100);	// Does nothing

sizeBy(width, height)

Sizes this content as specified by the parameters. If this content's coordinates constrain its size, the sizeBy function ignores the corresponding horizontal or vertical deltas.

let unconstrainedContent = new Content(null, {
    top: 0, left: 0, height: 100, width: 100,
    skin: new Skin({fill: "blue"}),
})
application.add(unconstrainedContent);
unconstrainedContent.sizeBy(100,100);	// Makes unconstrainedContent 100 pixels wider and taller

let constrainedContent = new Content(null, {
    top: 0, left: 0, bottom: 140, right: 220,
    skin: new Skin({fill: "red"}),
})
application.add(constrainedContent);
constrainedContent.sizeBy(100,100);	// Does nothing

start()

Starts this content's clock

class SampleBehavior extends Behavior {
	onDisplaying(content) {
		this.index = 0;
		content.interval = 750;
		content.time = 0;
		content.start();
	}
	onTimeChanged(content) {
		let state = content.state + 1;
		if (state > 3) state = 0;
		content.state = state;
	}
}
let sampleContent = new Content(null, {
	height: 100, width: 100,
	skin: new Skin({fill: ["red", "orange", "yellow", "green"]}),
	Behavior: SampleBehavior
});
application.add(sampleContent);

stop()

Stops this content's clock

class SampleBehavior extends Behavior {
	onDisplaying(content) {
		this.index = 0;
		content.interval = 750;
		content.time = 0;
		content.start();
	}
	onTimeChanged(content) {
		content.state = !content.state;
	}
	onTouchBegan(content) {
		content.stop();
	}
	onTouchEnded(content) {
		content.start();
	}
}
let sampleContent = new Content(null, {
	active: true, height: 100, width: 100,
	skin: new Skin({ fill: ["blue", "white"]}),
	Behavior: SampleBehavior
});
application.add(sampleContent);

The following standard events are triggered by content objects.

onCreate(content, data, context)

This event is triggered when the content is constructed.

onDisplaying(content)

This event is triggered after the specified content object is added to the containment hierarchy and has been measured and fitted, but before it is visible to the user. This is the first event the object receives after its coordinates have been computed.

onFinished(content)

This event is triggered when the specified content object is running and its time equals its duration.

onTimeChanged(content)

This event is triggered when the time of the specified content object changes.

onTouchBegan(content, id, x, y, ticks)

onTouchCancelled(content, id)

onTouchEnded(content, id, x, y, ticks)

onTouchMoved(content, id, x, y, ticks)

These events are triggered when the specified content object is active and touched.

• Source code: piuDie.c
• Relevant Examples: cards

The die object is a layout object that allows you to “die cut” its contents with a region, minimizing the areas to invalidate and to update. These are useful for building animations and transitions on constrained devices that cannot update every screen pixel at every frame.

The die object maintains two regions:

• the work region that the available operations build,
• the clip region that clips the contents of the die object

Both regions are initially empty.