public abstract class DrawAnnotation : Annotation
Attaches custom draw-phase rendering behind or over a text range.
Runs during the Compose draw phase with access to DrawAnnotationScope.textLayoutResult and the resolved `start, end) offsets ([DrawAnnotationScope.start and DrawAnnotationScope.end) so callbacks can query per-line bounding boxes via TextLayoutResult.getBoundingBoxesForRange or contour paths via TextLayoutResult.fillPathForRange. Unlike SpanStyle.background, updating or animating state read inside drawBehind or drawOver` only invalidates drawing without triggering text measurement or relayout.
Subclassing and State Guidelines
- Prefer
data classordata objectsubclasses: Reusable decorations should subclass - Instance reuse and caching: DrawAnnotation implementations may be shared across multiple
- Avoid capturing heavy references: AnnotatedString instances are frequently cached in
- Visual-only decoration: DrawAnnotation executes imperative canvas commands during the
DrawAnnotation as a top-level data class or data object holding only primitive or immutable graphics parameters so structural equals and hashCode are generated automatically. On Android, annotating a data class subclass with @Parcelize and implementing Parcelable allows AnnotatedString.Saver (for example, when saving an AnnotatedString via rememberSaveable(stateSaver = AnnotatedString.Saver)) to persist and restore the annotation across configuration changes and process death. Note that system clipboard copy/paste converts text through platform Spanned representations and does not transport DrawAnnotation instances.
ranges, shared across multiple Text layouts, or split across sub-ranges when AnnotatedString.subSequence slices text. Hold a reusable Path instance in a private field and pass it as target to TextLayoutResult.fillPathForRange to avoid allocating a Path on each draw pass; TextLayoutResult caches the per-range bounding boxes internally.
ViewModels or long-lived state holders. Avoid non-static inner class subclasses or properties that retain View, Context, or ViewModel references.
draw phase and is opaque to accessibility services, clipboard copy, and HTML export. Represent semantic meaning alongside DrawAnnotation using SpanStyle, TtsAnnotation, LinkAnnotation, or StringAnnotation.
For standard rounded background fills and borders, use BackgroundAnnotation. For one-off inline decorations, use the DrawAnnotation factory function.
Functions
drawBehind
public open fun DrawAnnotationScope.drawBehind()
Invoked before the text glyphs are painted. The receiver DrawAnnotationScope is aligned with the text layout origin and provides DrawAnnotationScope.textLayoutResult, DrawAnnotationScope.start, and DrawAnnotationScope.end to query geometry for the annotated range.
drawOver
public open fun DrawAnnotationScope.drawOver()
Invoked after the text glyphs are painted. The receiver DrawAnnotationScope is aligned with the text layout origin and provides DrawAnnotationScope.textLayoutResult, DrawAnnotationScope.start, and DrawAnnotationScope.end to query geometry for the annotated range.