---
title: "TextFieldBuffer"
description: "A text buffer that can be edited, similar to [StringBuilder].
This class provides methods for changing the text, such as:
- [replace]
- [append]
- [insert]
- [delete]
This class also stores and tracks the cursor position or selection range. The cursor position is
just a selection range with zero length. The cursor and selection can be changed using methods
such as:
- [placeCursorAfterCharAt]
- [placeCursorBeforeCharAt]
- [placeCursorAtEnd]
- [selectAll]
To get one of these, and for usage samples, see [TextFieldState.edit]. Every change to the buffer
is tracked in a [ChangeList] which you can access via the [changes] property."
type: "class"
---
Class
Common
```kotlin
class TextFieldBuffer
internal constructor(
initialValue: TextFieldCharSequence,
initialChanges: ChangeTracker? = null,
internal val originalValue: TextFieldCharSequence = initialValue,
private val offsetMappingCalculator: OffsetMappingCalculator? = null,
) : Appendable
```
A text buffer that can be edited, similar to `StringBuilder`.
This class provides methods for changing the text, such as:
- `replace`
- `append`
- `insert`
- `delete`
This class also stores and tracks the cursor position or selection range. The cursor position is
just a selection range with zero length. The cursor and selection can be changed using methods
such as:
- `placeCursorAfterCharAt`
- `placeCursorBeforeCharAt`
- `placeCursorAtEnd`
- `selectAll`
To get one of these, and for usage samples, see `TextFieldState.edit`. Every change to the buffer
is tracked in a `ChangeList` which you can access via the `changes` property.
## Properties
Common
```kotlin
val length: Int
```
The number of characters in the text field.
Common
```kotlin
val originalText: CharSequence
```
Original text content of the buffer before any changes were applied. Calling
`revertAllChanges` will set the contents of this buffer to this value.
Common
```kotlin
val originalSelection: TextRange
```
Original selection before the changes. Calling `revertAllChanges` will set the selection to
this value.
Common
```kotlin
@ExperimentalFoundationApi
val changes: ChangeList
```
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.
Common
```kotlin
val hasSelection: Boolean
```
True if the selection range has non-zero length. If this is false, then the selection
represents the cursor.
Common
```kotlin
var selection: TextRange
```
The selected range of characters.
Places the selection around the given range in characters.
If the start or end of TextRange fall inside surrogate pairs or other invalid runs, the
values will be adjusted to the nearest earlier and later characters, respectively.
To place the start of the selection at the beginning of the field, set this value to
`TextRange.Zero`. To place the end of the selection at the end of the field, after the last
character, pass `TextFieldBuffer.length`. Passing a zero-length range is the same as calling
`placeCursorBeforeCharAt`.
## Functions
```kotlin
fun replace(start: Int, end: Int, text: CharSequence)
```
Replaces the text between `start` (inclusive) and `end` (exclusive) in this value with
`text`, and records the change in `changes`.
#### Parameters
| | |
| --- | --- |
| start | The character offset of the first character to replace. |
| end | The character offset of the first character after the text to replace. |
| text | The text to replace the range ``start, end)` with. |
```kotlin
fun charAt(index: Int): Char
```
Returns the `Char` at `index` in this buffer.
```kotlin
fun asCharSequence(): CharSequence
```
Returns a `CharSequence` backed by this buffer. Any subsequent changes to this buffer will be
visible in the returned sequence as well.
```kotlin
fun revertAllChanges()
```
Revert all changes made to this value since it was created.
After calling this method, this object will be in the same state it was when it was initially
created, and `changes` will be empty.
```kotlin
fun placeCursorBeforeCharAt(index: Int)
```
Places the cursor before the character at the given index.
If `index` is inside a surrogate pair or other invalid run, the cursor will be placed at the
nearest earlier index.
To place the cursor at the beginning of the field, pass index 0. To place the cursor at the
end of the field, after the last character, pass index `TextFieldBuffer.length` or call
`placeCursorAtEnd`.
#### Parameters
| | |
| --- | --- |
| index | Character index to place cursor before, should be in range 0 to `TextFieldBuffer.length`, inclusive. |
```kotlin
fun placeCursorAfterCharAt(index: Int)
```
Places the cursor after the character at the given index.
If `index` is inside a surrogate pair or other invalid run, the cursor will be placed at the
nearest later index.
To place the cursor at the end of the field, after the last character, pass index
`TextFieldBuffer.length` or call `placeCursorAtEnd`.
#### Parameters
| | |
| --- | --- |
| index | Character index to place cursor after, should be in range 0 (inclusive) to `TextFieldBuffer.length` (exclusive). |
```kotlin
fun addStyle(spanStyle: SpanStyle, start: Int, end: Int)
```
Adds the given `spanStyle` to the text between `start` and `end` on this buffer.
Caution: You should only use this function from an `OutputTransformation`. Styling is not yet
supported by `InputTransformation` or `TextFieldState`. Any added styling by
`OutputTransformation` will be presented to the user without being part of the state.
Also, the added styling is not tracked by this `TextFieldBuffer` if further edits are made.
Please call this function after text content is finalized.
```kotlin
fun addStyle(paragraphStyle: ParagraphStyle, start: Int, end: Int)
```
Adds the given `paragraphStyle` to the text between `start` and `end` on this buffer.
Caution: You should only use this function from an `OutputTransformation`. Styling is not yet
supported by `InputTransformation` or `TextFieldState`. Any added styling by
`OutputTransformation` will be presented to the user without being part of the state.
Also, the added styling is not tracked by this `TextFieldBuffer` if further edits are made.
Please call this function after text content is finalized.