Class “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.
