/*
* Copyright 2020 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.compose.foundation.text
import androidx.compose.foundation.Interaction
import androidx.compose.foundation.InteractionState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.savedinstancestate.rememberSavedInstanceState
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.gesture.scrollorientationlocking.Orientation
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.node.Ref
import androidx.compose.ui.text.ExperimentalTextApi
import androidx.compose.ui.text.InternalTextApi
import androidx.compose.ui.text.SoftwareKeyboardController
import androidx.compose.ui.text.TextLayoutResult
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.input.ImeAction
import androidx.compose.ui.text.input.KeyboardType
import androidx.compose.ui.text.input.TextFieldValue
import androidx.compose.ui.text.input.VisualTransformation
/**
* Basic composable that enables users to edit text via hardware or software keyboard, but
* provides no decorations like hint or placeholder.
*
* Whenever the user edits the text, [onValueChange] is called with the most up to date state
* represented by [String] with which developer is expected to update their state.
*
* Unlike [TextFieldValue] overload, this composable does not let the developer to control
* selection, cursor and text composition information. Please check [TextFieldValue] and
* corresponding [BasicTextField] overload for more information.
*
* It is crucial that the value provided in the [onValueChange] is fed back into [BasicTextField] in
* order to have the final state of the text being displayed.
*
* Example usage:
* @sample androidx.compose.foundation.samples.BasicTextFieldWithStringSample
*
* Please keep in mind that [onValueChange] is useful to be informed about the latest state of the
* text input by users, however it is generally not recommended to modify the value that you get
* via [onValueChange] callback. Any change to this value may result in a context reset and end
* up with input session restart. Such a scenario would cause glitches in the UI or text input
* experience for users.
*
* This composable provides basic text editing functionality, however does not include any
* decorations such as borders, hints/placeholder. A design system based implementation such as
* Material Design Filled text field is typically what is needed to cover most of the needs. This
* composable is designed to be used when a custom implementation for different design system is
* needed.
*
* For example, if you need to include a hint in your TextField you can write a composable as below:
* @sample androidx.compose.foundation.samples.PlaceholderBasicTextFieldSample
*
* @param value the input [String] text to be shown in the text field
* @param onValueChange the callback that is triggered when the input service updates the text. An
* updated text comes as a parameter of the callback
* @param modifier optional [Modifier] for this text field.
* @param textStyle Style configuration that applies at character level such as color, font etc.
* @param keyboardOptions software keyboard options that contains configuration such as
* [KeyboardType] and [ImeAction].
* @param singleLine when set to true, this text field becomes a single horizontally scrolling
* text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
* the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
* maxLines attribute will be automatically set to 1.
* @param maxLines the maximum height in terms of maximum number of visible lines. Should be
* equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
* set to 1 if [singleLine] is set to true.
* @param onImeActionPerformed Called when the input service requested an IME action. When the
* input service emitted an IME action, this callback is called with the emitted IME action. Note
* that this IME action may be different from what you specified in [KeyboardOptions.imeAction].
* @param visualTransformation The visual transformation filter for changing the visual
* representation of the input. By default no visual transformation is applied.
* @param onTextLayout Callback that is executed when a new text layout is calculated.
* @param onTextInputStarted Callback that is executed when the initialization has done for
* communicating with platform text input service, e.g. software keyboard on Android. Called with
* [SoftwareKeyboardController] instance which can be used for requesting input show/hide software
* keyboard.
* @param interactionState the [InteractionState] representing the different [Interaction]s
* present on this TextField. You can create and pass in your own remembered [InteractionState]
* if you want to read the [InteractionState] and customize the appearance / behavior of this
* TextField in different [Interaction]s.
* @param cursorColor Color of the cursor. If [Color.Unspecified], there will be no cursor drawn
*/
@OptIn(ExperimentalTextApi::class)
@Composable
fun BasicTextField(
value: String,
onValueChange: (String) -> Unit,
modifier: Modifier = Modifier,
textStyle: TextStyle = TextStyle.Default,
keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
singleLine: Boolean = false,
maxLines: Int = Int.MAX_VALUE,
onImeActionPerformed: (ImeAction) -> Unit = {},
visualTransformation: VisualTransformation = VisualTransformation.None,
onTextLayout: (TextLayoutResult) -> Unit = {},
onTextInputStarted: (SoftwareKeyboardController) -> Unit = {},
interactionState: InteractionState = remember { InteractionState() },
cursorColor: Color = Color.Black
) {
var textFieldValueState by remember { mutableStateOf(TextFieldValue(text = value)) }
val textFieldValue = textFieldValueState.copy(text = value)
BasicTextField(
value = textFieldValue,
onValueChange = {
textFieldValueState = it
if (value != it.text) {
onValueChange(it.text)
}
},
modifier = modifier,
textStyle = textStyle,
keyboardOptions = keyboardOptions,
maxLines = maxLines,
onImeActionPerformed = onImeActionPerformed,
visualTransformation = visualTransformation,
onTextLayout = onTextLayout,
onTextInputStarted = onTextInputStarted,
cursorColor = cursorColor,
interactionState = interactionState,
singleLine = singleLine
)
}
/**
* Basic composable that enables users to edit text via hardware or software keyboard, but
* provides no decorations like hint or placeholder.
*
* Whenever the user edits the text, [onValueChange] is called with the most up to date state
* represented by [TextFieldValue]. [TextFieldValue] contains the text entered by user, as well
* as selection, cursor and text composition information. Please check [TextFieldValue] for the
* description of its contents.
*
* It is crucial that the value provided in the [onValueChange] is fed back into [BasicTextField] in
* order to have the final state of the text being displayed.
*
* Example usage:
* @sample androidx.compose.foundation.samples.BasicTextFieldSample
*
* Please keep in mind that [onValueChange] is useful to be informed about the latest state of the
* text input by users, however it is generally not recommended to modify the values in the
* [TextFieldValue] that you get via [onValueChange] callback. Any change to the values in
* [TextFieldValue] may result in a context reset and end up with input session restart. Such
* a scenario would cause glitches in the UI or text input experience for users.
*
* This composable provides basic text editing functionality, however does not include any
* decorations such as borders, hints/placeholder. A design system based implementation such as
* Material Design Filled text field is typically what is needed to cover most of the needs. This
* composable is designed to be used when a custom implementation for different design system is
* needed.
*
* For example, if you need to include a hint in your TextField you can write a composable as below:
* @sample androidx.compose.foundation.samples.PlaceholderBasicTextFieldSample
*
* @param value The [androidx.compose.ui.text.input.TextFieldValue] to be shown in the
* [BasicTextField].
* @param onValueChange Called when the input service updates the values in [TextFieldValue].
* @param modifier optional [Modifier] for this text field.
* @param textStyle Style configuration that applies at character level such as color, font etc.
* @param keyboardOptions software keyboard options that contains configuration such as
* [KeyboardType] and [ImeAction].
* @param singleLine when set to true, this text field becomes a single horizontally scrolling
* text field instead of wrapping onto multiple lines. The keyboard will be informed to not show
* the return key as the [ImeAction]. Note that [maxLines] parameter will be ignored as the
* maxLines attribute will be automatically set to 1.
* @param maxLines the maximum height in terms of maximum number of visible lines. Should be
* equal or greater than 1. Note that this parameter will be ignored and instead maxLines will be
* set to 1 if [singleLine] is set to true.
* @param onImeActionPerformed Called when the input service requested an IME action. When the
* input service emitted an IME action, this callback is called with the emitted IME action. Note
* that this IME action may be different from what you specified in [KeyboardOptions.imeAction].
* @param visualTransformation The visual transformation filter for changing the visual
* representation of the input. By default no visual transformation is applied.
* @param onTextLayout Callback that is executed when a new text layout is calculated.
* @param onTextInputStarted Callback that is executed when the initialization has done for
* communicating with platform text input service, e.g. software keyboard on Android. Called with
* [SoftwareKeyboardController] instance which can be used for requesting input show/hide software
* keyboard.
* @param interactionState The [InteractionState] representing the different [Interaction]s
* present on this TextField. You can create and pass in your own remembered [InteractionState]
* if you want to read the [InteractionState] and customize the appearance / behavior of this
* TextField in different [Interaction]s.
* @param cursorColor Color of the cursor. If [Color.Unspecified], there will be no cursor drawn
*/
@Composable
@OptIn(InternalTextApi::class, ExperimentalTextApi::class)
fun BasicTextField(
value: TextFieldValue,
onValueChange: (TextFieldValue) -> Unit,
modifier: Modifier = Modifier,
textStyle: TextStyle = TextStyle.Default,
keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
singleLine: Boolean = false,
maxLines: Int = Int.MAX_VALUE,
onImeActionPerformed: (ImeAction) -> Unit = {},
visualTransformation: VisualTransformation = VisualTransformation.None,
onTextLayout: (TextLayoutResult) -> Unit = {},
onTextInputStarted: (SoftwareKeyboardController) -> Unit = {},
interactionState: InteractionState = remember { InteractionState() },
cursorColor: Color = Color.Black
) {
// We use it to get the cursor position
val textLayoutResult: Ref<TextLayoutResult?> = remember { Ref() }
val orientation = if (singleLine) Orientation.Horizontal else Orientation.Vertical
val scrollerPosition = rememberSavedInstanceState(saver = TextFieldScrollerPosition.Saver) {
TextFieldScrollerPosition()
}
CoreTextField(
value = value,
onValueChange = onValueChange,
textStyle = textStyle,
onImeActionPerformed = onImeActionPerformed,
visualTransformation = visualTransformation,
onTextLayout = {
textLayoutResult.value = it
onTextLayout(it)
},
interactionState = interactionState,
onTextInputStarted = onTextInputStarted,
cursorColor = cursorColor,
imeOptions = keyboardOptions.toImeOptions(singleLine = singleLine),
softWrap = !singleLine,
modifier = modifier
.maxLinesHeight(if (singleLine) 1 else maxLines, textStyle)
.textFieldScroll(
orientation,
scrollerPosition,
value,
visualTransformation,
interactionState,
textLayoutResult
)
)
}