Class “WidgetCollection”

Object > WidgetCollection

A WidgetCollection is an array-like object representing a set of widgets, as returned by the widget methods children and find. It combines a subset of the JavaScript Array API with a subset of the Tabris.js Widget API. Like an array, the widgets within the collection may be accessed directly using the [index] syntax. The number of widgets is stored in the length field. Instances of WidgetCollection are immutable.

Calls to set or animate change the given properties for all widgets in the collection. Similarly, the on, off and once methods will add/remove the given listener to/from all widgets. When get is used, the value of the first widget in the collection is returned.

WidgetCollection can also in JSX as a means of creating a group of widgets to append to the same parent. To shorten this common use case the WidgetCollection is also available as the alias $. This alias still needs to be imported from the tabris module though.

TypeScript type WidgetCollection<T extends Widget = Widget> extends Object
Constructor public
Singleton No
Namespace tabris
Direct subclasses None
JSX support No

Example

let children = page.children();
for (let child of children) {
  console.log(child.id);
}

As a JSX element via the $ alias:

import {contentView, $, TextView} from 'tabris';

contentView.append(
  <$>
    <TextView>Hello</TextView>
    <TextView top='prev()'>World</TextView>
  </$>
);

Constructor

new WidgetCollection(widgets?)

Parameter Type Optional Description
widgets Widget[] Yes Array of widgets to include in the WidgetCollection

Methods

animate(properties, options)

Animates all widgets in this collection.

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 void

appendTo(parent)

Appends all widgets in this collection to the given parent widget.

Parameter Type Optional Description
parent Composite No The parent widget to append to.

Returns this

children(selector?)

Returns a collection containing all children of all widgets in this collection 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

concat(…items)

Returns a new WidgetCollection containing all widgets in this collection and those given as arguments.

Parameter Type Optional Description
…items Array<T | T[] | WidgetCollection<T>> No  

Returns WidgetCollection

detach()

Detaches all widgets in this collection from their parent.

Returns void

dispose()

Disposes all widgets in this collection.

Returns void

filter(selector)

Returns a new WidgetCollection containing all widgets in this collection that match the given selector.

Parameter Type Optional Description
selector Selector<T, Result> No A selector expression or a predicate function to filter the results.

Returns WidgetCollection

first(selector?)

Returns the first widget in the collection that is matched by the selector. Without selector, it is the same as collection[0].

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

Returns Widget

forEach(callback)

Calls the given callback function once for each widget in the collection.

Parameter Type Optional Description
callback (widget: Widget, index: number, collection: WidgetCollection) => void No The function to call for each widget. The arguments are: widget, index, collection

Returns void

includes(widget)

Returns true if the given widget is included in the collection, false otherwise.

Parameter Type Optional Description
widget Widget No The widget to search in the collection.

Returns boolean

indexOf(widget)

Returns the index of the given widget within the collection, or -1 if the widget is not present.

Parameter Type Optional Description
widget Widget No The widget to locate in the collection.

Returns number

last(selector?)

Returns the last widget in the collection that is matched by the selector. Without selector, it is the same as collection[collection.length - 1].

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

Returns Widget

last(constructor)

Returns the last widget in the collection that is an instance of the given class.

Parameter Type Optional Description
constructor { new (...args: any[]): U } | undefined No A class to filter the results.

Returns U

map(callback)

Calls the given callback function once for each widget in the collection and returns an array with the return values of each call.

Parameter Type Optional Description
callback (widget: Widget, index: number, collection: WidgetCollection) => void No The function to call for each widget. The arguments are: widget, index, collection

Returns Array

off(event, listener, context?)

Removes the given listener from all widgets in this collection. See also Widget.off().

Parameter Type Optional Description
event string No  
listener Function No  
context this Yes  

Returns this

on(event, listener, context?)

Adds the given listener to all widgets in this collection. See also Widget.on().

Parameter Type Optional Description
event string No  
listener Function No  
context this Yes In the listener function, this will point to this object.

Returns this

once(event, listener, context?)

Adds the given listener for single execution on all widgets in this collection. See also Widget.once().

Parameter Type Optional Description
event string No  
listener Function No  
context this Yes In the listener function, this will point to this object.

Returns this

only(selector?)

Returns the only widget in the collection that is matched by the selector. If there is more or less than one match the method throws en Error. Without a selector the widget collection needs to have exactly one entry.

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

Returns Widget

parent()

Returns a collection containing all direct parents of the widgets in this collection.

Returns WidgetCollection

set(properties)

Sets all key-value pairs in the properties object on all widgets in this collection. See also Widget.set().

Parameter Type Optional Description
properties object No  

Returns this

slice(start?, end?)

Returns a new WidgetCollection containing a section of this collection.

Parameter Type Optional Description
start number Yes The beginning of the specified portion of the collection.
end number Yes The end of the specified portion of the collection.

Returns WidgetCollection

toArray()

Returns an Array containing all widgets in the collection.

Returns Widget[]

trigger(event, …params)

Triggers an event of the given type on all widgets in this collection. See also Widget.trigger()

Parameter Type Optional Description
event string No  
…params any[] No  

Returns this

Properties

host

The widget this WidgetCollection was created from. Corresponds to the ‘:host’ selector.

Type Widget
Settable No
Change events No

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

length

Contains the number of widgets in the collection.

Type number
Settable No
Change events No

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