Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

# Builder

*** ** * ** ***

```
class Builder
```

|---|---|
| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||
| ↳ | [android.hardware.lights.MultiLightEffect.Builder](https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#) |

Builder for `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect` objects.

## Summary

| Public constructors ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#Builder()()` <br /> |

| Public methods ||
|---|---|
| [MultiLightEffect.Builder](https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#) | `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#addLightSequence(android.hardware.lights.Light,%20android.hardware.lights.ColorSequence)(light: https://developer.android.com/reference/kotlin/android/hardware/lights/Light, colorSequence: https://developer.android.com/reference/kotlin/android/hardware/lights/ColorSequence)` Adds a new light and its corresponding sequence to the effect. |
| [MultiLightEffect](https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect) | `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#build()()` Builds the light effect. |
| [MultiLightEffect.Builder](https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#) | `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#setIterations(kotlin.Int)(iterations: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)` Number of times that the effect should be played in a loop. |
| [MultiLightEffect.Builder](https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#) | `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#setPreemptive(kotlin.Boolean)(preemptive: https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html)` Sets whether this effect will preempt any previous effect / state currently active on the light. |

## Public constructors

### Builder

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
Builder()
```

## Public methods

### addLightSequence

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
fun addLightSequence(
    light: Light, 
    colorSequence: ColorSequence
): MultiLightEffect.Builder
```

Adds a new light and its corresponding sequence to the effect.

| Parameters ||
|---|---|
| `light` | [Light](https://developer.android.com/reference/kotlin/android/hardware/lights/Light): the light that will play the sequence. This value cannot be `null`. |
| `colorSequence` | [ColorSequence](https://developer.android.com/reference/kotlin/android/hardware/lights/ColorSequence): the sequence of colors and their timing. This value cannot be `null`. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#` | This value cannot be `null`. |

| Exceptions ||
|---|---|
| `java.lang.IllegalArgumentException` | if the light does not support animations. |

### build

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
fun build(): MultiLightEffect
```

Builds the light effect.

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect` | A MultiLightEffect with the configuration and sequences configured. This value cannot be `null`. |

| Exceptions ||
|---|---|
| `java.lang.IllegalStateException` | if no light-sequence pair has been provided. |

### setIterations

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
fun setIterations(iterations: Int): MultiLightEffect.Builder
```

Number of times that the effect should be played in a loop.

By default, the builder configures this value to 1 for a single run of the effect.

A value of 0 indicates the effect should repeat indefinitely until a new effect or state is provided for the light or until the light is turned off.

If the effect has an initial state (delay = 0 for the first control point) the initial state will only be applied during the first iteration and all other iterations will ignore the initial value.

| Parameters ||
|---|---|
| `iterations` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): number of times the effect should be played. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#` | This value cannot be `null`. |

### setPreemptive

Added in [API level 37](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)

```
fun setPreemptive(preemptive: Boolean): MultiLightEffect.Builder
```

Sets whether this effect will preempt any previous effect / state currently active on the light.

By default, the builder sets this value to true and the effect is preemptive.

When preemptive=false AND the previous light state is a:
- Permanent color: the playback will start immediately. Preemptive has no effect.
- Non-infinite effect: the new effect will start after the previous effect ends all of its iterations.
- Infinite effect: the playback will start after the current iteration of the effect finishes. When preemptive=true the effect is applied immediately regardless of previous state.

  Even when the effect preempts an existing state, the effect may not necessarily provide an initial state and the first control point may be relatively far in the future. Applications can make use of these conditions to create a fading effect between the last known state of the light and the new effect.

  When creating fading effects, the following applies:
- If the last known state is not an effect: last color becomes the starting color for the interpolator.
- If the last known state is an effect: the last interpolated value becomes the starting color for the interpolator. The system has a maximum of one non-preemptive event in the queue per light session. If an effect A is playing and the application requests two non-preemptive events (B and C) before A is done playing, only C will be kept and played after A, and B will be discarded.

| Parameters ||
|---|---|
| `preemptive` | [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html): true to play immediately or false wait for the previous effect to finish. |

| Return ||
|---|---|
| `https://developer.android.com/reference/kotlin/android/hardware/lights/MultiLightEffect.Builder#` | This value cannot be `null`. |