Class “Widget”

Object > NativeObject > Widget

Base class for all widgets

Constructor	protected
Singleton	No
Namespace	tabris
Direct subclasses	Action, ActivityIndicator, Button, CheckBox, Composite, ImageView, Picker, ProgressBar, RadioButton, Slider, Switch, TextInput, TextView, ToggleButton, Video, WebView
JSX support	No

See also:

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

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.

Parameter	Type	Optional	Description
properties	{transform?: Transformation, opacity?: number}	No	The properties and target values to animate.
options	AnimationOptions	No	Configures the animation itself.

Returns Promise<any>

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.

Parameter	Type	Optional	Description
parent	Composite	No

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 void

insertAfter(widget)

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

Parameter	Type	Optional	Description
widget	Widget	No

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.

Parameter	Type	Optional	Description
widget	Widget	No

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.

Parameter	Type	Optional	Description
selector	Selector	No	A selector expression or a predicate function to filter the results.

Returns Result

siblings(selector?)

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

Parameter	Type	Optional	Description
selector	Selector	Yes	A selector expression or a predicate function to filter the results.

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.

Parameter	Type	Optional	Description
parent	Composite	No
index	number	Yes

Returns void

Properties

[JSX.jsxFactory]

This function is called to create JSX widget elements. You may override it in your own subclass to create custom JSX behavior. The function is not called with any context, i.e. this is not available.

Type	JSX.JsxFactory
Settable	No
Change events	No

This property can only be set via constructor or JSX. Once set, it cannot change anymore.

absoluteBounds

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

Type	Bounds
Settable	No
Change events	No

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.

Type	LinearGradientValue | ColorValue | ImageValue
Settable	Yes
Change events	Yes

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.

Type	SiblingReferenceValue | 'auto' | true
Default	'auto'
Settable	Yes
Change events	Yes

bottom

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

Type	ConstraintValue
Default	'auto'
Settable	Yes
Change events	Yes

bounds

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

Type	Bounds
Settable	No
Change events	Yes

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.

Type	Offset | 'auto' | true
Default	'auto'
Settable	Yes
Change events	Yes

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.

Type	Offset | 'auto' | true
Default	'auto'
Settable	Yes
Change events	Yes

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.

Type	string
Settable	Yes
Change events	Yes

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.

Type	string[]
Settable	Yes
Change events	Yes

cornerRadius

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

Type	number
Settable	Yes
Change events	Yes

See also:

JSX widget-cornerradius.jsx

data

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;

Type	object
Settable	No
Change events	No

This property can only be set via constructor or JSX. Once set, it cannot change anymore.

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.

Type	number
Settable	Yes
Change events	Yes

See also:

JSX widget-elevation.jsx

enabled

Whether the widget can be interacted with.

Type	boolean
Default	true
Settable	Yes
Change events	Yes

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().

Type	boolean
Default	false
Settable	Yes
Change events	Yes

height

The height of the widget.

Type	Dimension | 'auto'
Default	'auto'
Settable	Yes
Change events	Yes

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.

Type	boolean
Default	false
Settable	Yes
Change events	Yes

See also:

JSX widget-highlightontouch.jsx

id

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

Type	string
Settable	Yes
Change events	Yes

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.0/api/LayoutData.html#stretch), stretchX and [stretchY](/3.0/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/>

Type	LayoutDataValue
Default	LayoutData
Settable	Yes
Change events	Yes

left

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

Type	ConstraintValue
Default	'auto'
Settable	Yes
Change events	Yes

opacity

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

Type	number
Default	1
Settable	Yes
Change events	Yes

padding

Additional space to add inside the widgets bounds.

Type	BoxDimensions | null
Settable	On creation
Change events	No

This property can only be set via constructor or JSX. Once set, it cannot change anymore.See also:

JSX widget-padding.jsx

right

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

Type	ConstraintValue
Default	'auto'
Settable	Yes
Change events	Yes

top

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

Type	ConstraintValue
Default	'auto'
Settable	Yes
Change events	Yes

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.

Type	Transformation
Settable	Yes
Change events	Yes

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.

Type	boolean
Default	true
Settable	Yes
Change events	Yes

width

The width of the widget.

Type	Dimension | 'auto'
Default	'auto'
Settable	Yes
Change events	Yes

Events

tap

Fired once when a finger briefly touched the widget.

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

longPress

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

Parameter	Type	Description
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.

See also:

JS widget-longpress-to-drag.js

pan

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

Parameter	Type	Description
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.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

swipeUp

Fired when a finger moves up quickly.

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

swipeDown

Fired when a finger moves down quickly.

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

swipeLeft

Fired when a finger moves left quickly.

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

swipeRight

Fired when a finger moves right quickly.

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

touchStart

Fired when a widget is touched. See Touch Events.

Parameter	Type	Description
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.

Parameter	Type	Description
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.

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

touchCancel

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

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

resize

Fired when the widget’s size has changed.

Parameter	Type	Description
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.

dispose

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

Change Events

idChanged

Fired when the id property has changed.

Parameter	Type	Description
value	string	The new value of id.

classChanged

Fired when the class property has changed.

Parameter	Type	Description
value	string	The new value of class.

classListChanged

Fired when the classList property has changed.

Parameter	Type	Description
value	string[]	The new value of classList.

enabledChanged

Fired when the enabled property has changed.

Parameter	Type	Description
value	boolean	The new value of enabled.

excludeFromLayoutChanged

Fired when the excludeFromLayout property has changed.

Parameter	Type	Description
value	boolean	The new value of excludeFromLayout.

visibleChanged

Fired when the visible property has changed.

Parameter	Type	Description
value	boolean	The new value of visible.

layoutDataChanged

Fired when the layoutData property has changed.

Parameter	Type	Description
value	LayoutDataValue	The new value of layoutData.

leftChanged

Fired when the left property has changed.

Parameter	Type	Description
value	ConstraintValue	The new value of left.

rightChanged

Fired when the right property has changed.

Parameter	Type	Description
value	ConstraintValue	The new value of right.

topChanged

Fired when the top property has changed.

Parameter	Type	Description
value	ConstraintValue	The new value of top.

bottomChanged

Fired when the bottom property has changed.

Parameter	Type	Description
value	ConstraintValue	The new value of bottom.

widthChanged

Fired when the width property has changed.

Parameter	Type	Description
value	Dimension | 'auto'	The new value of width.

heightChanged

Fired when the height property has changed.

Parameter	Type	Description
value	Dimension | 'auto'	The new value of height.

centerXChanged

Fired when the centerX property has changed.

Parameter	Type	Description
value	Offset | 'auto' | true	The new value of centerX.

centerYChanged

Fired when the centerY property has changed.

Parameter	Type	Description
value	Offset | 'auto' | true	The new value of centerY.

baselineChanged

Fired when the baseline property has changed.

Parameter	Type	Description
value	SiblingReferenceValue | 'auto' | true	The new value of baseline.

elevationChanged

Fired when the elevation property has changed.

Parameter	Type	Description
value	number	The new value of elevation.

cornerRadiusChanged

Fired when the cornerRadius property has changed.

Parameter	Type	Description
value	number	The new value of cornerRadius.

boundsChanged

Fired when the bounds property has changed.

Parameter	Type	Description
value	Bounds	The new value of bounds.

backgroundChanged

Fired when the background property has changed.

Parameter	Type	Description
value	LinearGradientValue | ColorValue | ImageValue	The new value of background.

opacityChanged

Fired when the opacity property has changed.

Parameter	Type	Description
value	number	The new value of opacity.

transformChanged

Fired when the transform property has changed.

Parameter	Type	Description
value	Transformation	The new value of transform.

highlightOnTouchChanged

Fired when the highlightOnTouch property has changed.

Parameter	Type	Description
value	boolean	The new value of highlightOnTouch.