Widget API

API supported by all widgets. Includes Events API, Properties API

Methods

animate(properties, options)

Parameters:

  • properties: Object, the properties and target values to animate.
  • options: Object, configures the animation itself.

Starts an animation that transforms the given properties from their current values to the given ones. Supported properties are transform and opacity. Supported options are:

  • delay - time until the animation starts in ms, defaults to 0
  • duration - in ms,
  • easing - one of linear, ease-in, ease-out, ease-in-out
  • repeat - number of times to repeat the animation, defaults to 0
  • reverse - true to alternate the direction of the animation on every repeat.
  • name - no effect, but will be given in animation events

appendTo(parent)

Parameters:

Returns: Widget

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: Widget

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

children()

Parameters:

Returns: WidgetCollection

Returns a (possibly empty) collection of all children of this widget.

children(selector)

Parameters:

Returns: WidgetCollection

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

dispose()

Parameters:

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

Parameters:

Returns: WidgetCollection

Returns a (possibly empty) collection of all descendants of this widget.

find(selector)

Parameters:

Returns: WidgetCollection

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

insertAfter(widget)

Parameters:

Returns: Widget

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:

Returns: Widget

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

isDisposed()

Parameters:

Returns: boolean

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

parent()

Parameters:

Returns: Widget

Returns the parent of this widget.

Fields

cid

Type: string

An application-wide unique identifier automatically assigned to all widgets on creation. Do not change it.

id

Type: string

Direct access to the value of the property of the same name. May be used instead of widget.get("id"); Do not use this field to change the value, instead use widget.set("id", id);.

type

Type: string

The exact string that was used to create this widget using the tabris.create method.

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

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

Type: Bounds

The actual location and size of the widget, relative to its parent. This property is read-only.

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.

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 entire widget should be highlighted while touched.

id

Type: string

A string to identify the widget by using selectors. Id’s 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, supported values: 0..1, default: 1

Opacity of the entire widget. Can be used for fade animations.

Type: margin

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

textColor

Type: Color

Text color of the 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.

Events

“animationend” (widget, options)

Parameters:

“animationstart” (widget, options)

Parameters:

“change:{property}” (widget, value, options)

Parameters:

  • widget: Widget
  • value: mixed, the new value of this given property.
  • options: Object, this is the options object given to the set method.

Fired when the given property has changed. Change events for specific properties will only be documented separately if they may be triggered without calling set.

“dispose” (widget)

Parameters:

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

“longpress” (widget, gesture)

Parameters:

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

“pan” (widget, gesture)

Parameters:

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

“pan:down” (widget, gesture)

Parameters:

Fired when a finger starts moving down.

“pan:left” (widget, gesture)

Parameters:

Fired when a finger starts moving left.

“pan:right” (widget, gesture)

Parameters:

Fired when a finger starts moving right.

“pan:up” (widget, gesture)

Parameters:

Fired when a finger starts moving up.

“resize” (widget, bounds, options)

Parameters:

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

“swipe:down” (widget, gesture)

Parameters:

Fired when a finger moves down quickly.

“swipe:left” (widget, gesture)

Parameters:

Fired when a finger moves left quickly.

“swipe:right” (widget, gesture)

Parameters:

Fired when a finger moves right quickly.

“swipe:up” (widget, gesture)

Parameters:

Fired when a finger moves up quickly.

“tap” (widget, gesture)

Parameters:

Fired once when a finger briefly touched the widget.

“touchcancel” (widget, gesture)

Parameters:

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

“touchend” (widget, gesture)

Parameters:

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

“touchmove” (widget, gesture)

Parameters:

Fired repeatedly while swiping across the screen.

“touchstart” (widget, gesture)

Parameters:

Fired when a widget is touched. See Touch Events.

See also

See Also

Get involved

Help us improve Tabris.js!

Install the app

Use the Tabris.js app to try examples and run your own snippets.