# FocusMeteringAction.Builder

Artifact: [androidx.camera:camera-core](https://developer.android.com/jetpack/androidx/releases/camera) [View Source](https://cs.android.com/search?q=file:androidx/camera/core/FocusMeteringAction.java+class:androidx.camera.core.FocusMeteringAction.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

*** ** * ** ***


```
class FocusMeteringAction.Builder
```

<br />

*** ** * ** ***

The builder used to create the `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#Builder(androidx.camera.core.MeteringPoint)(point: https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint)` Creates a Builder from a `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with default mode `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#Builder(androidx.camera.core.MeteringPoint,int)(point: https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint, meteringMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Creates a Builder from a `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` and MeteringMode. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint)(point: https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint)` Adds another `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with default metering mode `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#addPoint(androidx.camera.core.MeteringPoint,int)(point: https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint, meteringMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Adds another `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with specified meteringMode. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#build()()` Builds the `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction` instance. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#disableAutoCancel()()` Disables the auto-cancel. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#setAutoCancelDuration(long,java.util.concurrent.TimeUnit)(duration: @https://developer.android.com/reference/kotlin/androidx/annotation/IntRange(from = 1) https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, timeUnit: https://developer.android.com/reference/java/util/concurrent/TimeUnit.html)` Sets the auto-cancel duration. |
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)(lockingMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Sets the locking mode. |

## Public constructors

### Builder

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
Builder(point: MeteringPoint)
```

Creates a Builder from a `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with default mode `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`.

The default locking mode is `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`. Use `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)` to lock AE or AWB as well.

### Builder

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
Builder(point: MeteringPoint, meteringMode: Int)
```

Creates a Builder from a `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` and MeteringMode.

Metering mode is a combination of flags consisting of `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. This combination indicates whether the `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` is used to set AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region.

The default locking mode is `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`. Use `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder#setLockingMode(int)` to lock AE or AWB as well.

## Public functions

### addPoint

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun addPoint(point: MeteringPoint): FocusMeteringAction.Builder
```

Adds another `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with default metering mode `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()` \| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`.

The points added here will be appended in order after the point set in builder constructor.

If more points are added than what current device supports for AF/AE/AWB, only the first point and then in order up to the number of points supported on the device will be enabled.

If none of the points is supported on the device, this `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction` will cause `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` to fail.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` |   |

### addPoint

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun addPoint(point: MeteringPoint, meteringMode: Int): FocusMeteringAction.Builder
```

Adds another `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` with specified meteringMode.

Metering mode is a combination of flags consisting of `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. This combination indicates whether the `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` is used to set AF(Auto Focus) region, AE(Auto Exposure) region or AWB(Auto White Balance) region.

The points added here will be appended in order after the point set in builder constructor.

If more points are added than what current device supports for AF/AE/AWB, only the first point and then in order up to the number of points supported on the device will be enabled.

If none of the points is supported on the device, this `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction` will cause `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` to fail.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` |   |

### build

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun build(): FocusMeteringAction
```

Builds the `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction` instance.

### disableAutoCancel

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun disableAutoCancel(): FocusMeteringAction.Builder
```

Disables the auto-cancel.

### setAutoCancelDuration

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/camera#1.0.0)

```
fun setAutoCancelDuration(duration: @IntRange(from = 1) Long, timeUnit: TimeUnit): FocusMeteringAction.Builder
```

Sets the auto-cancel duration. After set, `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#cancelFocusAndMetering()` will be called in specified duration. By default, auto-cancel is enabled with 5 seconds duration. The duration must be greater than or equal to 1 otherwise it will throw a `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`.

### setLockingMode

Added in [1.7.0-rc02](https://developer.android.com/jetpack/androidx/releases/camera#1.7.0-rc02)

```
fun setLockingMode(lockingMode: Int): FocusMeteringAction.Builder
```

Sets the locking mode.

Locking mode is a combination of flags consisting of `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. This combination indicates whether the AF (Auto Focus), AE (Auto Exposure) or AWB (Auto White Balance) should be locked after focus and metering action is completed. For example, to lock both AF and AE, use `FLAG_AF | FLAG_AE`.

Locking will only occur if the corresponding 3A component has at least one `https://developer.android.com/reference/kotlin/androidx/camera/core/MeteringPoint` specified in this action and the camera device supports locking for that component.

By default, only `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is set. Apps can also use `0` to disable any 3A locking while still updating the 3A regions. For example, if AF points are specified but `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()` is not included in the locking mode set through this API, the AF region will be updated but the camera will not explicitly trigger an autofocus scan. In this case, how and when the camera focuses on the new region will depend on the current AF mode (e.g., whether it is a continuous autofocus mode) and device-specific behavior. Note that excluding a 3A flag from the locking mode does not unlock that 3A component or re-enable continuous autofocus if it was already locked by a prior `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#startFocusAndMetering(androidx.camera.core.FocusMeteringAction)` call; call `https://developer.android.com/reference/kotlin/androidx/camera/core/CameraControl#cancelFocusAndMetering()` (or rely on auto-cancel) to unlock 3A and restore continuous autofocus.

| Parameters |
|---|---|
| `lockingMode: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | a combination of flags consisting of `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AF()`, `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AE()`, and `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction#FLAG_AWB()`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder` | the current `https://developer.android.com/reference/kotlin/androidx/camera/core/FocusMeteringAction.Builder`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the locking mode is invalid. |