Class Observable

Extension methods for working with IObservable in the context of the Input System.

Inheritance
object
Observable
Namespace: UnityEngine.InputSystem.Utilities
Assembly: Unity.InputSystem.dll
Syntax
public static class Observable

Methods

CallOnce<TValue>(IObservable<TValue>, Action<TValue>)

Call an action for the first value in the given stream of values and then automatically dispose the observer.

Declaration
public static IDisposable CallOnce<TValue>(this IObservable<TValue> source, Action<TValue> action)
Parameters
Type Name Description
IObservable<TValue> source

An observable source of values.
Action<TValue> action

Action to call for the first value that arrives from the source.
Returns
Type Description
IDisposable

A handle to the subscription. Call Dispose to unsubscribe at any time.
Type Parameters
Name Description
TValue

Type of values delivered by the source.
Remarks
InputSystem.onEvent
    .Where(e => e.type == DeviceConfigurationEvent.typeStatic)
    .CallOnce(_ => Debug.Log("Device configuration changed"));
Exceptions
Type Condition
ArgumentNullException

source is null -or- action is null.
See Also

Call<TValue>(IObservable<TValue>, Action<TValue>)

Call the given callback for every value generated by the given observable stream of values.

Declaration
public static IDisposable Call<TValue>(this IObservable<TValue> source, Action<TValue> action)
Parameters
Type Name Description
IObservable<TValue> source

An observable stream of values.
Action<TValue> action

A callback to invoke for each value.
Returns
Type Description
IDisposable

A handle to the subscription. Call Dispose to unsubscribe at any time.
Type Parameters
Name Description
TValue
Remarks
InputSystem.onEvent
    .Where(e => e.type == DeviceConfigurationEvent.typeStatic)
    .Call(_ => Debug.Log("Device configuration changed"));
Exceptions
Type Condition
ArgumentNullException

source is null -or- action is null.
See Also

ForDevice(IObservable<InputEventPtr>, InputDevice)

From an observable stream of events, take only those that are for the given device.

Declaration
public static IObservable<InputEventPtr> ForDevice(this IObservable<InputEventPtr> source, InputDevice device)
Parameters
Type Name Description
IObservable<InputEventPtr> source

An observable stream of events.
InputDevice device

Device to filter events for.
Returns
Type Description
IObservable<InputEventPtr>

An observable stream of events for the given device.
Remarks

Each event has an deviceId associated with it. This is used to match against the deviceId of device.

InputSystem.onEvent
    .ForDevice(Mouse.current)
    .Call(e => Debug.Log($"Mouse event: {e}");
Exceptions
Type Condition
ArgumentNullException

source is null.
See Also

ForDevice<TDevice>(IObservable<InputEventPtr>)

From an observable stream of events, take only those that are for a device of the given type.

Declaration
public static IObservable<InputEventPtr> ForDevice<TDevice>(this IObservable<InputEventPtr> source) where TDevice : InputDevice
Parameters
Type Name Description
IObservable<InputEventPtr> source

An observable stream of events.
Returns
Type Description
IObservable<InputEventPtr>

An observable stream of events for devices of type TDevice.
Type Parameters
Name Description
TDevice

Type of device (such as Gamepad) to filter for.
Remarks
InputSystem.onEvent
    .ForDevice<Gamepad>()
    .Where(e => e.HasButtonPress())
    .CallOnce(e => PlayerInput.Instantiate(myPrefab,
        pairWithDevice: InputSystem.GetDeviceById(e.deviceId)));
Exceptions
Type Condition
ArgumentNullException

source is null.
See Also

SelectMany<TSource, TResult>(IObservable<TSource>, Func<TSource, IEnumerable<TResult>>)

Transform each value in an observable stream of values such that one value is translated to zero or more values of a new type.

Declaration
public static IObservable<TResult> SelectMany<TSource, TResult>(this IObservable<TSource> source, Func<TSource, IEnumerable<TResult>> filter)
Parameters
Type Name Description
IObservable<TSource> source

The stream of observable values.
Func<TSource, IEnumerable<TResult>> filter

Function to transform each value in the stream into zero or more new values.
Returns
Type Description
IObservable<TResult>

A new observable of values of the new result type.
Type Parameters
Name Description
TSource

Type of source values to transform from.
TResult

Type of target values to transform to.
Remarks
InputSystem.onEvent
    .SelectMany(eventPtr => eventPtr.GetAllButtonPresses())
    .Call(ctrl =>
        Debug.Log($"Button {ctrl} pressed"));
Exceptions
Type Condition
ArgumentNullException

source is null -or- filter is null.
See Also

Select<TSource, TResult>(IObservable<TSource>, Func<TSource, TResult>)

Transform each value in an observable stream of values into a value of a different type.

Declaration
public static IObservable<TResult> Select<TSource, TResult>(this IObservable<TSource> source, Func<TSource, TResult> filter)
Parameters
Type Name Description
IObservable<TSource> source

The stream of observable values.
Func<TSource, TResult> filter

Function to transform values in the stream.
Returns
Type Description
IObservable<TResult>

A new observable of values of the new result type.
Type Parameters
Name Description
TSource

Type of source values to transform from.
TResult

Type of target values to transform to.
Remarks
InputSystem.onEvent
    .Select(eventPtr => eventPtr.GetFirstButtonPressOrNull())
    .Call(ctrl =>
    {
        if (ctrl != null)
            Debug.Log(ctrl);
    });
Exceptions
Type Condition
ArgumentNullException

source is null -or- filter is null.
See Also

Take<TValue>(IObservable<TValue>, int)

Take up to the first N values from the given observable stream of values.

Declaration
public static IObservable<TValue> Take<TValue>(this IObservable<TValue> source, int count)
Parameters
Type Name Description
IObservable<TValue> source

An observable source of values.
int count

The maximum number of values to take from the source.
Returns
Type Description
IObservable<TValue>

A stream of up to count values.
Type Parameters
Name Description
TValue

Types of values to read from the stream.
Exceptions
Type Condition
ArgumentNullException

source is null.
ArgumentOutOfRangeException

count is negative.

Where<TValue>(IObservable<TValue>, Func<TValue, bool>)

Filter a stream of observable values by a predicate.

Declaration
public static IObservable<TValue> Where<TValue>(this IObservable<TValue> source, Func<TValue, bool> predicate)
Parameters
Type Name Description
IObservable<TValue> source

The stream of observable values.
Func<TValue, bool> predicate

Filter to apply to the stream. Only values for which the predicate returns true are passed on to OnNext of the observer.
Returns
Type Description
IObservable<TValue>

A new observable that is filtered by the given predicate.
Type Parameters
Name Description
TValue

Value type for the observable stream.
Remarks
InputSystem.onEvent
    .Where(e => e.HasButtonPress())
    .Call(e => Debug.Log("Press"));
Exceptions
Type Condition
ArgumentNullException

source is null -or- predicate is null.
See Also