Class “Observable”

Object > Observable

An Observable represents a sequence of values which may be observed. API based on the proposed Ecma TC39 Observable standard. It can be converted to an RxJS Observable via its from function.

Type: Observable<T> extends Object
Generics: T: The type of the observed value. Defaults to undefined.
Constructor: public
Singleton: No
Namespace: tabris
Direct subclasses: Listeners
JSX Support: No

See also:

TSX observable-events.tsx [► Run in Playground]
TSX observable-mutations.tsx [► Run in Playground]
TSX observable.tsx [► Run in Playground]

Constructor

new Observable(subscribe)

Parameter Type Description
subscribe SubscriptionHandler<T> Invoked whenever a new subscriber is registered. Passed an object through which values may be passed to the subscriber.

Methods

subscribe(observer)

Subscribes to this observable.

Parameter Type Description
observer PartialObserver<T> Object with some or all of the callbacks of Subscriber.

Returns: Subscription

subscribe(next, error?, complete?)

Subscribes to this observable.

Parameter Type Description
next (value) => any Callback invoked whenever the observed value changes.
error (error) => any Callback invoked when the subscription encounters an error. Optional.
complete () => any Callback invoked once when the subscription closes, either by itself or by calling unsubscribe. No other callbacks will be invoked from then on. Optional.

Returns: Subscription

Static Methods

mutations(source)

Creates an observable emitting the given source object once and then again whenever it fires property change events. It can be used with any widget, NativeObject instance, or object using @property or @prop decorators.

Events are aggregated, meaning multiple subsequent property changes may result in only one notification to the observer. It is guaranteed that this notification will occur before the next frame is rendered on screen.

The observable completes if the source object is disposed.

Limitations: The observable will not detect property changes that do not trigger change events, so plain objects, arrays, objects created by third-party libraries or instances of built-in ECMAScript types (such as Map) are not supported. Also, changes of bounds or any built-in property giving scroll offsets will not trigger the observable.

Parameter Type Description
source T  

Returns: Observable<T>

See also:

TSX observable-mutations.tsx [► Run in Playground]

SubscriptionHandler

  • JavaScript Type: Function
  • TypeScript Type: tabris.ImageLikeObject
type SubscriptionHandler<T> = (subscriber: Subscriber<T>) => TeardownLogic;

This function is passed to a Observable constructor to control the behavior of the observable. It is executed every time the subscribe method is called. It is given a Subscriber object to send “next”, “error” and “complete” messages to the respective callbacks. It may also return a teardown function.

Example:

new Observable(subscriber => {
  subscriber.next('foo');
  return {
    unsubscribe: () => doSomething()
  }
});

TeardownLogic

  • JavaScript Type: Function, Object
  • TypeScript Type: tabris.TeardownLogic
type TeardownLogic = Function | {unsubscribe: Function} | void;

A function or object with an unsubscribe method. It is called once the subscription is closed. This can be used to free up resources that were allocated by the subscription handler. For example, it may cancel a timer or de-register a listener.

Subscriber

  • JavaScript Type: Object
  • TypeScript Type: tabris.Subscriber
interface Subscriber<T> {
  closed: boolean;
  next: (value: T) => void;
  error: (value: any) => void;
  complete: () => void;
}

When calling the methods of this object the respective next, error and complete callbacks given to subscribe() will be invoked. This may happen synchronously (while the subscription handler executes) or later (i.e. asynchronously), for example in a timer.

PartialObserver

  • JavaScript Type: Object
  • TypeScript Type: tabris.PartialObserver
interface PartialObserver<T> {
  next?: (value: T) => any;
  error?: (ex: any) => void
  complete?: () => any
}

A plain object to be passed to the subscribe() method. It may implement some or all of the methods next(), error() and complete(). Alternatively, the subscribe() method may be passed some or all of these callbacks directly.

Subscription

  • JavaScript Type: Object
  • TypeScript Type: tabris.Subscription
interface Subscription {
  readonly closed: boolean;
  unsubscribe: () => void;
}

This object is returned by the subscribe() method. Calling its unsubscribe() method ends the subscription. The callbacks will not by invoked any more and any resources associated with the subscription will be freed up.