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.

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 {
  transform: Transformation, // optional
  opacity: number // optional
}
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
| Widget[]
| WidgetCollection>
 

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.