Blame - compose/material/material/src/commonMain/kotlin/androidx/compose/material/Text.kt - platform/frameworks/support

blob: 44a1f15af00c872150db76b2a0f4035ead424d10 [file] [log] [blame]

Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	1	/*
				2	* Copyright 2020 The Android Open Source Project
				3	*
				4	* Licensed under the Apache License, Version 2.0 (the "License");
				5	* you may not use this file except in compliance with the License.
				6	* You may obtain a copy of the License at
				7	*
				8	* http://www.apache.org/licenses/LICENSE-2.0
				9	*
				10	* Unless required by applicable law or agreed to in writing, software
				11	* distributed under the License is distributed on an "AS IS" BASIS,
				12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
				13	* See the License for the specific language governing permissions and
				14	* limitations under the License.
				15	*/
				16
				17	package androidx.compose.material
				18
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	19	import androidx.compose.foundation.text.BasicText
				20	import androidx.compose.foundation.text.InlineTextContent
				21	import androidx.compose.runtime.Composable
Leland Richardson	0f99bf1	2021-02-02 20:56:41 -0800	[diff] [blame^]	22	import androidx.compose.runtime.CompositionLocalProvider
Louis Pullen-Freilich	db28653	2021-01-27 17:36:54 +0000	[diff] [blame]	23	import androidx.compose.runtime.compositionLocalOf
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	24	import androidx.compose.runtime.structuralEqualityPolicy
				25	import androidx.compose.ui.Modifier
				26	import androidx.compose.ui.graphics.Color
George Mount	c6549b9	2020-12-14 10:49:53 -0800	[diff] [blame]	27	import androidx.compose.ui.graphics.takeOrElse
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	28	import androidx.compose.ui.text.AnnotatedString
				29	import androidx.compose.ui.text.Paragraph
				30	import androidx.compose.ui.text.TextLayoutResult
				31	import androidx.compose.ui.text.TextStyle
				32	import androidx.compose.ui.text.font.FontFamily
				33	import androidx.compose.ui.text.font.FontStyle
				34	import androidx.compose.ui.text.font.FontWeight
				35	import androidx.compose.ui.text.style.TextAlign
				36	import androidx.compose.ui.text.style.TextDecoration
				37	import androidx.compose.ui.text.style.TextOverflow
				38	import androidx.compose.ui.unit.TextUnit
				39
				40	/**
				41	* High level element that displays text and provides semantics / accessibility information.
				42	*
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	43	* The default [style] uses the [LocalTextStyle] provided by the [MaterialTheme] / components. If
				44	* you are setting your own style, you may want to consider first retrieving [LocalTextStyle],
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	45	* and using [TextStyle.copy] to keep any theme defined attributes, only modifying the specific
				46	* attributes you want to override.
				47	*
				48	* For ease of use, commonly used parameters from [TextStyle] are also present here. The order of
				49	* precedence is as follows:
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	50	* - If a parameter is explicitly set here (i.e, it is _not_ `null` or [TextUnit.Unspecified]),
				51	* then this parameter will always be used.
				52	* - If a parameter is _not_ set, (`null` or [TextUnit.Unspecified]), then the corresponding value
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	53	* from [style] will be used instead.
				54	*
				55	* Additionally, for [color], if [color] is not set, and [style] does not have a color, then
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	56	* [LocalContentColor] will be used with an alpha of [LocalContentAlpha]- this allows this
Louis Pullen-Freilich	3772ac5	2020-11-02 19:23:39 +0000	[diff] [blame]	57	* [Text] or element containing this [Text] to adapt to different background colors and still
				58	* maintain contrast and accessibility.
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	59	*
				60	* @param text The text to be displayed.
				61	* @param modifier [Modifier] to apply to this layout node.
				62	* @param color [Color] to apply to the text. If [Color.Unspecified], and [style] has no color set,
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	63	* this will be [LocalContentColor].
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	64	* @param fontSize The size of glyphs to use when painting the text. See [TextStyle.fontSize].
				65	* @param fontStyle The typeface variant to use when drawing the letters (e.g., italic).
				66	* See [TextStyle.fontStyle].
				67	* @param fontWeight The typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
				68	* @param fontFamily The font family to be used when rendering the text. See [TextStyle.fontFamily].
				69	* @param letterSpacing The amount of space to add between each letter.
				70	* See [TextStyle.letterSpacing].
				71	* @param textDecoration The decorations to paint on the text (e.g., an underline).
				72	* See [TextStyle.textDecoration].
				73	* @param textAlign The alignment of the text within the lines of the paragraph.
				74	* See [TextStyle.textAlign].
				75	* @param lineHeight Line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
				76	* See [TextStyle.lineHeight].
				77	* @param overflow How visual overflow should be handled.
				78	* @param softWrap Whether the text should break at soft line breaks. If false, the glyphs in the
				79	* text will be positioned as if there was unlimited horizontal space. If [softWrap] is false,
				80	* [overflow] and TextAlign may have unexpected effects.
				81	* @param maxLines An optional maximum number of lines for the text to span, wrapping if
				82	* necessary. If the text exceeds the given number of lines, it will be truncated according to
				83	* [overflow] and [softWrap]. If it is not null, then it must be greater than zero.
				84	* @param onTextLayout Callback that is executed when a new text layout is calculated.
				85	* @param style Style configuration for the text such as color, font, line height etc.
				86	*/
				87	@Composable
				88	fun Text(
				89	text: String,
				90	modifier: Modifier = Modifier,
				91	color: Color = Color.Unspecified,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	92	fontSize: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	93	fontStyle: FontStyle? = null,
				94	fontWeight: FontWeight? = null,
				95	fontFamily: FontFamily? = null,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	96	letterSpacing: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	97	textDecoration: TextDecoration? = null,
				98	textAlign: TextAlign? = null,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	99	lineHeight: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	100	overflow: TextOverflow = TextOverflow.Clip,
				101	softWrap: Boolean = true,
				102	maxLines: Int = Int.MAX_VALUE,
				103	onTextLayout: (TextLayoutResult) -> Unit = {},
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	104	style: TextStyle = LocalTextStyle.current
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	105	) {
				106	Text(
				107	AnnotatedString(text),
				108	modifier,
				109	color,
				110	fontSize,
				111	fontStyle,
				112	fontWeight,
				113	fontFamily,
				114	letterSpacing,
				115	textDecoration,
				116	textAlign,
				117	lineHeight,
				118	overflow,
				119	softWrap,
				120	maxLines,
				121	emptyMap(),
				122	onTextLayout,
				123	style
				124	)
				125	}
				126
				127	/**
				128	* High level element that displays text and provides semantics / accessibility information.
				129	*
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	130	* The default [style] uses the [LocalTextStyle] provided by the [MaterialTheme] / components. If
				131	* you are setting your own style, you may want to consider first retrieving [LocalTextStyle],
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	132	* and using [TextStyle.copy] to keep any theme defined attributes, only modifying the specific
				133	* attributes you want to override.
				134	*
				135	* For ease of use, commonly used parameters from [TextStyle] are also present here. The order of
				136	* precedence is as follows:
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	137	* - If a parameter is explicitly set here (i.e, it is _not_ `null` or [TextUnit.Unspecified]),
				138	* then this parameter will always be used.
				139	* - If a parameter is _not_ set, (`null` or [TextUnit.Unspecified]), then the corresponding value
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	140	* from [style] will be used instead.
				141	*
				142	* Additionally, for [color], if [color] is not set, and [style] does not have a color, then
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	143	* [LocalContentColor] will be used with an alpha of [LocalContentAlpha]- this allows this
Louis Pullen-Freilich	3772ac5	2020-11-02 19:23:39 +0000	[diff] [blame]	144	* [Text] or element containing this [Text] to adapt to different background colors and still
				145	* maintain contrast and accessibility.
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	146	*
				147	* @param text The text to be displayed.
				148	* @param modifier [Modifier] to apply to this layout node.
				149	* @param color [Color] to apply to the text. If [Color.Unspecified], and [style] has no color set,
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	150	* this will be [LocalContentColor].
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	151	* @param fontSize The size of glyphs to use when painting the text. See [TextStyle.fontSize].
				152	* @param fontStyle The typeface variant to use when drawing the letters (e.g., italic).
				153	* See [TextStyle.fontStyle].
				154	* @param fontWeight The typeface thickness to use when painting the text (e.g., [FontWeight.Bold]).
				155	* @param fontFamily The font family to be used when rendering the text. See [TextStyle.fontFamily].
				156	* @param letterSpacing The amount of space to add between each letter.
				157	* See [TextStyle.letterSpacing].
				158	* @param textDecoration The decorations to paint on the text (e.g., an underline).
				159	* See [TextStyle.textDecoration].
				160	* @param textAlign The alignment of the text within the lines of the paragraph.
				161	* See [TextStyle.textAlign].
				162	* @param lineHeight Line height for the [Paragraph] in [TextUnit] unit, e.g. SP or EM.
				163	* See [TextStyle.lineHeight].
				164	* @param overflow How visual overflow should be handled.
				165	* @param softWrap Whether the text should break at soft line breaks. If false, the glyphs in the
				166	* text will be positioned as if there was unlimited horizontal space. If [softWrap] is false,
				167	* [overflow] and TextAlign may have unexpected effects.
				168	* @param maxLines An optional maximum number of lines for the text to span, wrapping if
				169	* necessary. If the text exceeds the given number of lines, it will be truncated according to
				170	* [overflow] and [softWrap]. If it is not null, then it must be greater than zero.
				171	* @param inlineContent A map store composables that replaces certain ranges of the text. It's
				172	* used to insert composables into text layout. Check [InlineTextContent] for more information.
				173	* @param onTextLayout Callback that is executed when a new text layout is calculated.
				174	* @param style Style configuration for the text such as color, font, line height etc.
				175	*/
				176	@Composable
				177	fun Text(
				178	text: AnnotatedString,
				179	modifier: Modifier = Modifier,
				180	color: Color = Color.Unspecified,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	181	fontSize: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	182	fontStyle: FontStyle? = null,
				183	fontWeight: FontWeight? = null,
				184	fontFamily: FontFamily? = null,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	185	letterSpacing: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	186	textDecoration: TextDecoration? = null,
				187	textAlign: TextAlign? = null,
haoyu	df2e07c	2020-11-09 17:36:11 -0800	[diff] [blame]	188	lineHeight: TextUnit = TextUnit.Unspecified,
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	189	overflow: TextOverflow = TextOverflow.Clip,
				190	softWrap: Boolean = true,
				191	maxLines: Int = Int.MAX_VALUE,
				192	inlineContent: Map<String, InlineTextContent> = mapOf(),
				193	onTextLayout: (TextLayoutResult) -> Unit = {},
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	194	style: TextStyle = LocalTextStyle.current
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	195	) {
George Mount	c6549b9	2020-12-14 10:49:53 -0800	[diff] [blame]	196	val textColor = color.takeOrElse {
				197	style.color.takeOrElse {
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	198	LocalContentColor.current.copy(alpha = LocalContentAlpha.current)
Louis Pullen-Freilich	3772ac5	2020-11-02 19:23:39 +0000	[diff] [blame]	199	}
				200	}
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	201	val mergedStyle = style.merge(
				202	TextStyle(
				203	color = textColor,
				204	fontSize = fontSize,
				205	fontWeight = fontWeight,
				206	textAlign = textAlign,
				207	lineHeight = lineHeight,
				208	fontFamily = fontFamily,
				209	textDecoration = textDecoration,
				210	fontStyle = fontStyle,
				211	letterSpacing = letterSpacing
				212	)
				213	)
				214	BasicText(
				215	text,
				216	modifier,
				217	mergedStyle,
				218	onTextLayout,
				219	overflow,
				220	softWrap,
				221	maxLines,
				222	inlineContent
				223	)
				224	}
				225
				226	/**
Louis Pullen-Freilich	db28653	2021-01-27 17:36:54 +0000	[diff] [blame]	227	* CompositionLocal containing the preferred [TextStyle] that will be used by [Text] components by
				228	* default. To set the value for this CompositionLocal, see [ProvideTextStyle] which will merge any
				229	* missing [TextStyle] properties with the existing [TextStyle] set in this CompositionLocal.
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	230	*
				231	* @see ProvideTextStyle
				232	*/
Louis Pullen-Freilich	db28653	2021-01-27 17:36:54 +0000	[diff] [blame]	233	val LocalTextStyle = compositionLocalOf(structuralEqualityPolicy()) { TextStyle.Default }
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	234
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	235	// TODO: b/156598010 remove this and replace with fold definition on the backing CompositionLocal
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	236	/**
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	237	* This function is used to set the current value of [LocalTextStyle], merging the given style
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	238	* with the current style values for any missing attributes. Any [Text] components included in
Louis Pullen-Freilich	dc68dd50	2020-11-13 02:10:48 +0000	[diff] [blame]	239	* this component's [content] will be styled with this style unless styled explicitly.
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	240	*
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	241	* @see LocalTextStyle
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	242	*/
				243	@Composable
Louis Pullen-Freilich	dc68dd50	2020-11-13 02:10:48 +0000	[diff] [blame]	244	fun ProvideTextStyle(value: TextStyle, content: @Composable () -> Unit) {
Louis Pullen-Freilich	d42e107	2021-01-27 18:20:02 +0000	[diff] [blame]	245	val mergedStyle = LocalTextStyle.current.merge(value)
Leland Richardson	0f99bf1	2021-02-02 20:56:41 -0800	[diff] [blame^]	246	CompositionLocalProvider(LocalTextStyle provides mergedStyle, content = content)
Louis Pullen-Freilich	a77fc3c	2020-10-30 16:50:54 +0000	[diff] [blame]	247	}