/*
* 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.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
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.TextRange
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.text.constrain
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 maxLines the maximum height in terms of maximum number of visible lines. Should be
* equal or greater than 1.
* @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 [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 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,
maxLines: Int = Int.MAX_VALUE,
onImeActionPerformed: (ImeAction) -> Unit = {},
visualTransformation: VisualTransformation = VisualTransformation.None,
onTextLayout: (TextLayoutResult) -> Unit = {},
onTextInputStarted: (SoftwareKeyboardController) -> Unit = {},
cursorColor: Color = Color.Black
) {
var selection by remember { mutableStateOf(TextRange.Zero) }
var composition by remember { mutableStateOf<TextRange?>(null) }
@OptIn(InternalTextApi::class)
val textFieldValue = TextFieldValue(
text = value,
selection = selection.constrain(0, value.length),
composition = composition?.constrain(0, value.length)
)
BasicTextField(
value = textFieldValue,
onValueChange = {
selection = it.selection
composition = it.composition
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
)
}
/**
* 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 maxLines the maximum height in terms of maximum number of visible lines. Should be
* equal or greater than 1.
* @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 [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 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,
maxLines: Int = Int.MAX_VALUE,
onImeActionPerformed: (ImeAction) -> Unit = {},
visualTransformation: VisualTransformation = VisualTransformation.None,
onTextLayout: (TextLayoutResult) -> Unit = {},
onTextInputStarted: (SoftwareKeyboardController) -> Unit = {},
cursorColor: Color = Color.Black
) {
CoreTextField(
value = value,
modifier = modifier,
onValueChange = onValueChange,
textStyle = textStyle,
onImeActionPerformed = onImeActionPerformed,
visualTransformation = visualTransformation,
onTextLayout = onTextLayout,
onTextInputStarted = onTextInputStarted,
cursorColor = cursorColor,
imeOptions = keyboardOptions.toImeOptions(),
maxLines = maxLines
)
}