# VerticalTextScope

Artifact: [androidx.text:text-vertical-compose](https://developer.android.com/jetpack/androidx/releases/text) [View Source](https://cs.android.com/search?q=file:androidx/text/vertical/compose/VerticalTextUtils.kt+class:androidx.text.vertical.compose.VerticalTextScope) Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)


```
@VerticalTextDsl
class VerticalTextScope
```

<br />

*** ** * ** ***

Receiver for the `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/package-summary#buildVerticalText(androidx.compose.ui.unit.Density,kotlin.Function1)` DSL. Provides operations for appending plain and styled text, wrapping regions in ruby or orientation spans, and applying style modifications while constructing a vertical-text `https://developer.android.com/reference/android/text/Spanned.html`.

Instances are not intended to be instantiated directly. Use `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/package-summary#buildVerticalText(androidx.compose.ui.unit.Density,kotlin.Function1)` instead.

## Summary

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#combineUpright(kotlin.CharSequence)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html)` Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#combineUpright(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.CombineUpright` span: all of the appended characters are combined horizontally and laid out within a single vertical slot (tate-chu-yoko). |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#sideways(kotlin.CharSequence)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html)` Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#sideways(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.Sideways` span: every glyph is rotated 90° clockwise regardless of its script. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#text(kotlin.CharSequence,kotlin.collections.Map)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html, rubyMap: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-map/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html>)` Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#text(kotlin.CharSequence,kotlin.collections.Map)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#upright(kotlin.CharSequence)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html)` Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#upright(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.Upright` span: every glyph is drawn upright regardless of its script. |
| `R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withEmphasis(androidx.text.vertical.EmphasisStyle,kotlin.Boolean,kotlin.Float,kotlin.Function1)( style: https://developer.android.com/reference/kotlin/androidx/text/vertical/EmphasisStyle, filled: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, scale: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, block: https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope.() -> R )` Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withEmphasis(androidx.text.vertical.EmphasisStyle,kotlin.Boolean,kotlin.Float,kotlin.Function1)` and wraps the range it appends with an `https://developer.android.com/reference/kotlin/androidx/text/vertical/EmphasisSpan` that renders emphasis marks (傍点) alongside each character. |
| `R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)( ruby: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-char-sequence/index.html, position: https://developer.android.com/reference/kotlin/androidx/text/vertical/AnnotationPosition, orientation: https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientation, textScale: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, block: https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope.() -> R )` Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)` and wraps the range it appends with a `https://developer.android.com/reference/kotlin/androidx/text/vertical/RubySpan` annotating it with `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`, with the given `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`, `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`. |
| `R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)( fontSize: https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/TextUnit, textColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, backgroundColor: https://developer.android.com/reference/kotlin/androidx/compose/ui/graphics/Color, fontShear: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html, block: https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope.() -> R )` Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` and wraps the range it appends with a `https://developer.android.com/reference/android/text/style/MetricAffectingSpan.html` applying the given `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)`, `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)`, and/or `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` to the paint used for that range. |

## Public functions

### combineUpright

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun combineUpright(text: CharSequence): Unit
```

Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#combineUpright(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.CombineUpright` span: all of the appended characters are combined horizontally and laid out within a single vertical slot (tate-chu-yoko).

Typically used for short strings (e.g., 2 to 4 characters) such as numbers or acronyms.

### sideways

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun sideways(text: CharSequence): Unit
```

Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#sideways(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.Sideways` span: every glyph is rotated 90° clockwise regardless of its script.

### text

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun text(text: CharSequence, rubyMap: Map<String, String> = emptyMap()): Unit
```

Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#text(kotlin.CharSequence,kotlin.collections.Map)`. For each `(key, reading)` in `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#text(kotlin.CharSequence,kotlin.collections.Map)`, every occurrence of `key` inside the just-appended `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#text(kotlin.CharSequence,kotlin.collections.Map)` is annotated with a `https://developer.android.com/reference/kotlin/androidx/text/vertical/RubySpan` carrying `reading`.

### upright

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun upright(text: CharSequence): Unit
```

Appends `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#upright(kotlin.CharSequence)` and wraps it in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/TextOrientationSpan.Upright` span: every glyph is drawn upright regardless of its script.

### withEmphasis

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun <R : Any> withEmphasis(
    style: EmphasisStyle = EmphasisSpan.DEFAULT_EMPHASIS_STYLE,
    filled: Boolean = EmphasisSpan.DEFAULT_EMPHASIS_FILL,
    scale: Float = EmphasisSpan.DEFAULT_SCALE,
    block: VerticalTextScope.() -> R
): R
```

Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withEmphasis(androidx.text.vertical.EmphasisStyle,kotlin.Boolean,kotlin.Float,kotlin.Function1)` and wraps the range it appends with an `https://developer.android.com/reference/kotlin/androidx/text/vertical/EmphasisSpan` that renders emphasis marks (傍点) alongside each character.

| Returns |
|---|---|
| `R` | the value returned by `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withEmphasis(androidx.text.vertical.EmphasisStyle,kotlin.Boolean,kotlin.Float,kotlin.Function1)`. |

### withRuby

Added in [1.0.0-beta03](https://developer.android.com/jetpack/androidx/releases/text#1.0.0-beta03)

```
fun <R : Any> withRuby(
    ruby: CharSequence,
    position: AnnotationPosition = RubySpan.DEFAULT_POSITION,
    orientation: TextOrientation = RubySpan.DEFAULT_ORIENTATION,
    textScale: Float = RubySpan.DEFAULT_TEXT_SCALE,
    block: VerticalTextScope.() -> R
): R
```

Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)` and wraps the range it appends with a `https://developer.android.com/reference/kotlin/androidx/text/vertical/RubySpan` annotating it with `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`, with the given `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`, `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`.

Ruby text is small annotation text (such as furigana) placed alongside the base text, commonly used to indicate pronunciation or provide a brief description.

| Returns |
|---|---|
| `R` | the value returned by `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withRuby(kotlin.CharSequence,androidx.text.vertical.AnnotationPosition,androidx.text.vertical.TextOrientation,kotlin.Float,kotlin.Function1)`. |

### withStyle

```
fun <R : Any> withStyle(
    fontSize: TextUnit = TextUnit.Unspecified,
    textColor: Color = Color.Unspecified,
    backgroundColor: Color = Color.Unspecified,
    fontShear: Float = Float.NaN,
    block: VerticalTextScope.() -> R
): R
```

Runs `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` and wraps the range it appends with a `https://developer.android.com/reference/android/text/style/MetricAffectingSpan.html` applying the given `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)`, `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)`, and/or `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` to the paint used for that range. If `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` is provided, it also wraps the range in a `https://developer.android.com/reference/kotlin/androidx/text/vertical/FontShearSpan`.

Sp values in `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)` are resolved using `https://developer.android.com/reference/kotlin/androidx/compose/ui/unit/Density`; em values scale the inherited paint size.

| Returns |
|---|---|
| `R` | the value returned by `https://developer.android.com/reference/kotlin/androidx/text/vertical/compose/VerticalTextScope#withStyle(androidx.compose.ui.unit.TextUnit,androidx.compose.ui.graphics.Color,androidx.compose.ui.graphics.Color,kotlin.Float,kotlin.Function1)`. |