WidgetCollection

A WidgetCollection is an array-like object representing a set of widgets, as returned by the widget methods children and find.

Import this type with “const {WidgetCollection} = require('tabris');”

A WidgetCollection is an array-like object that represents any number of widgets - it can also be empty.

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.

Example:

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

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.

Methods

animate(properties, options)

Parameters:

• properties: {transform?: Transformation, opacity?: number}
  • the properties and target values to animate.
• options: AnimationOptions
  • configures the animation itself.

Animates all widgets in this collection.

appendTo(parent)

Parameters:

• parent: Composite
  • the parent widget to append to.

Returns: this

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

children(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

Returns a collection containing all children of all widgets in this collection that match the given selector.

dispose()

Disposes all widgets in this collection.

filter(selector)

Parameters:

• selector: Selector
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

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

find(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: WidgetCollection

Returns a collection containing all descendants of all widgets in this collection that match the given selector.

first(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: Widget

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

forEach(callback)

Parameters:

• callback: (widget: Widget, index: number, collection: WidgetCollection) => void
  • the function to call for each widget. The arguments are: widget, index, collection

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

get(property)

Parameters:

• property: string

Returns: any

Returns the value of the given property of the first widget in this collection.

includes(widget)

Parameters:

• widget: Widget
  • the widget to search in the collection.

Returns: boolean

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

indexOf(widget)

Parameters:

• widget: Widget
  • the widget to locate in the collection.

Returns: number

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

last(selector)

Parameters:

• selector: Selector [Optional]
  • a selector expression or a predicate function to filter the results.

Returns: Widget

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

off(event, listener, context)

Parameters:

• event: string
• listener: Function
• context: this [Optional]

Returns: this

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

on(event, listener, context)

Parameters:

• event: string
• listener: Function
• context: this [Optional]
  • in the listener function, this will point to this object.

Returns: this

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

once(event, listener, context)

Parameters:

• event: string
• listener: Function
• context: this [Optional]
  • in the listener function, this will point to this object.

Returns: this

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

parent()

Returns: WidgetCollection

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

set(property, value)

Parameters:

• property: string
• value: any

Returns: this

Sets the given property on all widgets in this collection. See also Widget.set().

set(properties)

Parameters:

• properties: object

Returns: this

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

toArray()

Returns: Widget[]

Returns an Array containing all widgets in the collection.

trigger(event, …params)

Parameters:

• event: string
• …params: any[]

Returns: this

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

Properties

length

read-only
Type: number

Contains the number of widgets in the collection.