Text

The text display object and its effects and input events.

import { Text, TextEffects, TextFieldType, TextInputEvent, TextCompositionEvent } from "willow";

Text

class Text extends Node

Extends Node.

Text-rendering primitive. text is live-settable.

Text: constructors

new Text(text: string)
new Text(text: string, font: Font)

Text: properties

Member	Description
align: string	Horizontal text alignment. One of "left" | "center" | "right". An unknown string raises a typed VM error. Defaults to "left".
color: Color	Equivalent to label.color = color. Glyph fill colour, a Color.
fontSize: float	Glyph point size in pixels. Defaults to 16. Assigning re-flows on the next frame.
wrapWidth: float	Wrap width in pixels; text wraps to fit. 0 (default) disables wrapping.
lineHeight: float	Line-spacing multiplier (1 = single-spaced, default). Must be > 0.
sharpness: float	SDF edge sharpness, 0 (default) to 1 (sharpest); values outside are clamped. Higher values narrow the anti-aliased edge of the glyphs.
pixelSnap: boolean	Whole-pixel text, true (default): the first baseline and the x origin land on whole pixels when the text is not rotated or skewed, which keeps small text crisp. Set false on a label that moves slowly, so it glides instead of stepping a pixel at a time.
style: string	Font style: "regular" (default), "bold", "italic", or "boldItalic".
readonly effects: TextEffects	Outline / glow / shadow parameters. See TextEffects.
font: Font	Bound font. Assigning triggers re-layout on the next frame.
readonly height: float	Measured text height in pixels, valid after the first layout pass.
text: string	The text content. Assigning triggers re-layout on the next frame.
type: TextFieldType	DYNAMIC (default) or INPUT. Only focused INPUT text can receive typing and end-entry Backspace. For caret, selection or clipboard editing, use willowui's TextInput or TextArea.
maxChars: int	Maximum Unicode characters accepted by typing. 0 (default) means unlimited.
restrict: RegExp | null	Optional regex every typed character must match before onTextInput fires.
readonly width: float	Measured text width in pixels, valid after the first layout pass.

Text: methods

Member	Description
setColor(color: Color): void	Equivalent to label.color = color. Glyph fill colour.
setFont(font: Font): void	Replaces the label's font. Triggers re-layout on the next frame.
setText(text: string): void	Equivalent to label.text = text. Triggers re-layout on the next frame.
onTextInput(cb: (e: TextInputEvent) => void): Function	Registers a cancelable pre-append text callback. Returns an unsubscribe function.
onTextComposition(cb: (e: TextCompositionEvent) => void): Function	Registers a callback for IME pre-edit updates. They never change text.
onChange(cb: () => void): Function	Registers a callback after focused typing or Backspace changes text. Returns an unsubscribe function.
measure(): Size	Computes the text layout (applying any pending property writes) without rendering and returns its { width, height } in pixels.

TextEffects

class TextEffects

Outline / glow / drop-shadow parameters for a Text, reached via label.effects. All widths/offsets default to 0 (no effect drawn); colours are the built-in Color, like Text.color. Assigning any field takes effect on the next frame (or immediately before a label.measure() call).

TextEffects: properties

Member	Description
outlineWidth: float	Outline thickness in pixels. 0 disables the outline.
outlineColor: Color	Outline colour.
glowWidth: float	Glow radius in pixels. 0 disables the glow.
glowColor: Color	Glow colour.
shadowOffsetX: float	Drop-shadow horizontal offset in pixels.
shadowOffsetY: float	Drop-shadow vertical offset in pixels.
shadowColor: Color	Drop-shadow colour.

TextFieldType

enum TextFieldType

Input mode for a Text node. Dynamic text never receives IME input.

TextFieldType: values

Member	Description
DYNAMIC	Display-only text that does not accept focused typing.
INPUT	Editable text that receives IME and character input while focused.

TextInputEvent

class TextInputEvent

Cancelable event sent to a focused input Text before its content changes.

TextInputEvent: properties

Member	Description
readonly text: string	Accepted text proposed for insertion.

TextInputEvent: methods

Member	Description
preventDefault(): void	Cancels insertion and suppresses the following change callback.

TextCompositionEvent

class TextCompositionEvent

A transient IME pre-edit update for a focused input Text.

TextCompositionEvent: properties

Member	Description
readonly text: string	Pre-edit text. Empty text with cancelled clears the composition.
readonly selectionStart: int	Selected segment start and length, measured in Unicode code points.
readonly selectionLength: int	Number of composed code points selected by the input method.
readonly replacementStart: int	Range in the widget selection which the eventual commit replaces. -1 means unspecified.
readonly replacementLength: int	Number of existing code points replaced by this composition.
readonly cancelled: boolean	True when the platform cancelled the active pre-edit.