Value Types

General

Properties<Widget>

The generic Properties type describes an object containing any number of key-value pairs corresponding to the settable properties of a given widget class. Such objects can be givin to a widget constructor or set method so set multiple widget properties simultaneously.

// Valid:
video.set({autoPlay: true, url: './myvideo.mp4'});
// Invalid: duration is read-only and can not be set!
video.set({duration: 1000});

The TypeScript interface always requires the widget class type parameter:

// Correct:
let props: Properties<Video> = {autoPlay: true, url: './myvideo.mp4'};
// Compiler Error: duration is read-only and can not be set!
props = {duration: 1000};

This interface is especially relevant when writing custom components in TypeScript, where it is needed to define the constructor:

class CustomComponent extends Composite {

  constructor(properties: Properties<CustomComponent>) {
    super(properties);
  }

}

PropertyChangedEvent<TargetType, ValueType>

An event object fired when an object property changes. It is an instance of EventObject that provides an additional property value containing the new value.

The TypeScript interface is generic with two parameter, the type of the target and the type of the value that changed:

interface PropertyChangedEvent<TargetType, ValueType> extends EventObject<TargetType> {
  readonly value: ValueType
}

Layout API

See also Layout.

Bounds

• JavaScript Type: Object
• TypeScript Type: tabris.Bounds

The bounds of a rectangle in relation to the top-left corner of a containing element in DIP (device independent pixel). This is a plain object implementing the following interface:

interface Bounds {
  left: number;
  top: number;
  width: number;
  height: number;
}

Explanation:

Example:

const buttonRight = button.bounds.left + button.bounds.width;

BoxDimensions

• JavaScript Type: Object or string or Array.
• TypeScript Type: tabris.BoxDimensions

The bounds of a rectangle in relation to the four edges of a containing element in DIP (device independent pixel). By default it is a plain object implementing the following interface:

interface BoxDimensions {
  left?: number;
  right?: number;
  top?: number;
  bottom?: number;
}

All properties are dimension and optional. Omitted properties are treated as 0.

As a shorthand a list of four dimensions is also accepted. This follow the order of [top, right, bottom, left], with missing entries being filled in by the entry of the opposing dimension. If only one entry is given it is used for all dimensions:

[1, 2, 3, 4] // {top: 1, right: 2, bottom: 3, left: 4};
[1, 2, 3] // {top: 1, right: 2, bottom: 3, left: 2};
[1, 2] // {top: 1, right: 2, bottom: 1, left: 2};
[1] // {top: 1, right: 1, bottom: 1, left: 1};

A space separated string list is also accepted instead of an array, with or without px as a unit.

Examples:

widget.padding = {left: 8, right: 8, top: 0, bottom: 0};
widget.padding = {left: 10, right: 10};
widget.padding = [0, 8];
widget.padding = [1, 10, 2, 10];
widget.padding = '10px 11px 12px 13px';
widget.padding = '10 11 12 13';
widget.padding = '0 8';

ConstraintValue

• JavaScript Type: tabris.Constraint, tabris.Widget, tabris.Percent, Symbol, Array, Object, string, number or true.
• TypeScript Type: tabris.ConstraintValue

A ConstraintValue represents a constraint on the layout of a widget that the parent uses to determine the position of one of its edges. This type allows various expressions that can all be used in place of a Constraint instance for convenience. All API that accept these expressions will convert them to a Constraint object. (With the exception of CanvasContext.)

Every expression of ConstraintValue consists of a reference value and/or an offset value. The following are all valid ConstraintValue types:

Offset-only constraints

Simply the Offset number by itself, a positive float including zero. A value of true is also accepted and treated like zero.

Examples:

widget.left = 12.5;
widget.right = 8;
widget.top = 0;
widget.bottom = true;

Reference-only constraints

Either a PercentValue or a SiblingReferenceValue.

Examples:

widget.left = '12%';
widget.right = 'prev()';
widget.top = new Percent(50);
widget.bottom = '#foo';

Constraint instance

An instance of the Constraint class naturally is also a valid ConstraintValue. It may be created via its constructor or the less strict Constraint.from factory.

ConstraintLikeObject

An object implementing the following interface:

interface ConstraintLikeObject {
  reference?: SiblingReferenceValue | PercentValue;
  offset?: Offset;
}

An instances of Constraint is a valid ConstraintLikeObject, but ConstraintLikeObject is less strict: The reference property can be a PercentValue or a SiblingReferenceValue, or can be omitted if offset is given. Either of the two entries may be omitted, but not both.

Examples:

widget.left = {reference: sibling, offset: 12};
widget.right = {reference: '23%', offset: 12};
widget.top = {reference: Constraint.prev};
widget.bottom = {offset: 12};

ConstraintArrayValue

An array tuple in the format of [reference, offset], where reference is either a PercentValue or a SiblingReferenceValue, and offset is an Offset, i.e. a number.

Examples:

widget.left = [sibling, 0];
widget.right = ['#foo', 0];
widget.top = [{percent: 23}, 12];
widget.bottom = [Constraint.prev, 12];

Constraint String

This is often the most compact way to express a constraint, but it may not be the preferred way in TypeScript projects if type safety is a priority. The string consists of a space separated list of two values in the pattern of 'reference offset'. The reference part may be of any string as accepted by SiblingReferenceValue or PercentValue. The offset has to be a positive (including zero) float, just like Offset.

Examples:

widget.left = '.bar 0';
widget.right = '#foo 0'
widget.top = '23% 12';
widget.bottom = 'prev() 12';

Dimension

• JavaScript Type: number
• TypeScript Type: tabris.Dimension, an alias for number

A positive float, or 0, representing device independent pixels (DIP).

LayoutDataValue

• JavaScript Type: tabris.LayoutData, Object
• TypeScript Type: tabris.LayoutDataValue

A LayoutDataValue provides layout information for a widget to be used its parent when determining its size and position. It allows various expressions that can all be used in place of a LayoutData instance for convenience. All API that accepts these expressions will convert them to a LayoutData object.

The following are all valid LayoutDataValue types:

LayoutData instance

An instance of the LayoutData class naturally is also a valid LayoutDataValue. It may be created via its constructor or the less strict LayoutData.from factory.

LayoutDataLikeObject

An object containing implementing the following interface:

interface LayoutDataLikeObject {
  left?: 'auto' | ConstraintValue;
  right?: 'auto' | ConstraintValue;
  top?: 'auto' | ConstraintValue;
  bottom?: 'auto' | ConstraintValue;
  centerX?: 'auto' | Offset | true;
  centerY?: 'auto' | Offset | true;
  baseline?: 'auto' | SiblingReferenceValue | true;
  width?: 'auto' | Dimension;
  height?: 'auto' | Dimension;
}

An instance of LayoutData is a valid LayoutDataLikeObject, but in LayoutDataLikeObject all properties are optional and less strict. For example left, top, right and bottom accept ConstraintValue (e.g. a number) in place of a Constraint instance.

A value of true is also accepted for all fields except width and height. For left, right, top, bottom, centerX and centerY it means 0. For baseline it means 'prev()'.

Example:

widget.layoutData = {
  baseline: 'prev()',
  left: 10,
  width: 100
};
widget.layoutData = {
  top: '25%',
  centerX: true
};

LayoutData string

There are 4 alias strings that can be used in place of a LayoutData object:

widget.layoutData = 'stretch';

Offset

• JavaScript Type: number
• TypeScript Type: tabris.Offset, an alias for number

A positive or negative float, or 0, representing device independent pixels (DIP).

PercentValue

• JavaScript Type: tabris.Percent, Object, string
• TypeScript Type: tabris.PercentValue

Represents a percentage. This type includes various expressions that can all be used in place of a Percent instance for convenience. All APIs that accept these expressions will convert them to a Percent object.

In TypeScript you can import this type as a union with import {PercentValue} from 'tabris'; or use tabris.PercentValue. A Type guard for PercentValue is available as Percent.isValidPercentValue.

Percent instance

An instance of the Percent class naturally is also a valid PercentValue. It may be created via its constructor or the more versatile Percent.from factory.

PercentLikeObject

A plain object in the format of {percent: number}, where 100 presents 100%. An instance of Percent is a valid PercentLikeObject.

Examples:

widget.left = {percent: 50};

Percent String

A number followed by %.

Example: '50%'

SiblingReference

• JavaScript Type: tabris.Widget, Symbol, string
• TypeScript Type: tabris.SiblingReference

A SiblingReference indicates a single sibling of a given Widget. Differs from the type SiblingReferenceValue in that it does not include 'next() and 'prev()' as selectors strings. It uses symbols instead. There are three variants of SiblingReference:

Sibling instance

Any widget instance that has the same parent.

Sibling Selector String

A simple selector string of the format '#Type', '#id', '.class'. No child selectors. The first matching sibling is selected.

Sibling Reference Symbol

The constants Constraint.prev and Constraint.next (also available as LayoutData.prev and LayoutData.next) may be used to point to the sibling directly before/after the reference widget in the parents children list.

SiblingReferenceValue

• JavaScript Type: tabris.Widget, Symbol, string
• TypeScript Type: tabris.SiblingReferenceValue

Same as SiblingReference, but less strict in that it also allows the strings 'next() and 'prev()' in place of the prev and next symbols.

Styling Related Types

Types related to the visual presentation of a widget.

ColorValue

• JavaScript Type: tabris.Color, Object, Array, string
• TypeScript Type: tabris.ColorValue

A ColorValue represents a 24 bit color, plus an alpha channel for opacity. This type allows various expressions that can all be used in place of a Color instance for convenience. All API that accept these expressions will convert them to a Color object. (With the exception of CanvasContext.) Setting a ColorValue property to null resets it to the default.

In TypeScript you can import this type as a union with import {ColorValue} from 'tabris'; or use tabris.ColorValue. Type guards for ColorValue are available as Color.isColorValue and Color.isValidColorValue.

The following are all valid ColorValue types:

Color instance

An instance of the Color class may be created via its constructor or the less strict Color.from factory.

Examples:

new Color(255, 0, 0)
new Color(255, 0, 0, 200)
Color.from("rgba(255, 0, 0, 0.8)")

ColorLikeObject

An object implementing the following interface:

interface ColorLikeObject {
  red: number;
  green: number;
  blue: number;
  alpha?: number;
}

An instance of Color is a valid ColorLikeObject.

Examples:

{red: 255, green: 255, blue: 255}
{red: 255, green: 255, blue: 255, alpha: 200}

ColorArray

An array in the shape of [red, green, blue, alpha]. All entries should be natural number between (and including) 0 and 255. If omitted, alpha is 255.

Examples:

[255, 0, 0]
[255, 0, 0, 200]

Color string

Any string in the following format:

Color names from the CSS3 specification are also accepted. They are available as static string properties of Color, e.g. Color.lime. These exist just to help with autocompletion.

Examples:

"#f00"
"#ff0000"
"#ff000080" // 50% opacity red
"#ff06" // 40% opacity yellow
"rgb(255, 0, 0)"
"rgba(255, 0, 0, 0.8)"
"red"
"initial" // same as null

FontValue

A FontValue describes a font by size, family, weight and style. This type allows various expressions that can all be used in place of a Font instance for convenience. All API that accept these expressions will convert them to a Font object. (With the exception of CanvasContext.) Setting a FontValue property to null resets it to the default.

Generic font size is always given as DIP (device independent pixels), though the string shorthand expects "px" as a unit. It’s still DIPs.

Generic font families are supported across all platforms: "serif", "sans-serif", "condensed" and "monospace". These are available as static string properties of Font, e.g. Font.serif. These exist just to help with autocompletion. More families can be added via app.registerFont. If no family is given for a font the system default is used. If no font family is given the default system font will be used. The string "initial" represents the platform default.

Supported font weights are "light", "thin", "normal", "medium", "bold" and "black". The default is "normal"

Supported font styles are "italic" and "normal". The default is "normal"

In TypeScript you can import this type as a union with import {FontValue} from 'tabris'; or use tabris.FontValue. Type guards for FontValue are available as Font.isFontValue and Font.isValidFontValue.

The following are all valid FontValue types:

Font instance

An instance of the Font class may be created via its constructor or the less strict Font.from factory.

Examples:

new Font({size: 16, family: Font.sansSerif})
Font.from("16px san-serif");

FontLikeObject

An object implementing the following interface:

interface FontLikeObject {
  size: number;
  family?: string[];
  weight?: FontWeight;
  style?: FontStyle;
}

An instance of Font is a valid FontLikeObject.

Examples:

{size: 16, weight: 'bold'}
{size: 24, family: 'sans-serif', style: 'italic'}

Font string

As a string, a subset of the shorthand syntax known from CSS is used: "font-style font-weight font-size font-family", where every value except size is optional. The size also need to have a "px" postfix. Multiple families may be given separated by commas. Families with spaces in their name need to be put in single or double quotes.

Examples:

"bold 24px"
"12px sans-serif"
"italic thin 12px sans-serif"
"24px 'My Font', sans-serif"
"initial"

ImageValue

A ImageValue describes an image source and optionally that image’s dimension or scale it should be displayed at. This type allows various expressions that can all be used in place of a Image instance for convenience. All API that accept these expressions will convert them to a Image object.

All ImageValue variations require a source (shortened to src), which is a File system path, relative path, full URL, a Blob containing a jpg or png file, or an ImageBitmap instance. The data URI scheme is also supported. Relative paths are resolved relative to the projects ‘package.json’. If an ImageBitmap is used it may not be closed at the time the bitmap is assigned to a property. On Android only the name of a bundled drawable resource may be provided via the android-drawable url scheme, e.g. android-drawable://ic_info_black.

The width and height of an image may optionally be specified in DIP (device independent pixel). If none are given the dimensions from the image file are used in combination with the given scale.

The scale is a positive float or 'auto'. The image will be scaled down by this factor. It is ignored if width or height are given. If neither scale, width or height are given the scale may be extracted from an image URL if the file name contains the pattern “@<scale>x”, e.g. "image@2x.jpg". If the scale can not be determined by any of these methods it will be treated as 1.

The scale factor of the image is relevant when the intrinsic size (in DIP) of the image is needed for layouting. On high-density displays (i.e. devices with a scale factor higher than 1) an undetermined image scale factor (or scale factor 1) may make the image look blurry at full its full natural size. It is the application developers responsibility to provide and use image files with the appropriate scale factor for any given device.

When displaying images that are very large (eg. 3000 x 2000) on small widgets (like a 100 x 100 ImageView), it is strongly recommended to provided a concrete image size. This will allow the system to scale the image to the given size, saving memory and computing power, which leads to a faster display time overall.

The following are all valid ImageValue types:

Image instance

An instance of the Image class may be created via its constructor or the less strict Image.from factory.

Examples:

new Image({src: "http://example.com/catseye.jpg", scale: 2})
new Image({src: "http://example.com/catseye.jpg", width: 100, height: 200})
Image.from(blob);

ImageLikeObject

An object implementing the following interface:

interface ImageLikeObject {
  src: string|ImageBitmap|Blob;
  scale?: number | "auto";
  width?: number | "auto";
  height?: number | "auto";
}

Basically it’s the interface of the Image class, but with all members except src being optional.

Examples:

{src: "images/catseye.jpg", width: 300, height: 200}
{src: blob, scale: 2}

Image Source

This is just the source value of an Image by itself, so a string, Blob or ImageBitmap.

"images/catseye.jpg"  // same as:
{src: "images/catseye.jpg"}

LinearGradientValue

A LinearGradientValue specifies a set of colors, their relative position along a straight line, and the angle of that line. This describes a color gradient that can be drawn to fill any area, usually the background of a widget. This type allows various expressions that can all be used in place of a LinearGradient instance for convenience. All API that accept these expressions will convert them to a LinearGradient object.

In TypeScript you can import this type as a union with import {LinearGradientValue} from 'tabris'; or use tabris.LinearGradientValue. Type guards for LinearGradientValue are available as LinearGradient.isLinearGradientValue and LinearGradient.isValidLinearGradientValue.

The following are all valid LinearGradientValue types:

LinearGradient instance

An instance of the LinearGradient class may be created via its constructor or the less strict LinearGradient.from factory.

Examples:

new LinearGradient([Color.red, Color.green]);
new LinearGradient([[Color.red, new Percent(5)], Color.green], 90);
LinearGradient.from({colorStops: [['red', '5%'], 'green'], direction: 'left'});
LinearGradient.from('linear-gradient(45deg, red 5%, green)');

LinearGradientLikeObject

An object implementing the following interface:

interface LinearGradientLikeObject {
  colorStops: Array<ColorValue | [ColorValue, PercentValue]>,
  direction?: number | 'left' | 'top' | 'right' | 'bottom'
}

An instances of LinearGradient is a valid LinearGradientLikeObject, but LinearGradientLikeObject is less strict as it accepts more expressions for colorStops and direction. Examples:

{colorStops: [['red', '5%'], 'green'], direction: 'left'}
{colorStops: [['red', '5%'], 'green'], direction: 45}

LinearGradient string

As a string, a subset of the CSS syntax is used:

<color-stop> ::= <color> [ <number>% ]
<linear-gradient> ::= linear-gradient(
    [ <number>deg | to ( left | top | right | bottom ), ]
    <color-stop> {, <color-stop>}
)

Examples:

"linear-gradient(red, green)"
"linear-gradient(to left, red 5%, green)"
"linear-gradient(45deg, red 5%, green)"

Binary Types

ImageData

Represents the underlying pixel data of an area of a Canvas widget. It is created using the creator methods on the CanvasContext: createImageData() and getImageData(). It can also be used to set a part of the canvas by using putImageData().

An ImageData object implements the following interface:

interface ImageData {
  data: Uint8ClampedArray;
  width: number;
  height: number;
}

Explanation:

Animation API

AnimationOptions

Options of the animate() method. They have to implement the following interface:

interface AnimationOptions {
  delay?: number;
  duration?: number;
  easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
  repeat?: number;
  reverse?: boolean;
  name?: string;
}

Each property has a default value if omitted:

Transformation

A Transformation is any object implementing the following interface:

interface Transformation {
  rotation?: number;
  scaleX?: number;
  scaleY?: number;
  translationX?: number;
  translationY?: number;
  translationZ?: number;
}

Each property has a default value if omitted:

Example:

{scaleX: 2, scaleY: 2, rotation: Math.PI * 0.75}

This transformation will make the widget twice as big and rotate it by 135°.