KeylineState.Builder

public final class KeylineState.Builder

A builder used to construct a KeylineState.

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
Builder(float itemSize, int carouselSize)

Creates a new KeylineState.Builder.

Public methods
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.
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.
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.
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.
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.
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.
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).
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).
KeylineState

Builds and returns a KeylineState.

Public constructors

Builder

public Builder(float itemSize, int carouselSize)

Creates a new 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 addKeyline and addKeylineRange 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
addKeyline

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 addKeyline and addKeylineRange 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 addKeyline and addKeylineRange 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 addKeyline and addKeylineRange 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 addKeyline and addKeylineRange 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
addKeylineRange

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 addKeyline and addKeylineRange 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 KeylineState.