[Carousel] Add left-aligned uncontained strategy

PiperOrigin-RevId: 559197283

lib/java/com/google/android/material/carousel/CarouselLayoutManager.java

@@ -294,7 +294,8 @@ private void recalculateKeylineStateList(Recycler recycler) {
  KeylineState keylineState = carouselStrategy.onFirstChildMeasuredWithMargins(this, firstChild);
  keylineStateList =
  KeylineStateList.from(
- this, isLayoutRtl() ? KeylineState.reverse(keylineState) : keylineState);
+ this,
+ isLayoutRtl() ? KeylineState.reverse(keylineState, getContainerSize()) : keylineState);
  }
 
  /**

lib/java/com/google/android/material/carousel/CarouselStrategyHelper.java

@@ -101,8 +101,8 @@ static KeylineState createLeftAlignedKeylineState(
  float largeMask = 0F;
 
  KeylineState.Builder builder =
- new KeylineState.Builder(arrangement.largeSize)
- .addKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth)
+ new KeylineState.Builder(arrangement.largeSize, availableSpace)
+ .addAnchorKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth)
  .addKeylineRange(
  largeStartCenterX, largeMask, arrangement.largeSize, arrangement.largeCount, true);
  if (arrangement.mediumCount > 0) {
@@ -112,7 +112,7 @@ static KeylineState createLeftAlignedKeylineState(
  builder.addKeylineRange(
  smallStartCenterX, smallMask, arrangement.smallSize, arrangement.smallCount);
  }
- builder.addKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
+ builder.addAnchorKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
  return builder.build();
  }
 
@@ -193,8 +193,8 @@ static KeylineState createCenterAlignedKeylineState(
  float largeMask = 0F;
 
  KeylineState.Builder builder =
- new KeylineState.Builder(arrangement.largeSize)
- .addKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth);
+ new KeylineState.Builder(arrangement.largeSize, availableSpace)
+ .addAnchorKeyline(extraSmallHeadCenterX, extraSmallMask, extraSmallChildWidth);
  if (arrangement.smallCount > 0) {
  builder.addKeylineRange(
  halfSmallStartCenterX,
@@ -229,7 +229,7 @@ static KeylineState createCenterAlignedKeylineState(
  (int) Math.ceil(arrangement.smallCount / 2F));
  }
 
- builder.addKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
+ builder.addAnchorKeyline(extraSmallTailCenterX, extraSmallMask, extraSmallChildWidth);
  return builder.build();
  }
 

lib/java/com/google/android/material/carousel/KeylineState.java

@@ -16,8 +16,12 @@
 
 package com.google.android.material.carousel;
 
+import static java.lang.Math.max;
+import static java.lang.Math.min;
+
 import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import com.google.android.material.animation.AnimationUtils;
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.ArrayList;
@@ -107,6 +111,30 @@ Keyline getLastKeyline() {
  return keylines.get(keylines.size() - 1);
  }
 
+ /** Returns the first non-anchor keyline. */
+ @Nullable
+ Keyline getFirstNonAnchorKeyline() {
+ for (int i = 0; i < keylines.size(); i++) {
+ Keyline keyline = keylines.get(i);
+ if (!keyline.isAnchor) {
+ return keyline;
+ }
+ }
+ return null;
+ }
+
+ /** Returns the last non-anchor keyline. */
+ @Nullable
+ Keyline getLastNonAnchorKeyline() {
+ for (int i = keylines.size()-1; i >= 0; i--) {
+ Keyline keyline = keylines.get(i);
+ if (!keyline.isAnchor) {
+ return keyline;
+ }
+ }
+ return null;
+ }
+
  /**
  * Linearly interpolate between two {@link KeylineState}s.
  *
@@ -149,11 +177,14 @@ static KeylineState lerp(KeylineState from, KeylineState to, float progress) {
  * <p>This is used to reverse a keyline state for RTL layouts.
  *
  * @param keylineState the {@link KeylineState} to reverse
+ * @param availableSpace the space in which the keylines calculate whether or not they are cut
+ * off.
  * @return a new {@link KeylineState} that has all keylines reversed.
  */
- static KeylineState reverse(KeylineState keylineState) {
+ static KeylineState reverse(KeylineState keylineState, float availableSpace) {
 
- KeylineState.Builder builder = new KeylineState.Builder(keylineState.getItemSize());
+ KeylineState.Builder builder =
+ new KeylineState.Builder(keylineState.getItemSize(), availableSpace);
 
  float start =
  keylineState.getFirstKeyline().locOffset
@@ -198,6 +229,8 @@ static final class Builder {
 
  private final float itemSize;
 
+ private final float availableSpace;
+
  // A list of keylines that hold all values except the Keyline#loc which needs to be calculated
  // in the build method.
  private final List<Keyline> tmpKeylines = new ArrayList<>();
@@ -208,21 +241,54 @@ static final class Builder {
 
  private float lastKeylineMaskedSize = 0F;
 
+ private int latestAnchorKeylineIndex = NO_INDEX;
+
+
  /**
  * Creates a new {@link KeylineState.Builder}.
  *
  * @param itemSize The size of a fully unmaksed 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.
+ * @param availableSpace The available space of the carousel the keylines calculate cutoffs by.
  */
- Builder(float itemSize) {
+ Builder(float itemSize, float availableSpace) {
  this.itemSize = itemSize;
+ this.availableSpace = availableSpace;
  }
 
  /**
- * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
- * mask} and positioned at {@code offsetLoc}.
+ * Adds a non-anchor keyline along the scrolling axis where an object should be masked by the
+ * given {@code mask} and positioned at {@code offsetLoc}. Non-anchor keylines shift when
+ * keylines shift due to scrolling.
+ *
+ * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+ * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
+ * keylines should be added in order of ascending {@code offsetLoc}.
+ *
+ * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+ * will be at the start of the scroll container.
+ * @param mask The percentage of a child's full size that it should be masked by when its center
+ * is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+ * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+ * itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+ * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
+ * when {@code mask} is equal to 0.
+ */
+ @NonNull
+ @CanIgnoreReturnValue
+ Builder addKeyline(
+ float offsetLoc,
+ @FloatRange(from = 0.0F, to = 1.0F) float mask,
+ float maskedItemSize,
+ boolean isFocal) {
+ return addKeyline(offsetLoc, mask, maskedItemSize, isFocal, /* isAnchor= */ false);
+ }
+
+ /**
+ * Adds a non-anchor keyline along the scrolling axis where an object should be masked by the
+ * given {@code mask} and positioned at {@code offsetLoc}.
  *
- * @see #addKeyline(float, float, float, boolean)
+ * @see #addKeyline(float, float, float, boolean, boolean)
  */
  @NonNull
  @CanIgnoreReturnValue
@@ -235,9 +301,14 @@ Builder addKeyline(
  * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
  * mask} and positioned at {@code offsetLoc}.
  *
- * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+ * <p>Note that calls to {@link #addKeyline(float, float, float, boolean, boolean)} and {@link
  * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
- * keylines should be added in order of ascending {@code offsetLoc}.
+ * keylines should be added in order of ascending {@code 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.
+ *
+ * <p>Note also that {@code isFocal} and {@code isAnchor} cannot be true at the same time as
+ * anchor keylines refer to keylines offscreen that dictate the ends of the keylines.
  *
  * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
  * will be at the start of the scroll container.
@@ -247,19 +318,36 @@ Builder addKeyline(
  * itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
  * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
  * when {@code mask} is equal to 0.
+ * @param isAnchor Whether this keyline is an anchor keyline. Anchor keylines do not shift when
+ * keylines are shifted.
+ * @param cutoff How much the keyline item is out the bounds of the available space.
  */
  @NonNull
  @CanIgnoreReturnValue
  Builder addKeyline(
  float offsetLoc,
  @FloatRange(from = 0.0F, to = 1.0F) float mask,
  float maskedItemSize,
- boolean isFocal) {
+ boolean isFocal,
+ boolean isAnchor,
+ float cutoff) {
  if (maskedItemSize <= 0F) {
  return this;
  }
+ if (isAnchor) {
+ if (isFocal) {
+ throw new IllegalArgumentException(
+ "Anchor keylines cannot be focal.");
+ }
+ if (latestAnchorKeylineIndex != NO_INDEX && latestAnchorKeylineIndex != 0) {
+ throw new IllegalArgumentException(
+ "Anchor keylines must be either the first or last keyline.");
+ }
+ latestAnchorKeylineIndex = tmpKeylines.size();
+ }
 
- Keyline tmpKeyline = new Keyline(UNKNOWN_LOC, offsetLoc, mask, maskedItemSize);
+ Keyline tmpKeyline =
+ new Keyline(UNKNOWN_LOC, offsetLoc, mask, maskedItemSize, isAnchor, cutoff);
  if (isFocal) {
  if (tmpFirstFocalKeyline == null) {
  tmpFirstFocalKeyline = tmpKeyline;
@@ -294,6 +382,81 @@ Builder addKeyline(
  return this;
  }
 
+ /**
+ * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
+ * mask} and positioned at {@code offsetLoc}. This method also calculates the amount that a
+ * keyline may be cut off by the bounds of the available space given.
+ *
+ * <p>Note that calls to {@link #addKeyline(float, float, float, boolean, boolean)} and {@link
+ * #addKeylineRange(float, float, float, int)} are added in order. Typically, this means
+ * keylines should be added in order of ascending {@code 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.
+ *
+ * <p>Note also that {@code isFocal} and {@code isAnchor} cannot be true at the same time as
+ * anchor keylines refer to keylines offscreen that dictate the ends of the keylines.
+ *
+ * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+ * will be at the start of the scroll container.
+ * @param mask The percentage of a child's full size that it should be masked by when its center
+ * is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+ * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+ * itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+ * @param isFocal Whether this keyline is considered part of the focal range. Typically, this is
+ * when {@code mask} is equal to 0.
+ * @param isAnchor Whether this keyline is an anchor keyline. Anchor keylines do not shift when
+ * keylines are shifted.
+ */
+ @NonNull
+ @CanIgnoreReturnValue
+ Builder addKeyline(
+ float offsetLoc,
+ @FloatRange(from = 0.0F, to = 1.0F) float mask,
+ float maskedItemSize,
+ boolean isFocal,
+ boolean isAnchor) {
+ float cutoff = 0;
+ // Calculate if the item will be cut off on either side. Currently we do not support an item
+ // cut off on both sides as we do not not support that use case. If an item is cut off on both
+ // sides, only the end cutoff will be included in the cutoff.
+ float keylineStart = offsetLoc - maskedItemSize/2F;
+ float keylineEnd = offsetLoc + maskedItemSize/2F;
+ if (keylineEnd > availableSpace) {
+ cutoff = Math.abs(keylineEnd - max(keylineEnd - maskedItemSize, availableSpace));
+ } else if (keylineStart < 0) {
+ cutoff = Math.abs(keylineStart - min(keylineStart + maskedItemSize, 0));
+ }
+
+ return addKeyline(offsetLoc, mask, maskedItemSize, isFocal, isAnchor, cutoff);
+ }
+
+ /**
+ * Adds an anchor keyline along the scrolling axis where an object should be masked by the given
+ * {@code mask} and positioned at {@code offsetLoc}.
+ *
+ * <p>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.
+ *
+ * <p>Note that calls to {@link #addKeyline(float, float, float, boolean)} and {@link
+ * #addKeylineRange(float, float, float, int)} are added in order. This method should be called
+ * first, or last of all the `addKeyline` calls.
+ *
+ * @param offsetLoc The location of this keyline along the scrolling axis. An offsetLoc of 0
+ * will be at the start of the scroll container.
+ * @param mask The percentage of a child's full size that it should be masked by when its center
+ * is at {@code offsetLoc}. 0 is fully unmasked and 1 is fully masked.
+ * @param maskedItemSize The total size of this item when masked. This might differ from {@code
+ * itemSize - (itemSize * mask)} depending on how margins are included in the {@code mask}.
+ */
+ @NonNull
+ @CanIgnoreReturnValue
+ Builder addAnchorKeyline(
+ float offsetLoc, @FloatRange(from = 0.0F, to = 1.0F) float mask, float maskedItemSize) {
+ return addKeyline(
+ offsetLoc, mask, maskedItemSize, /* isFocal= */ false, /* isAnchor= */ true);
+ }
+
  /**
  * Adds a range of keylines along the scrolling axis where an item should be masked by {@code
  * mask} when its center is between {@code offsetLoc} and {@code offsetLoc + (maskedItemSize *
@@ -366,7 +529,9 @@ KeylineState build() {
  tmpFirstFocalKeyline.locOffset, itemSize, firstFocalKeylineIndex, i),
  tmpKeyline.locOffset,
  tmpKeyline.mask,
- tmpKeyline.maskedItemSize);
+ tmpKeyline.maskedItemSize,
+ tmpKeyline.isAnchor,
+ tmpKeyline.cutoff);
  keylines.add(keyline);
  }
 
@@ -401,9 +566,11 @@ static final class Keyline {
  final float locOffset;
  final float mask;
  final float maskedItemSize;
+ final boolean isAnchor;
+ final float cutoff;
 
  /**
- * Creates a keyline along a scroll axis.
+ * Creates a non-anchor keyline along a scroll axis.
  *
  * @param loc Where this item will be along the scroll axis if it were laid out end-to-end when
  * it should be in the state defined by {@code locOffset} and {@code mask}.
@@ -414,10 +581,36 @@ static final class Keyline {
  * @param maskedItemSize The size of this item when masked.
  */
  Keyline(float loc, float locOffset, float mask, float maskedItemSize) {
+ this(loc, locOffset, mask, maskedItemSize, /* isAnchor= */ false, 0);
+ }
+
+ /**
+ * Creates a keyline along a scroll axis.
+ *
+ * @param loc Where this item will be along the scroll axis if it were laid out end-to-end when
+ * it should be in the state defined by {@code locOffset} and {@code mask}.
+ * @param locOffset The location within the carousel where an item should be when its center is
+ * at {@code loc}.
+ * @param mask The percentage of this items full size that it should be masked by when its
+ * center is at {@code loc}.
+ * @param maskedItemSize The size of this item when masked.
+ * @param isAnchor Whether or not the keyline is an anchor keyline (keylines at the end that do
+ * not shift).
+ * @param cutoff The amount by which the keyline item is cut off by the bounds of the carousel.
+ */
+ Keyline(
+ float loc,
+ float locOffset,
+ float mask,
+ float maskedItemSize,
+ boolean isAnchor,
+ float cutoff) {
  this.loc = loc;
  this.locOffset = locOffset;
  this.mask = mask;
  this.maskedItemSize = maskedItemSize;
+ this.isAnchor = isAnchor;
+ this.cutoff = cutoff;
  }
 
  /** Linearly interpolates between two keylines and returns the interpolated object. */