Widget

Extends NativeObject

Base class for all widgets

Import this type with “const {Widget} = require('tabris');”

Methods

animate(properties, options)

Parameters:

• properties: {transform?: Transformation, opacity?: number}
  • the properties and target values to animate.
• options: AnimationOptions
  • configures the animation itself.

Returns: *Promise*

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.

appendTo(parent)

Parameters:

• parent: Composite

Returns: this

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.

apply(properties)

Parameters:

• properties: object
  • an object in the format {Selector: {property: value, property: value, ... }, Selector: ...}

Returns: this

Applies the given properties to all descendants that match the associated selector(s).

If you wish to always exclude specific “internal” children from this, overwrite the children method on their parent. See children for details.

children(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

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

When writing custom UI components it may be useful to overwrite this method to prevent access to the internal children by external code. Doing so also affects find and apply, on this widget as well as on all parents, thereby preventing accidental clashes of widget id or class values. See also _children, _find and _apply.

detach()

Returns: this

Removes this widget from its parent.

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.

find(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

Returns a collection containing all descendants of all widgets in this collection that match the given selector.

If you wish to always exclude specific “internal” children from the result, overwrite the children method on their parent. See children for details.

insertAfter(widget)

Parameters:

• widget: Widget

Returns: this

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

insertBefore(widget)

Parameters:

• widget: Widget

Returns: this

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

isDisposed()

Returns: boolean

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

parent()

Returns: Composite

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

siblings(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

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

_apply(properties)

Parameters:

• properties: object
  • an object in the format {Selector: {property: value, property: value, ... }, Selector: ...}

Returns: this

Identical to the apply method, but intended to be used by subclasses in case the children method was overwritten . See children for details.

_children(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

Identical to the children method, but intended to be used by subclasses in case the children method was overwritten. See children for details.

_find(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

Identical to the find method, but intended to be used by subclasses in case the children method was overwritten. See children for details.

Properties

background

Type: Color

Background color of the widget.

backgroundImage

Type: Image

An image to be displayed on the widget’s background. If the image is smaller than the widget, it will be tiled.

baseline

Type: Widget|Selector

The vertical position of the widget’s baseline relative to a sibling widget.

bottom

Type: margin

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

bounds

read-only
Type: Bounds

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

centerX

Type: offset

The horizontal position of the widget’s center relative to the parent’s center.

centerY

Type: offset

The vertical position of the widget’s center relative to the parent’s center.

class

Type: string

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

Type: string[]

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

iOSAndroid

Type: number

Configure a widget to have rounded corners. Each corner is affected equally. Supported on iOS and Android 5.0+.

data

read-only
Type: object

A general-purpose object that allows the application to attach arbitrary data to the widget. Manipulations on this object have no effect on the widget itself in any way. Example: widget.data.myData = myData;

elevation

iOSAndroid

Type: number

The position of the widget on the z-axis. Supported on iOS and Android 5.0+.

enabled

Type: boolean, default: true

Whether the widget can be operated.

font

Type: Font

The font used for the widget.

height

Type: dimension

The height of the widget.

highlightOnTouch

Type: boolean, default: false

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

id

Type: string

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

layoutData

Type: LayoutData

Shorthand for all layout properties. See Layout.

left

Type: margin

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

opacity

Type: number, default: 1

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

right

Type: margin

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

top

Type: margin

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

transform

Type: Transformation

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

Type: boolean, default: true

Whether the widget is visible.

width

Type: dimension

The width of the widget.

win_theme

Windows 10

Type: string, supported values: light, dark, default, default: default

Controls the color scheme used for this widget. When set to "default" the theme is inherited from either the parent (if present) or the OS settings. Available only on windows.

Events

backgroundChanged

Fired when the background property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Color The new value of background.

backgroundImageChanged

Fired when the backgroundImage property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Image The new value of backgroundImage.

baselineChanged

Fired when the baseline property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Widget|Selector The new value of baseline.

bottomChanged

Fired when the bottom property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: margin The new value of bottom.

boundsChanged

Fired when the bounds property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Bounds The new value of bounds.

centerXChanged

Fired when the centerX property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: offset The new value of centerX.

centerYChanged

Fired when the centerY property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: offset The new value of centerY.

classChanged

Fired when the class property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: string The new value of class.

classListChanged

Fired when the classList property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: string[] The new value of classList.

cornerRadiusChanged

Fired when the cornerRadius property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: number The new value of cornerRadius.

dataChanged

Fired when the data property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: object The new value of data.

dispose

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

elevationChanged

Fired when the elevation property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: number The new value of elevation.

enabledChanged

Fired when the enabled property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: boolean The new value of enabled.

fontChanged

Fired when the font property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Font The new value of font.

heightChanged

Fired when the height property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: dimension The new value of height.

highlightOnTouchChanged

Fired when the highlightOnTouch property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: boolean The new value of highlightOnTouch.

idChanged

Fired when the id property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: string The new value of id.

layoutDataChanged

Fired when the layoutData property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: LayoutData The new value of layoutData.

leftChanged

Fired when the left property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: margin The new value of left.

longpress

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

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘end’|‘cancel’ ‘start’ when the widget has been hold down long enough, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

opacityChanged

Fired when the opacity property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: number The new value of opacity.

pan

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

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panDown

Fired when a finger starts moving down.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panHorizontal

Fired when a finger starts moving left or right.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panLeft

Fired when a finger starts moving left.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panRight

Fired when a finger starts moving right.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panUp

Fired when a finger starts moving up.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

panVertical

Fired when a finger starts moving up or down.

Event Parameters

• target: this The widget the event was fired on.

• state: ‘start’|‘change’|‘end’|‘cancel’ ‘start’ when the finger starts moving, ‘change’ while the finger is moving, ‘end’ when the finger has been lifted and ‘cancel’ when the gesture has been interrupted.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

• translationX: number Current horizontal touch offset relative to the first touch.

• translationY: number Current vertical touch offset relative to the first touch.

• velocityX: number Current horizontal velocity in pixels per second.

• velocityY: number Current vertical velocity in pixels per second.

resize

Fired when the widget’s size has changed. You can use this event to apply new layoutData.

Event Parameters

• target: this The widget the event was fired on.

• height: number The height of the widget in dip.

• left: number The horizontal offset from the parent’s left edge in dip.

• top: number The vertical offset from the parent’s top edge in dip.

• width: number The width of the widget in dip.

rightChanged

Fired when the right property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: margin The new value of right.

swipeDown

Fired when a finger moves down quickly.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

swipeLeft

Fired when a finger moves left quickly.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

swipeRight

Fired when a finger moves right quickly.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

swipeUp

Fired when a finger moves up quickly.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

tap

Fired once when a finger briefly touched the widget.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number}[] Touch coordinates relative to the origin coordinates of the widget.

topChanged

Fired when the top property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: margin The new value of top.

touchCancel

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

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number, absoluteX: number, absoluteY: number}[] Touch coordinates relative to the origin coordinates of the widget.

touchEnd

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

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number, absoluteX: number, absoluteY: number}[] Touch coordinates relative to the origin coordinates of the widget.

touchMove

Fired repeatedly while swiping across the screen.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number, absoluteX: number, absoluteY: number}[] Touch coordinates relative to the origin coordinates of the widget.

touchStart

Fired when a widget is touched. See Touch Events.

Event Parameters

• target: this The widget the event was fired on.

• touches: {x: number, y: number, absoluteX: number, absoluteY: number}[] Touch coordinates relative to the origin coordinates of the widget.

transformChanged

Fired when the transform property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: Transformation The new value of transform.

visibleChanged

Fired when the visible property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: boolean The new value of visible.

widthChanged

Fired when the width property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: dimension The new value of width.

win_themeChanged

Fired when the win_theme property has changed.

Event Parameters

• target: this The widget the event was fired on.

• value: string The new value of win_theme.

See also

• Understanding layouts in Tabris.js
• Understanding gesture events in Tabris.js