[Carousel] Updated CarouselConfiguration visibility and improved documentation

PiperOrigin-RevId: 508401214

Author: hunterstich

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

@@ -18,9 +18,6 @@
 
 /** An interface that defines a widget that can be configured as a Carousel. */
 interface Carousel {
+  /** Gets the width of the carousel container. */
   int getContainerWidth();
-  int getContainerPaddingStart();
-  int getContainerPaddingTop();
-  int getContainerPaddingEnd();
-  int getContainerPaddingBottom();
 }

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

@@ -17,43 +17,89 @@
 package com.google.android.material.carousel;
 
 import android.view.View;
+import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
-import com.google.android.material.carousel.KeylineState.Keyline;
 
 /**
- * Configuration class responsible for creating a {@link KeylineState} used by {@link Carousel} to
- * mask and offset views as they move along a scrolling axis.
- *
- * <p>An implementation of {@link CarouselConfiguration} is responsible for overriding {@link
- * #onFirstChildMeasuredWithMargins(View)} and constructing a {@link KeylineState}.
+ * Configuration class responsible for creating a model used by a carousel to mask and offset views
+ * as they move along a scrolling axis.
  */
-abstract class CarouselConfiguration {
+public abstract class CarouselConfiguration {
 
   /**
    * Calculates a keyline arrangement and returns a constructed {@link KeylineState}.
    *
-   * <p>This method should handle:
+   * <p>This method is called when {@link Carousel} measures the first item to be added to its
+   * scroll container. This method then must create a {@link KeylineState} which tells {@link
+   * Carousel} how to fill the scroll container with items — how many are visible at once, what
+   * their sizes are, and where they're placed.
+   *
+   * <p>For example, take a simple arrangement that fills the scroll container with two large items
+   * and one small item. As the user scrolls the first large item moves off-screen to the left, the
+   * second large item moves to position 1, the small item unmasks into a large item at position 2,
+   * and a new small item scrolls into view from the right. To create this arrangement, pick any
+   * size for the small item that will be smaller than the large item. Next, take the carousel's
+   * total space, subtract the small item size and divide the remainder by two - this is your large
+   * item size. After determining the size of our large and small items, we can now construct a
+   * {@link KeylineState} and add keylines representing each item:
+   *
+   * <pre>
+   *
+   * // Find the centers of the items in our arrangement, aligning the first item's left with the
+   * // left of the scroll container (0).
+   * float firstLargeItemCenter = largeChildSize / 2F;
+   * float smallItemCenter = (largeChildSize * 2F) + (smallChildSize / 2F);
+   *
+   * // Get our child margins to use when calculating mask percentage
+   * LayoutParams childLayoutParams = (LayoutParams) child.getLayoutParams();
+   * float childMargins = childLayoutParams.leftMargin + childLayoutParams.rightMargin;
    *
-   * <p>1) How large a child should be. This can be based on the measured width of the {@code
-   * child}, a division of the total available space, or any other strategy a subclass might prefer.
-   * Carousel will lay out all items end-to-end, each using this size, and then offset/mask/animate
-   * children as they move between points long the scroll axis called {@link Keyline}s.
+   * return new KeylineState.Builder(largeChildWidth)
+   *     .addKeylineRange(
+   *         firstLargeItemCenter, // offsetLoc
+   *         getChildMaskPercentage(largeChildSize, largeChildSize, childMargins), // mask
+   *         largeChildSize, // maskedItemSize
+   *         2, // count
+   *         true) // isFocal
+   *     .addKeyline(
+   *         smallItemCenter, // offsetLoc
+   *         getChildMaskPercentage(smallChildSize, largeChildSize, childMargins), // mask
+   *         smallChildSize); // maskedItemSize
    *
-   * <p>2) Points and ranges along the scrolling axis at which items should be masked by a set
-   * percentage. These points and ranges (a.k.a. keylines and keyline ranges) can be inside or
-   * outside the bounds of the visible scroll window. As a child moves along the scrolling axis, it
-   * will mask and unmask itself according to the points ({@link Keyline}s) it is moving between.
+   * </pre>
    *
-   * <p>3) Create and return a {@link KeylineState}. Use the full child size [1] and points/ranges
-   * [2] from above to build a {@link KeylineState}. This object is everything the layout manager
-   * needs to offset and mask items as they move along the scroll axis.
+   * <p>A configuration does not need to take layout direction into account. {@link
+   * CarouselLayoutManager} automatically reverses the configuration's {@link KeylineState} when
+   * laid out in right-to-left. Additionally, {@link CarouselLayoutManager} shifts the focal
+   * keylines to the start or end of the container when at the start or end of a list in order to
+   * allow every item in the list to pass through the focal state.
+   *
+   * <p>For additional guidelines on constructing valid KeylineStates, see {@link
+   * KeylineState.Builder}.
    *
-   * @param child The first measured view from the carousel, use this view to determine the max size
-   *     that all items in the carousel will be given.
    * @param carousel The carousel to create a {@link KeylineState} for
+   * @param child The first measured view from the carousel.
    * @return A {@link KeylineState} to be used by the layout manager to offset and mask children
    *     along the scrolling axis.
    */
-  protected abstract KeylineState onFirstChildMeasuredWithMargins(
+  abstract KeylineState onFirstChildMeasuredWithMargins(
       @NonNull Carousel carousel, @NonNull View child);
+
+  /**
+   * Helper method to calculate a child's mask percentage given its masked size, unmasked size, and
+   * margins.
+   *
+   * @param maskedSize The size this method calculates a mask percentage for
+   * @param unmaskedSize The size this child is when fully unmasked (mask == 0F). This should likely
+   *     be the {@code itemSize} passed to the {@link KeylineState.Builder} constructor.
+   * @param childMargins The total margins at the start+end or top+bottom of this child. By default,
+   *     these are removed from the returned mask as margins should not change in size as a child's
+   *     mask changes.
+   * @return A percentage by which the child should be masked in order to be sized at {@code
+   *     maskedSize}. 0F is fully unmasked and 1F is fully masked.
+   */
+  @FloatRange(from = 0F, to = 1F)
+  static float getChildMaskPercentage(float maskedSize, float unmaskedSize, float childMargins) {
+    return 1F - ((maskedSize - childMargins) / (unmaskedSize - childMargins));
+  }
 }

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

@@ -547,7 +547,7 @@ private int calculateStartHorizontalScroll(KeylineStateList stateList) {
     KeylineState startState = isRtl ? stateList.getRightState() : stateList.getLeftState();
     Keyline startFocalKeyline =
         isRtl ? startState.getLastFocalKeyline() : startState.getFirstFocalKeyline();
-    float firstItemDistanceFromStart = getContainerPaddingStart() * (isRtl ? 1 : -1);
+    float firstItemDistanceFromStart = getPaddingStart() * (isRtl ? 1 : -1);
     float firstItemStart =
         addStart((int) startFocalKeyline.loc, (int) (startState.getItemSize() / 2F));
     return (int) (firstItemDistanceFromStart + getParentStart() - firstItemStart);
@@ -733,26 +733,6 @@ public int getContainerWidth() {
     return getWidth();
   }
 
-  @Override
-  public int getContainerPaddingStart() {
-    return getPaddingStart();
-  }
-
-  @Override
-  public int getContainerPaddingTop() {
-    return getPaddingTop();
-  }
-
-  @Override
-  public int getContainerPaddingEnd() {
-    return getPaddingEnd();
-  }
-
-  @Override
-  public int getContainerPaddingBottom() {
-    return getPaddingBottom();
-  }
-
   private boolean isLayoutRtl() {
     return getLayoutDirection() == ViewCompat.LAYOUT_DIRECTION_RTL;
   }

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

@@ -25,21 +25,25 @@
 import java.util.List;
 
 /**
- * An arrangement of {@link Keyline}s that are positioned along a scrolling axis.
+ * An arrangement of keylines that are positioned along a scrolling axis.
  *
- * <p>This class is the structure used to tell a scrolling item how it should be masked, offset, or
- * treated, at certain points along the scrolling axis.
+ * <p>This class is the model used to tell a scrolling item how it should be masked, offset, or
+ * treated at certain points (keylines) along the scrolling axis.
  *
- * <p>KeylineState enforces the following rules:
+ * <p>Keylines are points located along a scrolling axis, relative to the scrolling container's
+ * bounds, that tell an item how it should be treated (masked, offset) when it's center is located
+ * at a keyline. When between keylines, a scrolling item is treated by interpolating between the
+ * states of its nearest surrounding keylines. When put together, a KeylineState contains all
+ * keylines associated with a scrolling container and is able to tell a scrolling item how it should
+ * be treated at any point (as the item moves) along the scrolling axis, creating a fluid
+ * interpolated motion tied to scroll position.
  *
- * <ol>
- *   <li>There must be one or two keylines marked as "focal". These define the range along the
- *       scrolling axis where an item or items are considered fully unmasked and viewable.
- *   <li>Keylines can only remain the same size or increase in size as they approach the focal
- *       range. Keylines before the focal range cannot be larger than a focal item.
- *   <li>Keylines can only remain the same size or decrease in size as they move away from the focal
- *       range. Keylines after the focal range cannot be larger than a focal item.
- * </ol>
+ * <p>Keylines can be either focal or non-focal. A focal keyline is a keyline where items are
+ * considered visible or interactable in their fullest form. This usually means where items will be
+ * fully unmaksed and viewable. There must be at least one focal keyline in a KeylineState. The
+ * focal keylines are important for usability and alignment. Start-aligned configurations should
+ * place focal keylines at the beginning of the scroll container, center-aligned configurations at
+ * the center of the scroll container, etc.
  */
 final class KeylineState {
 
@@ -48,7 +52,7 @@ final class KeylineState {
   private final int firstFocalKeylineIndex;
   private final int lastFocalKeylineIndex;
 
-  KeylineState(
+  private KeylineState(
       float itemSize,
       List<Keyline> keylines,
       int firstFocalKeylineIndex,
@@ -167,6 +171,26 @@ static KeylineState reverse(KeylineState keylineState) {
     return builder.build();
   }
 
+  /**
+   * A builder used to construct a {@link KeylineState}.
+   *
+   * <p>{@link KeylineState.Builder} enforces the following rules:
+   *
+   * <ol>
+   *   <li>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.
+   *   <li>Focal keylines must be added adjacent to each other. A non-focal keyline cannot be added
+   *       between focal keylines.
+   *   <li>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.
+   *   <li>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.
+   * </ol>
+   *
+   * Typically there should be a keyline for every visible item in the scrolling container.
+   */
   static final class Builder {
 
     private static final int NO_INDEX = -1;
@@ -187,16 +211,18 @@ static final class Builder {
     /**
      * Creates a new {@link KeylineState.Builder}.
      *
-     * @param itemSize the size of a fully unmaksed item. All mask values will be a percentage of
-     *     this size.
+     * @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.
      */
     Builder(float itemSize) {
       this.itemSize = itemSize;
     }
 
     /**
-     * Adds a point along the scrolling axis where an object should be masked by the given {@code
-     * mask} percentage.
+     * Adds a 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)
      */
     @NonNull
     @CanIgnoreReturnValue
@@ -206,18 +232,21 @@ Builder addKeyline(
     }
 
     /**
-     * Adds a point along the scrolling axis where an object should be masked by the given {@code
-     * mask} percentage.
+     * Adds a keyline along the scrolling axis where an object should be masked by the given {@code
+     * mask} and positioned at {@code offsetLoc}.
      *
-     * <p>Keylines are added in order! Keylines added at the beginning of the list will appear at
-     * the start of the scroll axis.
+     * <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 along the axis where this keyline is positioned.
-     * @param mask The percentage of {@code itemSize} that a child should be masked by when its
-     *     center is at {@code loc}.
-     * @param maskedItemSize The total size of this item when masked. This might differ from the
-     *     masked size depending on how margins are included in the mask.
-     * @param isFocal Whether this keyline marks the beginning or end of the focal range.
+     * @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
@@ -266,8 +295,11 @@ Builder addKeyline(
     }
 
     /**
-     * Adds a range along the scrolling axis where an object should be masked by {@code mask} when
-     * its center is between {@code offsetLoc} and {@code offsetLoc * (maskedItemSize + count)}.
+     * 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 *
+     * count)}.
+     *
+     * @see #addKeylineRange(float, float, float, int, boolean)
      */
     @NonNull
     @CanIgnoreReturnValue
@@ -281,21 +313,22 @@ Builder addKeylineRange(
 
     /**
      * Adds a range along the scrolling axis where an object should be masked by {@code mask} when
-     * its center is between {@code offsetLoc} and {@code offsetLoc * (maskedItemSize + count)}.
+     * its center is between {@code offsetLoc} and {@code offsetLoc + (maskedItemSize * count)}.
      *
-     * <p>Keyline ranges are added in order! Keyline ranges added at the beginning of the list will
-     * appear at the start of the scroll axis. Also note that keylines can only increase in size or
-     * remain the same size as they approach the focal range and decrease in size or remain the same
-     * size as they exit the focal range.
+     * <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 location along the axis where this range starts.
-     * @param mask The percentage of {@code itemSize} that a child should be masked by when its
-     *     center is within this keyline range. 0F is fully unmasked and 1F is fully masked.
-     * @param maskedItemSize The total size of this item when masked. This might differ from the
-     *     masked size depending on how margins are included in the mask.
+     * @param offsetLoc the location along the scrolling axis where this range starts. The range's
+     *     end will be defined by {@code offsetLoc + (maskedItemSize * count)}. An offsetLoc of 0
+     *     will be at the start of the scrolling container.
+     * @param 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.
+     * @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 count The number of items that should be in this range at a time.
-     * @param isFocal Whether this range should be used to align the keylines within the scroll
-     *     container.
+     * @param isFocal whether this keyline range is the focal range. Typically this is when {@code
+     *     mask} is equal to 0.
      */
     @NonNull
     @CanIgnoreReturnValue
@@ -317,6 +350,7 @@ Builder addKeylineRange(
       return this;
     }
 
+    /** Builds and returns a {@link KeylineState}. */
     @NonNull
     KeylineState build() {
       if (tmpFirstFocalKeyline == null) {
@@ -375,7 +409,7 @@ static final class Keyline {
      *     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 width that it should be masked by when its
+     * @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.
      */

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

@@ -25,7 +25,6 @@
 import android.content.Context;
 import androidx.recyclerview.widget.RecyclerView.LayoutParams;
 import android.view.View;
-import androidx.annotation.FloatRange;
 import androidx.annotation.NonNull;
 
 /**
@@ -80,12 +79,6 @@ private float getSmallSize(@NonNull Context context) {
     return context.getResources().getDimension(R.dimen.m3_carousel_small_item_size);
   }
 
-  @FloatRange(from = 0F, to = 1F)
-  private static float getChildMaskPercentage(
-      float maskedSize, float unmaskedSize, float childMargins) {
-    return 1F - ((maskedSize - childMargins) / (unmaskedSize - childMargins));
-  }
-
   @Override
   @NonNull
   protected KeylineState onFirstChildMeasuredWithMargins(