@lightningjs/renderer/dist/src/core/CoreTextNodeCanvas.d.ts

Lightning 3 Renderer

import type { TextRenderer, TrFontProps } from './text-rendering/renderers/TextRenderer.js';
import { CoreNode, type CoreNodeProps } from './CoreNode.js';
import type { Stage } from './Stage.js';
import type { RectWithValid } from './lib/utils.js';
import type { TextBaseline, TextVerticalAlign } from './text-rendering/renderers/canvas/LightningTextTextureRenderer.js';
export declare enum CanvasTextUpdateType {
    None = 0,
    Text = 1,
    Font = 2,
    All = 4
}
export interface CoreTextNodeProps extends CoreNodeProps, TrFontProps {
    /**
     * Text to display
     *
     * @default ''
     */
    text: string;
    /**
     * Text alignment
     *
     * @remarks
     * Alignment of the text relative to it's contained bounds. For best results,
     * use {@link contain} mode `'width'` or `'both'` and a set an explicit
     * {@link width} for the text to be aligned within.
     *
     * @default 'left'
     */
    textAlign: 'left' | 'center' | 'right';
    /**
     * Color of text
     *
     * @remarks
     * The color value is a number in the format 0xRRGGBBAA, where RR is the red
     * component, GG is the green component, BB is the blue component, and AA is
     * the alpha component.
     *
     * @default 0xffffffff (opaque white)
     */
    color: number;
    /**
     * Contain mode for text
     *
     * @remarks
     * The contain mode determines how the text is contained within the bounds
     * of the Text Node. The default value is `'none'`, which means that the
     * Text Renderer will not constrain the text in any way. `'width'` mode will
     * constrain the text to the set width wrapping lines as necessary, and
     * `'both'` mode will constrain the text to both the set width and height
     * wrapping lines and truncating text as necessary.
     *
     * ## Text Auto-size Behavior
     * Depending on the set contain mode, after the text 'loaded' event is emitted,
     * the text node may have either its {@link width} and {@link height} updated
     * to match the rendered size of the text.
     *
     * When contain mode is 'none', both the {@link width} and {@link height}
     * properties are updated.
     *
     * When contain mode is 'width', only the {@link height} property is updated.
     *
     * When contain mode is 'both', neither property is updated.
     *
     * @default 'none'
     */
    contain: 'none' | 'width' | 'both';
    /**
     * Letter spacing for text (in pixels)
     *
     * @remarks
     * This property sets additional (or reduced, if value is negative) spacing
     * between characters in the text.
     *
     * @default 0
     */
    letterSpacing: number;
    /**
     * Line height for text (in pixels)
     *
     * @remarks
     * This property sets the height of each line. If set to `undefined`, the
     * line height will be calculated based on the font and font size to be the
     * minimal height required to completely contain a line of text.
     *
     * See: https://github.com/lightning-js/renderer/issues/170
     *
     * @default `undefined`
     */
    lineHeight: number | undefined;
    /**
     * Max lines for text
     *
     * @remarks
     * This property sets max number of lines of a text paragraph.
     * Not yet implemented in the SDF renderer.
     *
     * @default 0
     */
    maxLines: number;
    /**
     * Baseline for text
     *
     * @remarks
     * This property sets the text baseline used when drawing text.
     * Not yet implemented in the SDF renderer.
     *
     * @default alphabetic
     */
    textBaseline: TextBaseline;
    /**
     * Vertical Align for text when lineHeight > fontSize
     *
     * @remarks
     * This property sets the vertical align of the text.
     * Not yet implemented in the SDF renderer.
     *
     * @default middle
     */
    verticalAlign: TextVerticalAlign;
    /**
     * Overflow Suffix for text
     *
     * @remarks
     * The suffix to be added when text is cropped due to overflow.
     * Not yet implemented in the SDF renderer.
     *
     * @default "..."
     */
    overflowSuffix: string;
    /**
     * Font Style String
     *
     * @remarks
     * This property sets the font style string used when drawing text.
     *
     * @default "normal normal normal"
     */
    fontStyleString?: string;
    /**
     * Word wrap
     *
     * @remarks
     * This property sets the word wrap mode for the text.
     *
     * @default true
     */
    wordWrap: boolean;
    /**
     * Debug mode for text
     *
     * @remarks
     * This property sets the debug mode for the text.
     * Not yet implemented in the SDF renderer.
     *
     * @default false
     */
    debug?: boolean;
}
/**
 * An CoreNode in the Renderer scene graph that renders text using Canvas 2D.
 *
 * @remarks
 * A Text Node is the second graphical building block of the Renderer scene
 * graph. It renders text using a specific text renderer that is automatically
 * chosen based on the font requested and what type of fonts are installed
 * into an app.
 *
 * The text renderer can be overridden by setting the `textRendererOverride`
 *
 * The `texture` and `shader` properties are managed by loaded text renderer and
 * should not be set directly.
 *
 * For non-text rendering, see {@link CoreNode}.
 */
export declare class CoreTextCanvasNode extends CoreNode {
    private textUpdateType;
    private textProps;
    private textRenderer;
    private fontLoaded;
    constructor(stage: Stage, props: CoreTextNodeProps, textRenderer: TextRenderer);
    setTextUpdateType(updateType: CanvasTextUpdateType): void;
    update(delta: number, parentClippingRect: RectWithValid): void;
    updateText(): void;
    updateFont(): Promise<void>;
    get text(): string;
    set text(value: string);
    get fontSize(): CoreTextNodeProps['fontSize'];
    set fontSize(value: CoreTextNodeProps['fontSize']);
    get fontFamily(): CoreTextNodeProps['fontFamily'];
    set fontFamily(value: CoreTextNodeProps['fontFamily']);
    get fontStretch(): CoreTextNodeProps['fontStretch'];
    set fontStretch(value: CoreTextNodeProps['fontStretch']);
    get fontStyle(): CoreTextNodeProps['fontStyle'];
    set fontStyle(value: CoreTextNodeProps['fontStyle']);
    get fontWeight(): CoreTextNodeProps['fontWeight'];
    set fontWeight(value: CoreTextNodeProps['fontWeight']);
    get textAlign(): CoreTextNodeProps['textAlign'];
    set textAlign(value: CoreTextNodeProps['textAlign']);
    get contain(): CoreTextNodeProps['contain'];
    set contain(value: CoreTextNodeProps['contain']);
    get letterSpacing(): CoreTextNodeProps['letterSpacing'];
    set letterSpacing(value: CoreTextNodeProps['letterSpacing']);
    get lineHeight(): CoreTextNodeProps['lineHeight'];
    set lineHeight(value: CoreTextNodeProps['lineHeight']);
    get maxLines(): CoreTextNodeProps['maxLines'];
    set maxLines(value: CoreTextNodeProps['maxLines']);
    get textBaseline(): CoreTextNodeProps['textBaseline'];
    set textBaseline(value: CoreTextNodeProps['textBaseline']);
    get verticalAlign(): CoreTextNodeProps['verticalAlign'];
    set verticalAlign(value: CoreTextNodeProps['verticalAlign']);
    get overflowSuffix(): CoreTextNodeProps['overflowSuffix'];
    set overflowSuffix(value: CoreTextNodeProps['overflowSuffix']);
    get debug(): CoreTextNodeProps['debug'];
    set debug(value: CoreTextNodeProps['debug']);
}