Merge "Address API council feedback on TextMeasurer." into snap-temp-L27900000960861615snap-temp-L27900000960861615

7 files changed, 59 insertions, 33 deletions

diff --git a/compose/ui/ui-text/api/current.ignore b/compose/ui/ui-text/api/current.ignore
index bf842f85057..016057605fc 100644
--- a/compose/ui/ui-text/api/current.ignore
+++ b/compose/ui/ui-text/api/current.ignore
@@ -17,3 +17,14 @@ InvalidNullConversion: androidx.compose.ui.text.AnnotatedString.Range#Range(T, i
 
 RemovedDeprecatedMethod: androidx.compose.ui.text.AnnotatedString.Builder#deprecated_append_returning_void(char):
     Removed deprecated method androidx.compose.ui.text.AnnotatedString.Builder.deprecated_append_returning_void(char)
+
+AddedAbstractMethod: androidx.compose.ui.text.Paragraph#fillBoundingBoxes(long, float[], int):
+    Added method androidx.compose.ui.text.Paragraph.fillBoundingBoxes(long,float[],int)
+
+
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #0:
+    Attempted to change parameter name from fallbackFontFamilyResolver to defaultFontFamilyResolver in constructor androidx.compose.ui.text.TextMeasurer
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #1:
+    Attempted to change parameter name from fallbackDensity to defaultDensity in constructor androidx.compose.ui.text.TextMeasurer
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #2:
+    Attempted to change parameter name from fallbackLayoutDirection to defaultLayoutDirection in constructor androidx.compose.ui.text.TextMeasurer
diff --git a/compose/ui/ui-text/api/current.txt b/compose/ui/ui-text/api/current.txt
index 09ac6baabe0..d7c3df19109 100644
--- a/compose/ui/ui-text/api/current.txt
+++ b/compose/ui/ui-text/api/current.txt
@@ -463,7 +463,7 @@ package androidx.compose.ui.text {
   }
 
   @androidx.compose.runtime.Immutable public final class TextMeasurer {
-    ctor public TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver fallbackFontFamilyResolver, androidx.compose.ui.unit.Density fallbackDensity, androidx.compose.ui.unit.LayoutDirection fallbackLayoutDirection, optional int cacheSize);
+    ctor public TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver defaultFontFamilyResolver, androidx.compose.ui.unit.Density defaultDensity, androidx.compose.ui.unit.LayoutDirection defaultLayoutDirection, optional int cacheSize);
     method @androidx.compose.runtime.Stable public androidx.compose.ui.text.TextLayoutResult measure(androidx.compose.ui.text.AnnotatedString text, optional androidx.compose.ui.text.TextStyle style, optional int overflow, optional boolean softWrap, optional int maxLines, optional java.util.List<androidx.compose.ui.text.AnnotatedString.Range<androidx.compose.ui.text.Placeholder>> placeholders, optional long constraints, optional androidx.compose.ui.unit.LayoutDirection layoutDirection, optional androidx.compose.ui.unit.Density density, optional androidx.compose.ui.text.font.FontFamily.Resolver fontFamilyResolver, optional boolean skipCache);
     method @androidx.compose.runtime.Stable public androidx.compose.ui.text.TextLayoutResult measure(String text, optional androidx.compose.ui.text.TextStyle style, optional int overflow, optional boolean softWrap, optional int maxLines, optional long constraints, optional androidx.compose.ui.unit.LayoutDirection layoutDirection, optional androidx.compose.ui.unit.Density density, optional androidx.compose.ui.text.font.FontFamily.Resolver fontFamilyResolver, optional boolean skipCache);
   }
diff --git a/compose/ui/ui-text/api/restricted_current.ignore b/compose/ui/ui-text/api/restricted_current.ignore
index bf842f85057..ac8b900adc9 100644
--- a/compose/ui/ui-text/api/restricted_current.ignore
+++ b/compose/ui/ui-text/api/restricted_current.ignore
@@ -17,3 +17,15 @@ InvalidNullConversion: androidx.compose.ui.text.AnnotatedString.Range#Range(T, i
 
 RemovedDeprecatedMethod: androidx.compose.ui.text.AnnotatedString.Builder#deprecated_append_returning_void(char):
     Removed deprecated method androidx.compose.ui.text.AnnotatedString.Builder.deprecated_append_returning_void(char)
+
+
+AddedAbstractMethod: androidx.compose.ui.text.Paragraph#fillBoundingBoxes(long, float[], int):
+    Added method androidx.compose.ui.text.Paragraph.fillBoundingBoxes(long,float[],int)
+
+
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #0:
+    Attempted to change parameter name from fallbackFontFamilyResolver to defaultFontFamilyResolver in constructor androidx.compose.ui.text.TextMeasurer
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #1:
+    Attempted to change parameter name from fallbackDensity to defaultDensity in constructor androidx.compose.ui.text.TextMeasurer
+ParameterNameChange: androidx.compose.ui.text.TextMeasurer#TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver, androidx.compose.ui.unit.Density, androidx.compose.ui.unit.LayoutDirection, int) parameter #2:
+    Attempted to change parameter name from fallbackLayoutDirection to defaultLayoutDirection in constructor androidx.compose.ui.text.TextMeasurer
diff --git a/compose/ui/ui-text/api/restricted_current.txt b/compose/ui/ui-text/api/restricted_current.txt
index 09ac6baabe0..d7c3df19109 100644
--- a/compose/ui/ui-text/api/restricted_current.txt
+++ b/compose/ui/ui-text/api/restricted_current.txt
@@ -463,7 +463,7 @@ package androidx.compose.ui.text {
   }
 
   @androidx.compose.runtime.Immutable public final class TextMeasurer {
-    ctor public TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver fallbackFontFamilyResolver, androidx.compose.ui.unit.Density fallbackDensity, androidx.compose.ui.unit.LayoutDirection fallbackLayoutDirection, optional int cacheSize);
+    ctor public TextMeasurer(androidx.compose.ui.text.font.FontFamily.Resolver defaultFontFamilyResolver, androidx.compose.ui.unit.Density defaultDensity, androidx.compose.ui.unit.LayoutDirection defaultLayoutDirection, optional int cacheSize);
     method @androidx.compose.runtime.Stable public androidx.compose.ui.text.TextLayoutResult measure(androidx.compose.ui.text.AnnotatedString text, optional androidx.compose.ui.text.TextStyle style, optional int overflow, optional boolean softWrap, optional int maxLines, optional java.util.List<androidx.compose.ui.text.AnnotatedString.Range<androidx.compose.ui.text.Placeholder>> placeholders, optional long constraints, optional androidx.compose.ui.unit.LayoutDirection layoutDirection, optional androidx.compose.ui.unit.Density density, optional androidx.compose.ui.text.font.FontFamily.Resolver fontFamilyResolver, optional boolean skipCache);
     method @androidx.compose.runtime.Stable public androidx.compose.ui.text.TextLayoutResult measure(String text, optional androidx.compose.ui.text.TextStyle style, optional int overflow, optional boolean softWrap, optional int maxLines, optional long constraints, optional androidx.compose.ui.unit.LayoutDirection layoutDirection, optional androidx.compose.ui.unit.Density density, optional androidx.compose.ui.text.font.FontFamily.Resolver fontFamilyResolver, optional boolean skipCache);
   }
diff --git a/compose/ui/ui-text/benchmark/src/androidTest/java/androidx/compose/ui/text/benchmark/TextMeasurerBenchmark.kt b/compose/ui/ui-text/benchmark/src/androidTest/java/androidx/compose/ui/text/benchmark/TextMeasurerBenchmark.kt
index 993ebf5d396..27e9cb64940 100644
--- a/compose/ui/ui-text/benchmark/src/androidTest/java/androidx/compose/ui/text/benchmark/TextMeasurerBenchmark.kt
+++ b/compose/ui/ui-text/benchmark/src/androidTest/java/androidx/compose/ui/text/benchmark/TextMeasurerBenchmark.kt
@@ -96,9 +96,9 @@ class TextMeasurerBenchmark(
     fun text_measurer_no_cache() {
         textBenchmarkRule.generator { textGenerator ->
             val textMeasurer = TextMeasurer(
-                fallbackFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
-                fallbackDensity = Density(instrumentationContext),
-                fallbackLayoutDirection = LayoutDirection.Ltr,
+                defaultFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
+                defaultDensity = Density(instrumentationContext),
+                defaultLayoutDirection = LayoutDirection.Ltr,
                 cacheSize = 0
             )
             val text = text(textGenerator)
@@ -116,9 +116,9 @@ class TextMeasurerBenchmark(
     fun text_measurer_cached() {
         textBenchmarkRule.generator { textGenerator ->
             val textMeasurer = TextMeasurer(
-                fallbackFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
-                fallbackDensity = Density(instrumentationContext),
-                fallbackLayoutDirection = LayoutDirection.Ltr,
+                defaultFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
+                defaultDensity = Density(instrumentationContext),
+                defaultLayoutDirection = LayoutDirection.Ltr,
                 cacheSize = 16
             )
             val text = text(textGenerator)
@@ -136,9 +136,9 @@ class TextMeasurerBenchmark(
     fun drawText_TextLayoutResult_no_change() {
         textBenchmarkRule.generator { textGenerator ->
             val textMeasurer = TextMeasurer(
-                fallbackFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
-                fallbackDensity = Density(instrumentationContext),
-                fallbackLayoutDirection = LayoutDirection.Ltr,
+                defaultFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
+                defaultDensity = Density(instrumentationContext),
+                defaultLayoutDirection = LayoutDirection.Ltr,
                 cacheSize = 16
             )
             val textLayoutResult = textMeasurer.measure(
@@ -167,9 +167,9 @@ class TextMeasurerBenchmark(
     fun drawText_TextLayoutResult_color_override() {
         textBenchmarkRule.generator { textGenerator ->
             val textMeasurer = TextMeasurer(
-                fallbackFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
-                fallbackDensity = Density(instrumentationContext),
-                fallbackLayoutDirection = LayoutDirection.Ltr,
+                defaultFontFamilyResolver = createFontFamilyResolver(instrumentationContext),
+                defaultDensity = Density(instrumentationContext),
+                defaultLayoutDirection = LayoutDirection.Ltr,
                 cacheSize = 16
             )
             val textLayoutResult = textMeasurer.measure(
diff --git a/compose/ui/ui-text/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurer.kt b/compose/ui/ui-text/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurer.kt
index 61ac3a6b387..eb8cef90b60 100644
--- a/compose/ui/ui-text/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurer.kt
+++ b/compose/ui/ui-text/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurer.kt
@@ -64,13 +64,13 @@ private val DefaultCacheSize = 8
  *
  * [FontFamily.Resolver], [LayoutDirection], and [Density] are required parameters to construct a
  * text layout but they have no safe fallbacks outside of composition. These parameters must be
- * provided during the construction of a [TextMeasurer] to be used as default values when they
+ * provided during the construction of a TextMeasurer to be used as default values when they
  * are skipped in [TextMeasurer.measure] call.
  *
- * @param fallbackFontFamilyResolver to be used to load fonts given in [TextStyle] and [SpanStyle]s
+ * @param defaultFontFamilyResolver to be used to load fonts given in [TextStyle] and [SpanStyle]s
  * in [AnnotatedString].
- * @param fallbackLayoutDirection layout direction of the measurement environment.
- * @param fallbackDensity density of the measurement environment. Density controls the scaling
+ * @param defaultLayoutDirection layout direction of the measurement environment.
+ * @param defaultDensity density of the measurement environment. Density controls the scaling
  * factor for fonts.
  * @param cacheSize Capacity of internal cache inside TextMeasurer. Size unit is the number of
  * unique text layout inputs that are measured. Value of this parameter highly depends on the
@@ -81,9 +81,9 @@ private val DefaultCacheSize = 8
  */
 @Immutable
 class TextMeasurer constructor(
-    private val fallbackFontFamilyResolver: FontFamily.Resolver,
-    private val fallbackDensity: Density,
-    private val fallbackLayoutDirection: LayoutDirection,
+    private val defaultFontFamilyResolver: FontFamily.Resolver,
+    private val defaultDensity: Density,
+    private val defaultLayoutDirection: LayoutDirection,
     private val cacheSize: Int = DefaultCacheSize
 ) {
     private val textLayoutCache: TextLayoutCache? = if (cacheSize > 0) {
@@ -145,9 +145,9 @@ class TextMeasurer constructor(
         maxLines: Int = Int.MAX_VALUE,
         placeholders: List<AnnotatedString.Range<Placeholder>> = emptyList(),
         constraints: Constraints = Constraints(),
-        layoutDirection: LayoutDirection = this.fallbackLayoutDirection,
-        density: Density = this.fallbackDensity,
-        fontFamilyResolver: FontFamily.Resolver = this.fallbackFontFamilyResolver,
+        layoutDirection: LayoutDirection = this.defaultLayoutDirection,
+        density: Density = this.defaultDensity,
+        fontFamilyResolver: FontFamily.Resolver = this.defaultFontFamilyResolver,
         skipCache: Boolean = false
     ): TextLayoutResult {
         val requestedTextLayoutInput = TextLayoutInput(
@@ -234,9 +234,9 @@ class TextMeasurer constructor(
         softWrap: Boolean = true,
         maxLines: Int = Int.MAX_VALUE,
         constraints: Constraints = Constraints(),
-        layoutDirection: LayoutDirection = this.fallbackLayoutDirection,
-        density: Density = this.fallbackDensity,
-        fontFamilyResolver: FontFamily.Resolver = this.fallbackFontFamilyResolver,
+        layoutDirection: LayoutDirection = this.defaultLayoutDirection,
+        density: Density = this.defaultDensity,
+        fontFamilyResolver: FontFamily.Resolver = this.defaultFontFamilyResolver,
         skipCache: Boolean = false
     ): TextLayoutResult {
         return measure(
diff --git a/compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurerHelper.kt b/compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurerHelper.kt
index b94e5efd26c..5b6565ad09b 100644
--- a/compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurerHelper.kt
+++ b/compose/ui/ui/src/commonMain/kotlin/androidx/compose/ui/text/TextMeasurerHelper.kt
@@ -28,14 +28,17 @@ import androidx.compose.ui.platform.LocalLayoutDirection
 private val DefaultCacheSize: Int = 8
 
 /**
- * Creates and remembers a [TextMeasurer]. All parameters that are required for TextMeasurer except
- * [cacheSize] are read from CompositionLocals. Created TextMeasurer carries an internal
+ * Creates and remembers a [TextMeasurer]. All parameters that are required for [TextMeasurer]
+ * except [cacheSize] are read from CompositionLocals. Created [TextMeasurer] carries an internal
  * [TextLayoutCache] with [cacheSize] capacity. Provide 0 for [cacheSize] to opt-out from internal
- * caching behavior. Moreover, the cache can be disabled at will during measure by passing in
- * skipCache as true.
+ * caching behavior.
  *
- * @param cacheSize Capacity of internal cache inside TextMeasurer. Size unit is the number of
- * unique text layout inputs that are measured.
+ * @param cacheSize Capacity of internal cache inside [TextMeasurer]. Size unit is the number of
+ * unique text layout inputs that are measured. Value of this parameter highly depends on the
+ * consumer use case. Provide a cache size that is in line with how many distinct text layouts are
+ * going to be calculated by this measurer repeatedly. If you are animating font attributes, or any
+ * other layout affecting input, cache can be skipped because most repeated measure calls would miss
+ * the cache.
  */
 @Composable
 fun rememberTextMeasurer(