Class “Widget”

Object > NativeObject > Widget

Base class for all widgets

See also:

Understanding layouts in Tabris.js
Understanding gesture events in Tabris.js
JSX A Widget with padding [► Run in Playground]
JSX A card style Widget with corner radius and elevation [► Run in Playground]
JS A Widget with a linear-gradient background [► Run in Playground]
JS Using touch events on a Widget [► Run in Playground]
JSX widget-elevation.jsx [► Run in Playground]
JSX widget-exclude-from-layout.jsx [► Run in Playground]
JSX widget-highlightontouch.jsx [► Run in Playground]
JS widget-touch.js [► Run in Playground]

Methods

animate(properties, options)

Starts an animation that transforms the given properties from their current values to the given ones. Supported properties are transform and opacity. Returns a promise that is resolved once the animation is completed and is rejected if the animation is aborted.

Returns: Promise

appendTo(parent)

Appends this widget to the given parent. The parent widget must support children (extending Composite). If the widget already has a parent, it is removed from the old parent.

Returns: this

detach()

Removes this widget from its parent.

Returns: this

dispose()

Removes this widget from its parent and destroys it. Also disposes of all its children. Triggers a remove event on the parent and a dispose event on itself. The widget can no longer be used.

Returns: undefined

insertAfter(widget)

Inserts this widget directly after the given widget. If the widget already has a parent, it is removed from the old parent.

Returns: this

insertBefore(widget)

Inserts this widget directly before the given widget. If the widget already has a parent, it is removed from the old parent.

Returns: this

isDisposed()

Returns true if the widget has been disposed, otherwise false.

Returns: boolean

parent()

Returns the parent of this widget or null if this widget is not appended to a parent.

Returns: Composite

parent(selector)

Returns the first (nearest) parent of this widget that matches the given selector, or null if no parent matches.

Returns: Result

siblings(selector?)

Returns a (possibly empty) collection of all siblings of this widget that match the given selector.

Returns: WidgetCollection

Protected Methods

These methods are accessible only in classes extending Widget.

_setParent(parent, index?)

Sets the parent of the widget. If an index is given the widget will be inserted at that position.

Returns: undefined

Properties

absoluteBounds

The actual location and size of the widget, relative to contentView.

background

The background of the widget. If given a plain string it is interpreted first as a gradient, then as a color, and finally as an image path, whichever passes first. Use object literals or instances of LinearGradient, Color or Image to avoid any ambiguity.

baseline

The vertical position of the widget’s baseline relative to a sibling widget. Value true is treated like 'prev()' and aligns it with the previous sibling.

bottom

The position of the widget’s bottom edge relative to the parent or a sibling widget.

bounds

The actual location and size of the widget, relative to its parent.

centerX

The horizontal position of the widget’s center relative to the parent’s center. Value true is treated like 0 and puts it at the exact center without offset.

centerY

The vertical position of the widget’s center relative to the parent’s center. Value true is treated like 0 and puts it at the exact center without offset.

class

A class name or a whitespace separated list of class names to identify the widget. Class names are arbitrary strings that describe a state or a category and help to select widgets using a selector expression. A class name may only contain alphanumeric characters, _ and -. Class names can also be added or removed using the field classList.

classList

Provides convenient access to the list of class names set to this widget. Class names can either be set using the class property or by modifying the classList directly.

cornerRadius

Configure a widget to have equally rounded corners. The widget content is clipped by the rounded corners.

See also:

JSX widget-cornerradius.jsx [► Run in Playground]

data

A general-purpose property that may be set to any object. Unlike other properties, data forwards change events from the object it contains. As it is initialized with an empty instance of ObservableData, modifying this initial data object also causes a PropertyChangedEvent for data to be fired.

Important: If data is assigned a plain object, that object will be converted to an ObservableData instance, so the original object will not be identical with the new data value. If set to any other object the new value will be the same instance.

When set as an attribute (via JSX or a widget factory) it has a special treatment: Unlike other properties it is set after the listeners have been registered. This is so to allow passing a data change listener (via ‘onDataChanged’ attribute) that will be invoked for the initial data value immediately.

elevation

The position of the widget on the z-axis. Setting an elevation casts a shadow in the shape of the widget.

To have the shadow properly applied on Android it is required to set the background on the widget as well.

See also:

JSX widget-elevation.jsx [► Run in Playground]

enabled

Whether the widget can be interacted with.

excludeFromLayout

If set to true the widget will be invisible and ignored in the layout of the parent. Visually it is treated like it was not attached to its parent, but it will still included in the return value of children().

height

The height of the widget.

highlightOnTouch

Whether the widget should show visual feedback while touched. Enabling highlightOnTouch will not prevent the touch event from being propagated to the parent widget.

See also:

JSX widget-highlightontouch.jsx [► Run in Playground]

id

A string to identify the widget by using selectors. IDs are optional. It is strongly recommended that they are unique within any component.

layoutData

Provides information for a widget to be used by the parent when determining its size and position. While this property accepts any valid LayoutData expression (see LayoutDataValue), it will always return an instance of the class LayoutData.

Widget provides an alias property for each property of LayoutData. Setting these properties will change the value of the layoutData property, while getting them is the same as accessing them via the layoutData property. I.e. widget.left === widget.layoutData.left.

There are multiple presets for layoutData available as static properties on the LayoutData class: center, [stretch](/3.9/api/LayoutData.html#stretch), stretchX and [stretchY](/3.9/api/LayoutData.html#stretchy). They may be set directly (new TextView({layoutData: LayoutData.stretch});), via string (e.g. new TextView({layoutData: 'stretch'});), or in JSX via a special shorthand syntax: <TextView stretch/>. The presets can be merged with widget properties, e.g. <TextView stretch left={10}/> or <TextView stretchX centerY/>

left

The position of the widget’s left edge relative to the parent or a sibling widget.

opacity

Opacity of the entire widget, in the range [0..1]. Can be used for fade animations.

padding

Additional space to add inside the widgets bounds.

See also:

JSX widget-padding.jsx [► Run in Playground]

right

The position of the widget’s right edge relative to the parent or a sibling widget.

top

The position of the widget’s top edge relative to the parent or a sibling widget.

transform

Modifications to the widget’s shape, size, or position. Can be used for animations. Note: In Android the transform property does not affect the bounds property, while it does so in iOS.

visible

If set to false the widget will be invisible, but still occupy space in the parents layout. Visually it is treated like a widget with an opacity of 0, but in addition the widget can also not be interacted with anymore.

width

The width of the widget.

Events

tap

Fired once when a finger briefly touched the widget.

EventObject Type: WidgetTapEvent<Widget>

longPress

Fired after pressing a widget for a specific amount of time (about a second), and again on lifting the finger.

EventObject Type: WidgetLongPressEvent<Widget>

See also:

JS widget-longpress-to-drag.js [► Run in Playground]

pan

Fired continuously after a finger touching the widget moved for a certain distance.

EventObject Type: WidgetPanEvent<Widget>

panUp

Fired when a finger starts moving up.

EventObject Type: WidgetPanEvent<Widget>

panDown

Fired when a finger starts moving down.

EventObject Type: WidgetPanEvent<Widget>

panLeft

Fired when a finger starts moving left.

EventObject Type: WidgetPanEvent<Widget>

panRight

Fired when a finger starts moving right.

EventObject Type: WidgetPanEvent<Widget>

panHorizontal

Fired when a finger starts moving left or right.

EventObject Type: WidgetPanEvent<Widget>

panVertical

Fired when a finger starts moving up or down.

EventObject Type: WidgetPanEvent<Widget>

swipeUp

Fired when a finger moves up quickly.

EventObject Type: WidgetSwipeEvent<Widget>

swipeDown

Fired when a finger moves down quickly.

EventObject Type: WidgetSwipeEvent<Widget>

swipeLeft

Fired when a finger moves left quickly.

EventObject Type: WidgetSwipeEvent<Widget>

swipeRight

Fired when a finger moves right quickly.

EventObject Type: WidgetSwipeEvent<Widget>

touchStart

Fired when a widget is touched. See Touch Events.

EventObject Type: WidgetTouchEvent<Widget>

touchMove

Fired repeatedly while swiping across the screen.

EventObject Type: WidgetTouchEvent<Widget>

touchEnd

Fired when a touch ends on the same widget than it started on.

EventObject Type: WidgetTouchEvent<Widget>

touchCancel

Fired instead of touchEnd when the touch ends on another widget than it started on.

EventObject Type: WidgetTouchEvent<Widget>

resize

Fired when the widget’s size has changed.

EventObject Type: WidgetResizeEvent<Widget>

dispose

Fired when the widget is about to be disposed. At this point the widget and its children are still accessible.

EventObject Type: EventObject<Widget>

This event has no additional parameter.

Change Events

idChanged

Fired when the id property has changed.

EventObject Type: PropertyChangedEvent<Widget, string>

classChanged

Fired when the class property has changed.

EventObject Type: PropertyChangedEvent<Widget, string>

classListChanged

Fired when the classList property has changed.

EventObject Type: PropertyChangedEvent<Widget, Array>

enabledChanged

Fired when the enabled property has changed.

EventObject Type: PropertyChangedEvent<Widget, boolean>

excludeFromLayoutChanged

Fired when the excludeFromLayout property has changed.

EventObject Type: PropertyChangedEvent<Widget, boolean>

visibleChanged

Fired when the visible property has changed.

EventObject Type: PropertyChangedEvent<Widget, boolean>

layoutDataChanged

Fired when the layoutData property has changed.

EventObject Type: PropertyChangedEvent<Widget, LayoutDataValue>

leftChanged

Fired when the left property has changed.

EventObject Type: PropertyChangedEvent<Widget, ConstraintValue>

rightChanged

Fired when the right property has changed.

EventObject Type: PropertyChangedEvent<Widget, ConstraintValue>

topChanged

Fired when the top property has changed.

EventObject Type: PropertyChangedEvent<Widget, ConstraintValue>

bottomChanged

Fired when the bottom property has changed.

EventObject Type: PropertyChangedEvent<Widget, ConstraintValue>

widthChanged

Fired when the width property has changed.

EventObject Type: PropertyChangedEvent<Widget, Dimension | 'auto'>

heightChanged

Fired when the height property has changed.

EventObject Type: PropertyChangedEvent<Widget, Dimension | 'auto'>

centerXChanged

Fired when the centerX property has changed.

EventObject Type: PropertyChangedEvent<Widget, Offset
| 'auto'
| true>

centerYChanged

Fired when the centerY property has changed.

EventObject Type: PropertyChangedEvent<Widget, Offset
| 'auto'
| true>

baselineChanged

Fired when the baseline property has changed.

EventObject Type: PropertyChangedEvent<Widget, SiblingReferenceValue
| 'auto'
| true>

elevationChanged

Fired when the elevation property has changed.

EventObject Type: PropertyChangedEvent<Widget, number>

cornerRadiusChanged

Fired when the cornerRadius property has changed.

EventObject Type: PropertyChangedEvent<Widget, number>

boundsChanged

Fired when the bounds property has changed.

EventObject Type: PropertyChangedEvent<Widget, Bounds>

backgroundChanged

Fired when the background property has changed.

EventObject Type: PropertyChangedEvent<Widget, LinearGradientValue
| ColorValue
| ImageValue>

opacityChanged

Fired when the opacity property has changed.

EventObject Type: PropertyChangedEvent<Widget, number>

transformChanged

Fired when the transform property has changed.

EventObject Type: PropertyChangedEvent<Widget, Transformation>

highlightOnTouchChanged

Fired when the highlightOnTouch property has changed.

EventObject Type: PropertyChangedEvent<Widget, boolean>

dataChanged

Fired when the data property has changed.

EventObject Type: PropertyChangedEvent<Widget, TData>

Related Types

Dimension

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

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

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';

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;

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;
}

On iOS translationZ is not supported and will be ignored.

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°.

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);
  }

}

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