# BackgroundAnnotation.SpreadValues

> Per-edge [Dp] spread applied to a text range's bounding boxes during the draw phase.

## API Reference

> Source set: Common

```kotlin
public class SpreadValues(
        public val left: Dp = 0.dp,
        public val top: Dp = 0.dp,
        public val right: Dp = 0.dp,
        public val bottom: Dp = 0.dp,
    )
```

Per-edge `Dp` spread applied to a text range's bounding boxes during the draw phase.

Spread applies to the per-line boxes returned by `TextLayoutResult.getBoundingBoxesForRange`,
rather than to each glyph individually:
- Neighboring characters on the same line whose horizontal bounds touch or overlap are merged
into a single box spanning the line's ``top, bottom``.
- Multi-line ranges and bidirectional text ranges that split into separate visual runs on the
same line produce one box per run.

By default (`SpreadValues.Zero`), each box spans the full line height (``top, bottom``) and
fits tightly around the glyphs horizontally. Configure `BackgroundAnnotation.spread` with
`SpreadValues` to adjust those bounds at draw time without shifting text layout:
- Positive horizontal spread (for example, `SpreadValues(horizontal = 4.dp)`) expands the
left and right edges outward to add space between the first or last glyph and a pill's
border or rounded corners. If horizontal expansion causes two separate boxes on the same
line to touch or overlap, they are merged into a single box.
- Negative vertical spread (for example, `SpreadValues(vertical = (-2).dp)`): when
`BackgroundAnnotation.mergeLines` is `false`, shrinks each per-line box's top and bottom
edges inward from the line bounds so pills on consecutive lines have a vertical gap instead
of touching; when `BackgroundAnnotation.mergeLines` is `true`, shrinks only the outer top
of the first line and outer bottom of the last line of each merged stack while inner line
seams remain joined as a continuous contour.
- Positive vertical spread expands the top and bottom edges outward past the line bounds (on
each per-line box when `mergeLines = false`, or on the outer top and bottom of each merged
stack when `mergeLines = true`).

If negative spread values reduce a box's width or height (or a merged line stack's height) to
`<= 0`, that box or stack is omitted and not drawn.

## Functions

### equals

> Source set: Common

```kotlin
override fun equals(other: Any?): Boolean
```

Creates `SpreadValues` with `all` four edges spread by the same amount.

### hashCode

> Source set: Common

```kotlin
override fun hashCode(): Int
```

## Members

### Companion

> Source set: Common

```kotlin
public companion object
```

## Properties

### Zero

> Source set: Common

```kotlin
public val Zero: SpreadValues = SpreadValues(0.dp, 0.dp, 0.dp, 0.dp)
```

A `SpreadValues` with `0.dp` spread on all four edges.

## Code Examples

### BackgroundAnnotationSpreadSample

```kotlin
@Sampled
@Composable
fun BackgroundAnnotationSpreadSample() {
    val text = remember {
        buildAnnotatedString {
            append("Use positive horizontal and negative vertical ")
            withDrawAnnotation(
                BackgroundAnnotation(
                    color = Color.Cyan.copy(alpha = 0.25f),
                    cornerRadius = 6.dp,
                    // Positive horizontal spread adds side space around the glyphs;
                    // negative vertical spread shrinks from the line top/bottom so wrapped pills
                    // on consecutive lines stay visually separated instead of touching.
                    spread = SpreadValues(horizontal = 4.dp, vertical = (-2).dp),
                    mergeLines = false,
                    border = BackgroundAnnotation.Border(width = 1.dp, color = Color.Blue),
                )
            ) {
                append("SpreadValues on multi-line per-line pills")
            }
            append(" so adjacent lines do not touch.")
        }
    }
    BasicText(text = text, style = TextStyle(fontSize = 16.sp, lineHeight = 24.sp))
}
```
