# KeylineState.Builder

[View Source](https://github.com/material-components/material-components-android/blob/1.14.0/lib/java/com/google/android/material/carousel/KeylineState.java)

*** ** * ** ***


```
public final class KeylineState.Builder
```

<br />

*** ** * ** ***

A builder used to construct a `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState`.

`https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` enforces the following rules:

1. There must be one or more keylines marked as "focal". These are keylines along the scrolling axis where an item or items are considered fully unmasked and viewable.
2. Focal keylines must be added adjacent to each other. A non-focal keyline cannot be added between focal keylines.
3. A keyline's masked item size can only remain the same size or increase in size as it approaches the focal range. A keyline's masked item size before the focal range cannot be larger than a focal keyline's masked item size.
4. A keyline's masked item size can only remain the same size or decrease in size as it moves away from the focal range. A keyline's masked item size after the focal range cannot be larger than a focal keyline's masked item size.

Typically there should be a keyline for every visible item in the scrolling container.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#Builder(float,int)(float itemSize, int carouselSize)` Creates a new `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder`. |

| ### Public methods |
|---|---|
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addAnchorKeyline(float,float,float)(float offsetLoc, float mask, float maskedItemSize)` Adds an anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float)(float offsetLoc, float mask, float maskedItemSize)` Adds a non-anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean)( float offsetLoc, float mask, float maskedItemSize, boolean isFocal )` Adds a non-anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean)( float offsetLoc, float mask, float maskedItemSize, boolean isFocal, boolean isAnchor )` Adds a keyline along the scrolling axis where an object should be masked by the given ` mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean,float)( float offsetLoc, float mask, float maskedItemSize, boolean isFocal, boolean isAnchor, float cutoff )` Adds a keyline along the scrolling axis where an object should be masked by the given ` mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean,float,float,float)( float offsetLoc, float mask, float maskedItemSize, boolean isFocal, boolean isAnchor, float cutoff, float leftOrTopPaddingShift, float rightOrBottomPaddingShift )` Adds a keyline along the scrolling axis where an object should be masked by the given ` mask` and positioned at `offsetLoc`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)( float offsetLoc, float mask, float maskedItemSize, int count )` Adds a range of keylines along the scrolling axis where an item should be masked by ` mask` when its center is between `offsetLoc` and `offsetLoc + (maskedItemSize * count)`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int,boolean)( float offsetLoc, float mask, float maskedItemSize, int count, boolean isFocal )` Adds a range along the scrolling axis where an object should be masked by `mask` when its center is between `offsetLoc` and `offsetLoc + (maskedItemSize * count)`. |
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState` | `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#build()()` Builds and returns a `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState`. |

## Public constructors

### Builder

```
public Builder(float itemSize, int carouselSize)
```

Creates a new `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder`.

| Parameters |
|---|---|
| `float itemSize` | The size of a fully unmasked item. This is the size that will be used by the carousel to measure and lay out all children, overriding each child's desired size. |
| `int carouselSize` | the size of the carousel used to build this keyline state. |

## Public methods

### addAnchorKeyline

```
public KeylineState.Builder addAnchorKeyline(float offsetLoc, float mask, float maskedItemSize)
```

Adds an anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`.

Anchor keylines are keylines that are added to increase motion of carousel items going out of bounds of the carousel, and are 'anchored' (ie. does not shift). These keylines must be at the start or end of all keylines.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. This method should be called first, or last of all the \`addKeyline\` calls.

| Parameters |
|---|---|
| `float offsetLoc` | The location of this keyline along the scrolling axis. An offsetLoc of 0 will be at the start of the scroll container. |
| `float mask` | The percentage of a child's full size that it should be masked by when its center is at `offsetLoc`. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | The total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |

### addKeyline

```
public KeylineState.Builder addKeyline(float offsetLoc, float mask, float maskedItemSize)
```

Adds a non-anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`.

| See also |
|---|---|
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean)` |   |

### addKeyline

```
public KeylineState.Builder addKeyline(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    boolean isFocal
)
```

Adds a non-anchor keyline along the scrolling axis where an object should be masked by the given `mask` and positioned at `offsetLoc`. Non-anchor keylines shift when keylines shift due to scrolling.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. Typically, this means keylines should be added in order of ascending `offsetLoc`.

| Parameters |
|---|---|
| `float offsetLoc` | The location of this keyline along the scrolling axis. An offsetLoc of 0 will be at the start of the scroll container. |
| `float mask` | The percentage of a child's full size that it should be masked by when its center is at `offsetLoc`. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | The total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |
| `boolean isFocal` | Whether this keyline is considered part of the focal range. Typically, this is when `mask` is equal to 0. |

### addKeyline

```
public KeylineState.Builder addKeyline(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    boolean isFocal,
    boolean isAnchor
)
```

Adds a keyline along the scrolling axis where an object should be masked by the given `
mask` and positioned at `offsetLoc`. This method also calculates the amount that a keyline may be cut off by the bounds of the available space given.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. Typically, this means keylines should be added in order of ascending `offsetLoc`. The first and last keylines added are 'anchor' keylines that mark the start and ends of the keylines. These keylines do not shift when scrolled.

Note also that `isFocal` and `isAnchor` cannot be true at the same time as anchor keylines refer to keylines offscreen that dictate the ends of the keylines.

| Parameters |
|---|---|
| `float offsetLoc` | The location of this keyline along the scrolling axis. An offsetLoc of 0 will be at the start of the scroll container. |
| `float mask` | The percentage of a child's full size that it should be masked by when its center is at `offsetLoc`. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | The total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |
| `boolean isFocal` | Whether this keyline is considered part of the focal range. Typically, this is when `mask` is equal to 0. |
| `boolean isAnchor` | Whether this keyline is an anchor keyline. Anchor keylines do not shift when keylines are shifted. |

### addKeyline

```
public KeylineState.Builder addKeyline(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    boolean isFocal,
    boolean isAnchor,
    float cutoff
)
```

Adds a keyline along the scrolling axis where an object should be masked by the given `
mask` and positioned at `offsetLoc`.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. Typically, this means keylines should be added in order of ascending `offsetLoc`. The first and last keylines added are 'anchor' keylines that mark the start and ends of the keylines. These keylines do not shift when scrolled.

Note also that `isFocal` and `isAnchor` cannot be true at the same time as anchor keylines refer to keylines offscreen that dictate the ends of the keylines.

| Parameters |
|---|---|
| `float offsetLoc` | The location of this keyline along the scrolling axis. An offsetLoc of 0 will be at the start of the scroll container. |
| `float mask` | The percentage of a child's full size that it should be masked by when its center is at `offsetLoc`. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | The total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |
| `boolean isFocal` | Whether this keyline is considered part of the focal range. Typically, this is when `mask` is equal to 0. |
| `boolean isAnchor` | Whether this keyline is an anchor keyline. Anchor keylines do not shift when keylines are shifted. |
| `float cutoff` | How much the keyline item is out the bounds of the available space. |

### addKeyline

```
public KeylineState.Builder addKeyline(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    boolean isFocal,
    boolean isAnchor,
    float cutoff,
    float leftOrTopPaddingShift,
    float rightOrBottomPaddingShift
)
```

Adds a keyline along the scrolling axis where an object should be masked by the given `
mask` and positioned at `offsetLoc`.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. Typically, this means keylines should be added in order of ascending `offsetLoc`. The first and last keylines added are 'anchor' keylines that mark the start and ends of the keylines. These keylines do not shift when scrolled.

Note also that `isFocal` and `isAnchor` cannot be true at the same time as anchor keylines refer to keylines offscreen that dictate the ends of the keylines.

| Parameters |
|---|---|
| `float offsetLoc` | The location of this keyline along the scrolling axis. An offsetLoc of 0 will be at the start of the scroll container. |
| `float mask` | The percentage of a child's full size that it should be masked by when its center is at `offsetLoc`. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | The total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |
| `boolean isFocal` | Whether this keyline is considered part of the focal range. Typically, this is when `mask` is equal to 0. |
| `boolean isAnchor` | Whether this keyline is an anchor keyline. Anchor keylines do not shift when keylines are shifted. |
| `float cutoff` | How much the keyline item is out the bounds of the available space. |

### addKeylineRange

```
public KeylineState.Builder addKeylineRange(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    int count
)
```

Adds a range of keylines along the scrolling axis where an item should be masked by `
mask` when its center is between `offsetLoc` and `offsetLoc + (maskedItemSize *
count)`.

| See also |
|---|---|
| `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int,boolean)` |   |

### addKeylineRange

```
public KeylineState.Builder addKeylineRange(
    float offsetLoc,
    float mask,
    float maskedItemSize,
    int count,
    boolean isFocal
)
```

Adds a range along the scrolling axis where an object should be masked by `mask` when its center is between `offsetLoc` and `offsetLoc + (maskedItemSize * count)`.

Note that calls to `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeyline(float,float,float,boolean)` and `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState.Builder#addKeylineRange(float,float,float,int)` are added in order. Typically, this means keylines should be added in order of ascending `offsetLoc`.

| Parameters |
|---|---|
| `float offsetLoc` | the location along the scrolling axis where this range starts. The range's end will be defined by `offsetLoc + (maskedItemSize * count)`. An offsetLoc of 0 will be at the start of the scrolling container. |
| `float mask` | the percentage of a child's full size that it should be masked by when its center is within the keyline range. 0 is fully unmasked and 1 is fully masked. |
| `float maskedItemSize` | the total size of this item when masked. This might differ from ` itemSize - (itemSize * mask)` depending on how margins are included in the `mask`. |
| `int count` | The number of items that should be in this range at a time. |
| `boolean isFocal` | whether this keyline range is the focal range. Typically this is when ` mask` is equal to 0. |

### build

```
public KeylineState build()
```

Builds and returns a `https://developer.android.com/reference/com/google/android/material/carousel/KeylineState`.