Merge "BasicTextField2 further docs polish" into androidx-main
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicSecureTextField.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicSecureTextField.kt
index 2b9bd1c..876eb87 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicSecureTextField.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicSecureTextField.kt
@@ -65,9 +65,9 @@
*
* BasicSecureTextField is specifically designed for password entry fields and is a preconfigured
* alternative to BasicTextField2. It only supports a single line of content and comes with default
- * settings for KeyboardOptions, filter, and obscureText that are appropriate for entering secure
- * content. Additionally, some context menu actions like cut, copy, and drag are disabled for
- * added security.
+ * settings for KeyboardOptions, filter, and codepointTransformation that are appropriate for
+ * entering secure content. Additionally, some context menu actions like cut, copy, and drag are
+ * disabled for added security.
*
* @param state [TextFieldState] object that holds the internal state of a [BasicTextField2].
* @param modifier optional [Modifier] for this text field.
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicTextField2.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicTextField2.kt
index a338feb..4891028 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicTextField2.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/BasicTextField2.kt
@@ -72,7 +72,14 @@
* using it in production since it has a very unstable API and implementation for the time being.
* Many core features like selection, cursor, gestures, etc. may fail or simply not exist.
*
- * @param state [TextFieldState] object that holds the internal state of a [BasicTextField2].
+ * Basic text composable that provides an interactive box that accepts text input through software
+ * or hardware keyboard.
+ *
+ * All the editing state of this composable is hoisted through [state]. Whenever the contents of
+ * this composable change via user input or semantics, [TextFieldState.text] gets updated.
+ * Similarly, all the programmatic updates made to [state] also reflect on this composable.
+ *
+ * @param state [TextFieldState] object that holds the internal editing state of [BasicTextField2].
* @param modifier optional [Modifier] for this text field.
* @param enabled controls the enabled state of the [BasicTextField2]. When `false`, the text
* field will be neither editable nor focusable, the input of the text field will not be selectable.
@@ -85,10 +92,11 @@
* will _not_ be applied when changing the [state] programmatically, or when the filter is changed.
* If the filter is changed on an existing text field, it will be applied to the next user edit.
* the filter will not immediately affect the current [state].
- * @param textStyle Style configuration for text content that's displayed in the editor.
- * @param keyboardOptions software keyboard options that contains configuration such as
+ * @param textStyle Typographic and graphic style configuration for text content that's displayed
+ * in the editor.
+ * @param keyboardOptions Software keyboard options that contain configurations such as
* [KeyboardType] and [ImeAction].
- * @param keyboardActions when the input service emits an IME action, the corresponding callback
+ * @param keyboardActions When the input service emits an IME action, the corresponding callback
* is called. Note that this IME action may be different from what you specified in
* [KeyboardOptions.imeAction].
* @param lineLimits Whether the text field should be [SingleLine], scroll horizontally, and
@@ -97,16 +105,16 @@
* applied. This transformation replaces any newline characters ('\n') within the text with regular
* whitespace (' '), ensuring that the contents of the text field are presented in a single line.
* @param onTextLayout Callback that is executed when a new text layout is calculated. A
- * [TextLayoutResult] object that callback provides contains paragraph information, size of the
- * text, baselines and other details. The callback can be used to add additional decoration or
- * functionality to the text. For example, to draw a cursor or selection around the text. [Density]
- * scope is the one that was used while creating the given text layout.
+ * [TextLayoutResult] object contains paragraph information, size of the text, baselines and other
+ * details. The callback can be used to add additional decoration or functionality to the text.
+ * For example, to draw a cursor or selection around the text. [Density] scope is the one that was
+ * used while creating the given text layout.
* @param interactionSource the [MutableInteractionSource] representing the stream of [Interaction]s
* for this TextField. You can create and pass in your own remembered [MutableInteractionSource]
* if you want to observe [Interaction]s and customize the appearance / behavior of this TextField
* for different [Interaction]s.
* @param cursorBrush [Brush] to paint cursor with. If [SolidColor] with [Color.Unspecified]
- * provided, there will be no cursor drawn
+ * provided, then no cursor will be drawn.
* @param scrollState Scroll state that manages either horizontal or vertical scroll of TextField.
* If [lineLimits] is [SingleLine], this text field is treated as single line with horizontal
* scroll behavior. In other cases the text field becomes vertically scrollable.
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditFilter.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditFilter.kt
index 9c25500..fd6592c 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditFilter.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditFilter.kt
@@ -51,7 +51,7 @@
/**
* The filter operation. For more information see the documentation on [TextEditFilter].
*
- * To reject all changes in [originalValue], call
+ * To reject all changes in [valueWithChanges], call
* `valueWithChanges.`[revertAllChanges][TextFieldBufferWithSelection.revertAllChanges].
*
* @param originalValue The value of the field before the change was performed.
@@ -64,8 +64,8 @@
}
/**
- * Creates a filter chain that will run [next] after this. Filters are applied in order – [next]
- * will see any the changes made by this filter.
+ * Creates a filter chain that will run [next] after this. Filters are applied sequentially, so any
+ * changes made by this filter will be visible to [next].
*
* @sample androidx.compose.foundation.samples.BasicTextField2FilterChainingSample
*
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditResult.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditResult.kt
index 9b6c9ab..93b0021 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditResult.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextEditResult.kt
@@ -22,7 +22,7 @@
import androidx.compose.ui.text.TextRange
/**
- * A value to be returned from [TextFieldState.edit] that specifies where the place the cursor or
+ * A value to be returned from [TextFieldState.edit] that specifies where to place the cursor or
* selection.
*
* Predefined results include:
@@ -85,8 +85,8 @@
* To place the cursor at the end of the field, after the last character, pass index
* [TextFieldBuffer.codepointLength] or call [placeCursorAtEnd].
*
- * @param index Codepoint index to place cursor after, should be in range 0 to
- * [TextFieldBuffer.codepointLength], inclusive.
+ * @param index Codepoint index to place cursor after, should be in range 0 (inclusive) to
+ * [TextFieldBuffer.codepointLength] (exclusive).
*
* @see placeCursorBeforeCharAt
* @see placeCursorAfterCodepointAt
@@ -132,8 +132,8 @@
* To place the cursor at the end of the field, after the last character, pass index
* [TextFieldBuffer.length] or call [placeCursorAtEnd].
*
- * @param index Character index to place cursor after, should be in range 0 to
- * [TextFieldBuffer.length], inclusive.
+ * @param index Character index to place cursor after, should be in range 0 (inclusive) to
+ * [TextFieldBuffer.length] (exclusive).
*
* @see placeCursorAfterCodepointAt
* @see placeCursorBeforeCharAt
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBuffer.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBuffer.kt
index 6281104..267535c 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBuffer.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBuffer.kt
@@ -61,9 +61,9 @@
val codepointLength: Int get() = buffer.codePointCount(0, length)
/**
- * The [ChangeList] that represents the changes made to this value. The returned [ChangeList]
- * will always represent the total list of changes made to this value, including changes made
- * after this property is read.
+ * The [ChangeList] represents the changes made to this value and is inherently mutable. This
+ * means that the returned [ChangeList] always reflects the complete list of changes made to
+ * this value at any given time, even those made after reading this property.
*
* @sample androidx.compose.foundation.samples.BasicTextField2ChangeIterationSample
* @sample androidx.compose.foundation.samples.BasicTextField2ChangeReverseIterationSample
@@ -212,7 +212,8 @@
}
/**
- * Insert [text] at the given [index] in this value.
+ * Insert [text] at the given [index] in this value. Pass 0 to insert [text] at the beginning of
+ * this buffer, and pass [TextFieldBuffer.length] to insert [text] at the end of this buffer.
*
* This is equivalent to calling `replace(index, index, text)`.
*
@@ -229,7 +230,8 @@
}
/**
- * Delete the text between [start] (inclusive) and [end] (exclusive).
+ * Delete the text between [start] (inclusive) and [end] (exclusive). Pass 0 as [start] and
+ * [TextFieldBuffer.length] as [end] to delete everything in this buffer.
*
* @param start The character offset of the first character to delete.
* @param end The character offset of the first character after the deleted range.
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBufferWithSelection.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBufferWithSelection.kt
index e04d4f5..56c698e 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBufferWithSelection.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldBufferWithSelection.kt
@@ -21,7 +21,7 @@
import androidx.compose.ui.text.TextRange
/**
- * A [TextFieldBuffer] that also provides both read and write access to the current selection
+ * A [TextFieldBuffer] that also provides both read and write access to the current selection,
* used by [TextEditFilter.filter].
*/
@ExperimentalFoundationApi
@@ -35,6 +35,8 @@
/**
* True if the selection range has non-zero length. If this is false, then the selection
* represents the cursor.
+ *
+ * @see selectionInChars
*/
val hasSelection: Boolean
get() = !selectionInChars.collapsed
@@ -105,8 +107,8 @@
* To place the cursor at the end of the field, after the last character, pass index
* [TextFieldBuffer.codepointLength] or call [placeCursorAtEnd].
*
- * @param index Codepoint index to place cursor after, should be in range 0 to
- * [TextFieldBuffer.codepointLength], inclusive.
+ * @param index Codepoint index to place cursor after, should be in range 0 (inclusive) to
+ * [TextFieldBuffer.codepointLength] (exclusive).
*
* @see placeCursorAfterCharAt
* @see placeCursorBeforeCodepointAt
@@ -126,8 +128,8 @@
* To place the cursor at the end of the field, after the last character, pass index
* [TextFieldBuffer.length] or call [placeCursorAtEnd].
*
- * @param index Character index to place cursor after, should be in range 0 to
- * [TextFieldBuffer.length], inclusive.
+ * @param index Character index to place cursor after, should be in range 0 (inclusive) to
+ * [TextFieldBuffer.length] (exclusive).
*
* @see placeCursorAfterCodepointAt
* @see placeCursorBeforeCharAt
@@ -205,7 +207,7 @@
* @param range Codepoint range of the selection, should be in range 0 to
* [TextFieldBuffer.length], inclusive.
*
- * @see selectCharsIn
+ * @see selectCodepointsIn
*/
fun selectCharsIn(range: TextRange) {
requireValidRange(range, inCodepoints = false)
diff --git a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldLineLimits.kt b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldLineLimits.kt
index 4b14a14..e2e151f 100644
--- a/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldLineLimits.kt
+++ b/compose/foundation/foundation/src/androidMain/kotlin/androidx/compose/foundation/text2/input/TextFieldLineLimits.kt
@@ -34,16 +34,15 @@
sealed interface TextFieldLineLimits {
/**
- * The text field is always a single line tall, ignores newlines in the
- * text, and scrolls horizontally when the text overflows.
+ * The text field is always a single line tall, ignores newlines in the text, and scrolls
+ * horizontally when the text overflows.
*/
object SingleLine : TextFieldLineLimits
/**
- * The text field will be at least [minHeightInLines] tall, if the text
- * overflows it will wrap, and if the text ends up being more than one
- * line the field will grow until it is [maxHeightInLines] tall and
- * then start scrolling vertically.
+ * The text field will be at least [minHeightInLines] tall, if the text overflows it will wrap,
+ * and if the text ends up being more than one line the field will grow until it is
+ * [maxHeightInLines] tall and then start scrolling vertically.
*
* It is required that 1 ≤ [minHeightInLines] ≤ [maxHeightInLines].
*/
