whenFontReady

Resolves once font can be measured with getFontMeasure

Available since @roku-sdk/runtime 2.19.0

import { whenFontReady } from "@roku-sdk/runtime/font";

whenFontReady(font: object, options?: WhenFontReadyOptions): Promise<void>

Description

Resolves once font can be measured with getFontMeasure.

Prefers the platform's optional FontMeasureApi.whenReady when present (the web runtime implements it). Device firmware does not supply that hook; when firmware exposes a font load status, the SDK reads it here rather than waiting for a native hook. Until then device builds fall back to a shared poll per font ref: getOneLineHeight(ref) > 0 without throwing. The poll is fast for about a second, then backs off up to 500ms, and never gives up silently. Rejects only when options.signal is aborted.

Parameters

Name	Type	Description
`font`	`object`	Font node ref previously captured from a `<font>` element (`node.r`)
`options?`	WhenFontReadyOptions	Optional abort signal

Return values

A promise that resolves when the font is measurable

Example

const controller = new AbortController();
await whenFontReady(fontRef, { signal: controller.signal });
const width = getFontMeasure().getOneLineWidth(fontRef, "Hello", 1920);

Types

WhenFontReadyOptions

Options for whenFontReady.

type WhenFontReadyOptions = {
    signal?: FontReadyAbortSignal;
};

Name	Type	Description
`signal?`	`FontReadyAbortSignal`	When aborted, the returned promise rejects with `signal.reason`.

FontReadyAbortSignal

Minimal abort-signal shape accepted by whenFontReady.

Matches both the DOM AbortSignal and the firmware AbortSignalInstance (which exposes only aborted / reason).

type FontReadyAbortSignal = {
    readonly aborted: boolean;
    readonly reason?: unknown;
    addEventListener?: (type: "abort", listener: () => void) => void;
    removeEventListener?: (type: "abort", listener: () => void) => void;
};

Name	Type	Description
`aborted`	`boolean`	Whether the font-readiness wait has been canceled.
`addEventListener?`	`(type: "abort", listener: () => void) => void`	Registers a callback that runs when the signal is aborted.
`reason?`	`unknown`	Value used to reject the wait after cancellation.
`removeEventListener?`	`(type: "abort", listener: () => void) => void`	Removes a callback previously registered for the abort event.