@needle-tools/engine
Version:
Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.
159 lines (158 loc) • 6.51 kB
TypeScript
import { Graphic } from './Graphic.js';
import { type ICanvas, type ICanvasEventReceiver, type IHasAlphaFactor } from './Interfaces.js';
export declare enum TextAnchor {
UpperLeft = 0,
UpperCenter = 1,
UpperRight = 2,
MiddleLeft = 3,
MiddleCenter = 4,
MiddleRight = 5,
LowerLeft = 6,
LowerCenter = 7,
LowerRight = 8
}
export declare enum VerticalWrapMode {
Truncate = 0,
Overflow = 1
}
export declare enum HorizontalWrapMode {
Wrap = 0,
Overflow = 1
}
export declare enum FontStyle {
Normal = 0,
Bold = 1,
Italic = 2,
BoldAndItalic = 3
}
/**
* [Text](https://engine.needle.tools/docs/api/Text) displays text content in the UI. Supports custom fonts, colors,
* alignment, and basic rich text formatting.
*
* **Text properties:**
* - `text` - The string content to display
* - `fontSize` - Size of the text in pixels
* - `color` - Text color (inherited from Graphic)
* - `alignment` - Text anchor position (UpperLeft, MiddleCenter, etc.)
*
* **Fonts:**
* Set the `font` property to a URL pointing to a font file.
* Supports MSDF (Multi-channel Signed Distance Field) fonts for crisp rendering.
*
* @example Update text at runtime
* ```ts
* const text = myLabel.getComponent(Text);
* text.text = "Score: " + score;
* text.fontSize = 24;
* text.color = new RGBAColor(1, 1, 1, 1);
* ```
*
* @summary Display text in the UI
* @category User Interface
* @group Components
* @see {@link Canvas} for the UI root
* @see {@link TextAnchor} for alignment options
* @see {@link FontStyle} for bold/italic styles
*/
export declare class Text extends Graphic implements IHasAlphaFactor, ICanvasEventReceiver {
/**
* The alignment of the text within its container. This determines how the text is anchored and positioned relative to its RectTransform. For example, `UpperLeft` will anchor the text to the upper left corner of the container, while `MiddleCenter` will center the text both horizontally and vertically. Changing this property will update the underlying three-mesh-ui options and mark the UI as dirty to trigger a re-render.
*/
set alignment(val: TextAnchor);
get alignment(): TextAnchor;
private _alignment;
/**
* Determines how text that exceeds the vertical bounds of the container is handled. If set to `Truncate`, any text that goes beyond the vertical limits of the container will be cut off and not visible. If set to `Overflow`, the text will continue to render outside the container bounds, which may result in it being partially or fully visible depending on the layout and parent containers.
* @default VerticalWrapMode.Truncate
*/
set verticalOverflow(val: VerticalWrapMode);
get verticalOverflow(): VerticalWrapMode;
private _verticalOverflow;
/**
* Determines how text that exceeds the horizontal bounds of the container is handled. If set to `Wrap`, the text will automatically wrap to the next line when it reaches the edge of the container. If set to `Overflow`, the text will continue on a single line and may overflow outside the container bounds.
* @default HorizontalWrapMode.Wrap
*/
set horizontalOverflow(val: HorizontalWrapMode);
get horizontalOverflow(): HorizontalWrapMode;
private _horizontalOverflow;
/**
* The line spacing multiplier for the text. A value of 1 means normal spacing, 1.5 means 50% more spacing, and 0.5 means 50% less spacing.
* @default 1
*/
set lineSpacing(val: number);
get lineSpacing(): number;
private _lineSpacing;
/**
* The style of the font, which can be normal, bold, italic, or bold and italic.
*
* This is used to determine the correct font variant to use based on the provided `font` property. For example, if you set `font` to "Arial" and `fontStyle` to `FontStyle.Bold`, it will look for a font variant named "Arial-Bold" (or "arial-bold") in the font library. If such a variant exists, it will be used to render the text with the specified style.
*
* @default FontStyle.Normal
*/
set fontStyle(val: FontStyle);
get fontStyle(): FontStyle;
private _fontStyle;
/**
* The font to use for the text, specified as a URL to a font file.
*
* The font file must be in MSDF format. You can generate MSDF fonts using tools like [msdf-bmfont-xml](https://github.com/Chlumsky/msdf-bmfont-xml) or by using Needle Engine for Unity where the Needle Engine integration automatically generates MSDF fonts for used font assets.
*
* @default "https://cdn.needle.tools/static/fonts/msdf/arial/arial"
*/
set font(val: string | null);
get font(): string | null;
private _font;
private _assignedAtRuntime;
/**
* Whether to support basic rich text tags in the `text` property. Supported tags include `<b>`, `<i>`, and `<color=hex>`. For example: `Hello <b>World</b>` or `Score: <color=#ff0000>100</color>`
* @default false
*/
set supportRichText(val: boolean);
get supportRichText(): boolean;
private _supportRichText;
/**
* Set the alpha factor for the text, which multiplies with the color's alpha to determine overall transparency.
*/
setAlphaFactor(factor: number): void;
/**
* The text content to display. Supports basic rich text tags like `<b>`, `<i>`, and `<color=hex>` if `supportRichText` is enabled.
* @default ""
*/
get text(): string;
set text(val: string);
private _text;
private set_text;
get fontSize(): number;
set fontSize(val: number);
private _fontSize;
private sRGBTextColor;
protected onColorChanged(): void;
onParentRectTransformChanged(): void;
onBeforeCanvasRender(_canvas: ICanvas): void;
private updateOverflow;
protected onCreate(_opts: any): void;
onAfterAddedToScene(): void;
private _textMeshUi;
private getTextOpts;
onEnable(): void;
onDisable(): void;
onDestroy(): void;
private getAlignment;
private feedText;
private _didHandleTextRenderOnTop;
private handleTextRenderOnTop;
private renderOnTopCoroutine;
private handleTag;
private getText;
private getNextTag;
/**
* Update provided opts to have a proper fontDefinition : family+weight+style
* Ensure Family and Variant are registered in FontLibrary
*
* @param opts
* @param fontStyle
* @private
*/
private setFont;
private getFamilyNameWithCorrectSuffix;
}