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.
| Type: | WidgetCollection<WidgetType> extends Object |
| Generics: | WidgetType: The common type of all widgets in this collection. Must be a subclass of Widget and defaults to Widget. |
| Constructor: | public |
| Singleton: | No |
| Namespace: | tabris |
| Direct subclasses: | None |
| JSX Support: | Element: <WidgetCollection/>Parent Elements: Not supported Child Elements: Not Supported |
Examples
JavaScript
import {Page} from 'tabris';
const children = $(Page).first().children();
for (const child of children) {
console.log(child.id);
}
JSX
WidgetCollection 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 | Description |
|---|---|---|
| widgets | Widget[] |
Array of widgets to include in the WidgetCollection Optional. |
Methods
animate(properties, options)
Animates all widgets in this collection.
| Parameter | Type | Description |
|---|---|---|
| properties | { |
The properties and target values to animate. |
| options | AnimationOptions |
Configures the animation itself. |
Returns: undefined
appendTo(parent)
Appends all widgets in this collection to the given parent widget.
| Parameter | Type | Description |
|---|---|---|
| parent | Composite |
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 | Description |
|---|---|---|
| selector | Selector |
A selector expression or a predicate function to filter the results. Optional. |
Returns: WidgetCollection
concat()
Returns a clone of this WidgetCollection containing all widgets in this collection.
Returns: WidgetCollection<WidgetType>
concat(…items)
Returns a new WidgetCollection containing all widgets in this collection and those given as arguments.
| Parameter | Type | Description |
|---|---|---|
| …items | Array<Widget |
Returns: WidgetCollection<Widget>
detach()
Detaches all widgets in this collection from their parent.
Returns: undefined
dispose()
Disposes all widgets in this collection.
Returns: undefined
filter(selector)
Returns a new WidgetCollection containing all widgets in this collection that match the given selector.
| Parameter | Type | Description |
|---|---|---|
| selector | Selector<WidgetType, Result> |
A selector expression or a predicate function to filter the results. |
Returns: WidgetCollection<WidgetType>
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 | Description |
|---|---|---|
| selector | Selector |
A selector expression or a predicate function to filter the results. Optional. |
Returns: WidgetType
forEach(callback)
Calls the given callback function once for each widget in the collection.
| Parameter | Type | Description |
|---|---|---|
| callback | (widget, index, WidgetCollection<WidgetType>) => void |
The function to call. |
Returns: undefined
includes(widget)
Returns true if the given widget is included in the collection, false otherwise.
| Parameter | Type | Description |
|---|---|---|
| widget | Widget |
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 | Description |
|---|---|---|
| widget | Widget |
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 | Description |
|---|---|---|
| selector | Selector |
A selector expression or a predicate function to filter the results. Optional. |
Returns: WidgetType
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 | Description |
|---|---|---|
| callback | (widget, index, WidgetCollection<WidgetType>) => any |
The function to call for each widget. |
Returns: any[]
off(event, listener, context?)
Removes the given listener from all widgets in this collection. See also Widget.off().
| Parameter | Type | Description |
|---|---|---|
| event | string |
|
| listener | Function |
|
| context | this |
Optional. |
Returns: this
on(event, listener, context?)
Adds the given listener to all widgets in this collection. See also Widget.on().
| Parameter | Type | Description |
|---|---|---|
| event | string |
|
| listener | Function |
|
| context | this |
In the listener function, this will point to this object. Optional. |
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 | Description |
|---|---|---|
| event | string |
|
| listener | Function |
|
| context | this |
In the listener function, this will point to this object. Optional. |
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 | Description |
|---|---|---|
| selector | Selector |
A selector expression or a predicate function to filter the results. Optional. |
Returns: WidgetType
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 | Description |
|---|---|---|
| properties | Properties<WidgetType> |
Returns: this
slice(start?, end?)
Returns a new WidgetCollection containing a section of this collection.
| Parameter | Type | Description |
|---|---|---|
| start | number |
The beginning of the specified portion of the collection. Optional. |
| end | number |
The end of the specified portion of the collection. Optional. |
Returns: WidgetCollection<WidgetType>
toArray()
Returns an Array containing all widgets in the collection.
Returns: WidgetType[]
trigger(type, eventData?)
Triggers an event of the given type on all widgets in this collection and passes the fields of the given object to all listeners`
| Parameter | Type | Description |
|---|---|---|
| type | string |
The type of event to trigger |
| eventData | object |
The data to pass to listener functions. Optional. |
Returns: this
Properties
host
The widget this WidgetCollection was created from. Corresponds to the ‘:host’ selector.
| Type: | Widget |
| Settable: | 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 |
This property can only be set via constructor. Once set, it cannot change anymore.
