Interface ITextNodeProps

Properties used to create a new Text Node

interface ITextNodeProps {
    alpha: number;
    autosize: boolean;
    clipping: boolean;
    color: number;
    colorBl: number;
    colorBottom: number;
    colorBr: number;
    colorLeft: number;
    colorRight: number;
    colorTl: number;
    colorTop: number;
    colorTr: number;
    contain: "both" | "none" | "width";
    data?: CustomDataMap;
    debug: Partial<TextRendererDebugProps>;
    fontFamily: string;
    fontSize: number;
    fontStretch:
        | "normal"
        | "condensed"
        | "expanded"
        | "extra-condensed"
        | "extra-expanded"
        | "semi-condensed"
        | "semi-expanded"
        | "ultra-condensed"
        | "ultra-expanded";
    fontStyle: "normal" | "italic" | "oblique";
    fontWeight:
        | number
        | "bold"
        | "normal"
        | "lighter"
        | "bolder";
    height: number;
    imageType?:
        | null
        | "svg"
        | "regular"
        | "compressed";
    letterSpacing: number;
    lineHeight: undefined | number;
    maxLines: number;
    mount: number;
    mountX: number;
    mountY: number;
    offsetY: number;
    overflowSuffix: string;
    parent: null | INode<BaseShaderController>;
    pivot: number;
    pivotX: number;
    pivotY: number;
    preventCleanup: boolean;
    rotation: number;
    rtt: boolean;
    scale: null | number;
    scaleX: number;
    scaleY: number;
    scrollable: boolean;
    scrollY: number;
    shader: BaseShaderController;
    src: null | string;
    srcHeight?: number;
    srcWidth?: number;
    srcX?: number;
    srcY?: number;
    strictBounds: boolean;
    text: string;
    textAlign: "center" | "left" | "right";
    textBaseline: TextBaseline;
    textRendererOverride: null | (keyof TextRendererMap);
    texture: null | Texture;
    textureOptions: TextureOptions;
    verticalAlign: TextVerticalAlign;
    width: number;
    x: number;
    y: number;
    zIndex: number;
    zIndexLocked: number;
}

Hierarchy

  • Omit<CoreTextNodeProps, "parent">
    • ITextNodeProps

Properties

alpha autosize clipping color colorBl colorBottom colorBr colorLeft colorRight colorTl colorTop colorTr contain data? debug fontFamily fontSize fontStretch fontStyle fontWeight height imageType? letterSpacing lineHeight maxLines mount mountX mountY offsetY overflowSuffix parent pivot pivotX pivotY preventCleanup rotation rtt scale scaleX scaleY scrollable scrollY shader src srcHeight? srcWidth? srcX? srcY? strictBounds text textAlign textBaseline textRendererOverride texture textureOptions verticalAlign width x y zIndex zIndexLocked

Properties

alpha

alpha: number

The alpha opacity of the Node.

Remarks

The alpha value is a number between 0 and 1, where 0 is fully transparent and 1 is fully opaque.

Default

1

autosize

autosize: boolean

Autosize mode

Remarks

When enabled, when a texture is loaded into the Node, the Node will automatically resize to the dimensions of the texture.

Text Nodes are always autosized based on their text content regardless of this mode setting.

Default

false

clipping

clipping: boolean

Clipping Mode

Remarks

Enable Clipping Mode when you want to prevent the drawing of a Node and its descendants from overflowing outside of the Node's x/y/width/height bounds.

For WebGL, clipping is implemented using the high-performance WebGL operation scissor. As a consequence, clipping does not work for non-rectangular areas. So, if the element is rotated (by itself or by any of its ancestors), clipping will not work as intended.

TODO: Add support for non-rectangular clipping either automatically or via Render-To-Texture.

Default

false

color

color: number

The color of the Node.

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.

Gradient colors may be set by setting the different color sub-properties: colorTop, colorBottom, colorLeft, colorRight, colorTl, colorTr, colorBr, colorBl accordingly.

Default

0xffffffff (opaque white)

colorBl

colorBl: number

The color of the bottom-left corner of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorBottom

colorBottom: number

The color of the bottom edge of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorBr

colorBr: number

The color of the bottom-right corner of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorLeft

colorLeft: number

The color of the left edge of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorRight

colorRight: number

The color of the right edge of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorTl

colorTl: number

The color of the top-left corner of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorTop

colorTop: number

The color of the top edge of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

colorTr

colorTr: number

The color of the top-right corner of the Node for gradient rendering.

Remarks

See color for more information about color values and gradient rendering.

contain

contain: "both" | "none" | "width"

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 width and height updated to match the rendered size of the text.

When contain mode is 'none', both the width and height properties are updated.

When contain mode is 'width', only the height property is updated.

When contain mode is 'both', neither property is updated.

Default

'none'

Optionaldata

data?: CustomDataMap

Node data element for custom data storage (optional)

Remarks

This property is used to store custom data on the Node as a key/value data store. Data values are limited to string, numbers, booleans. Strings will be truncated to a 2048 character limit for performance reasons.

This is not a data storage mechanism for large amounts of data please use a dedicated data storage mechanism for that.

The custom data will be reflected in the inspector as part of data-* attributes

Default

undefined

debug

debug: Partial<TextRendererDebugProps>

fontFamily

fontFamily: string

Font Family

Internal Remarks

fontFamily is defined currently as single string, but in the future we may want to support multiple font family fallbacks, as this is supported by CSS / Canvas2d. We can do this in a backwards compatible way by unioning an array of strings to the fontFamily property.

fontSize

fontSize: number

Font Size

Remarks

The font size to use when looking up the font face.

The font size is specified in pixels and is the height of the font's em-square. The em-square is essentially the height of the capital letters for the font. The actual height of the text can be larger than the specified font size, as the font may have ascenders and descenders that extend beyond the em-square.

Default

16

fontStretch

fontStretch:
    | "normal"
    | "condensed"
    | "expanded"
    | "extra-condensed"
    | "extra-expanded"
    | "semi-condensed"
    | "semi-expanded"
    | "ultra-condensed"
    | "ultra-expanded"

Font Stretch

Remarks

The font stretch to use when looking up the font face. This can be one of the following strings:

  • 'normal'
  • 'ultra-condensed'
  • 'extra-condensed'
  • 'condensed'
  • 'semi-condensed'
  • 'semi-expanded'
  • 'expanded'
  • 'extra-expanded'
  • 'ultra-expanded'

Default

'normal'

fontStyle

fontStyle: "normal" | "italic" | "oblique"

Font Style

Remarks

The font style to use when looking up the font face. This can be one of the following strings:

  • 'normal'
  • 'italic'
  • 'oblique'

fontWeight

fontWeight:
    | number
    | "bold"
    | "normal"
    | "lighter"
    | "bolder"

Font Weight

Remarks

The font weight to use when looking up the font face. This can be a numeric value between 1 and 1000, or one of the following strings:

  • 'normal' - same as 400
  • 'bold' - same as 700
  • 'bolder' - (Not yet properly supported)

height

height: number

The height of the Node.

Default

0

OptionalimageType

imageType?:
    | null
    | "svg"
    | "regular"
    | "compressed"

Image Type to explicitly set the image type that is being loaded

Remarks

This property must be used with a src that points at an image. In some cases the extension doesn't provide a reliable representation of the image type. In such cases set the ImageType explicitly.

regular is used for normal images such as png, jpg, etc compressed is used for ETC1/ETC2 compressed images with a PVR or KTX container svg is used for scalable vector graphics

Default

undefined

letterSpacing

letterSpacing: number

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

lineHeight

lineHeight: undefined | 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

maxLines

maxLines: number

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

mount

mount: number

Combined position of the Node's Mount Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Mount Point at the top-left corner of the Node.
  • 0.5 defines it at the center of the Node.
  • 1.0 defines it at the bottom-right corner of the node.

Use the mountX and mountY props seperately for more control of the Mount Point.

When assigned, the same value is also passed to both the mountX and mountY props.

Default

0 (top-left)

mountX

mountX: number

X position of the Node's Mount Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Mount Point's X position as the left-most edge of the Node
  • 0.5 defines it as the horizontal center of the Node
  • 1.0 defines it as the right-most edge of the Node.

The combination of mountX and mountY define the Mount Point

Default

0 (left-most edge)

mountY

mountY: number

Y position of the Node's Mount Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Mount Point's Y position as the top-most edge of the Node
  • 0.5 defines it as the vertical center of the Node
  • 1.0 defines it as the bottom-most edge of the Node.

The combination of mountX and mountY define the Mount Point

Default

0 (top-most edge)

offsetY

offsetY: number

Vertical offset for text

Remarks

The vertical offset of the text. This property is only used if scrollable is true.

Default

0

overflowSuffix

overflowSuffix: string

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

"..."

parent

parent: null | INode<BaseShaderController>

pivot

pivot: number

Combined position of the Node's Pivot Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Pivot Point at the top-left corner of the Node.
  • 0.5 defines it at the center of the Node.
  • 1.0 defines it at the bottom-right corner of the node.

Use the pivotX and pivotY props seperately for more control of the Pivot Point.

When assigned, the same value is also passed to both the pivotX and pivotY props.

Default

0.5 (center)

pivotX

pivotX: number

X position of the Node's Pivot Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Pivot Point's X position as the left-most edge of the Node
  • 0.5 defines it as the horizontal center of the Node
  • 1.0 defines it as the right-most edge of the Node.

The combination of pivotX and pivotY define the Pivot Point

Default

0.5 (centered on x-axis)

pivotY

pivotY: number

Y position of the Node's Pivot Point

Remarks

The value can be any number between 0.0 and 1.0:

  • 0.0 defines the Pivot Point's Y position as the top-most edge of the Node
  • 0.5 defines it as the vertical center of the Node
  • 1.0 defines it as the bottom-most edge of the Node.

The combination of pivotX and pivotY define the Pivot Point

Default

0.5 (centered on y-axis)

preventCleanup

preventCleanup: boolean

Whether to prevent the node from being cleaned up

Default

false

rotation

rotation: number

Rotation of the Node (in Radians)

Remarks

Sets the amount to rotate the Node by around it's Pivot Point (defined by the pivot props). Positive values rotate the Node clockwise, while negative values rotate it counter-clockwise.

Example values:

  • -Math.PI / 2: 90 degree rotation counter-clockwise
  • 0: No rotation
  • Math.PI / 2: 90 degree rotation clockwise
  • Math.PI: 180 degree rotation clockwise
  • 3 * Math.PI / 2: 270 degree rotation clockwise
  • 2 * Math.PI: 360 rotation clockwise

rtt

rtt: boolean

Whether the Node is rendered to a texture

Remarks

TBD

Default

false

scale

scale: null | number

Scale to render the Node at

Remarks

The scale value multiplies the provided width and height of the Node around the Node's Pivot Point (defined by the pivot props).

Behind the scenes, setting this property sets both the scaleX and scaleY props to the same value.

NOTE: When the scaleX and scaleY props are explicitly set to different values, this property returns null. Setting null on this property will have no effect.

Default

1.0

scaleX

scaleX: number

Scale to render the Node at (X-Axis)

Remarks

The scaleX value multiplies the provided width of the Node around the Node's Pivot Point (defined by the pivot props).

Default

1.0

scaleY

scaleY: number

Scale to render the Node at (Y-Axis)

Remarks

The scaleY value multiplies the provided height of the Node around the Node's Pivot Point (defined by the pivot props).

Default

1.0

scrollable

scrollable: boolean

Whether or not the text is scrollable

Remarks

If scrollable is true, the text can be scrolled vertically within the bounds of the Text Node. You can set the scroll position using the scrollY property.

Default

false

scrollY

scrollY: number

Vertical scroll position for text

Remarks

The vertical scroll position of the text. This property is only used if scrollable is true.

Default

0

shader

shader: BaseShaderController

The Node's shader

Remarks

The shader defines a Shader used to draw the Node. By default, the Default Shader is used which simply draws the defined texture or color(s) within the Node without any special effects.

To create a Shader in order to set it on this property, call RendererMain.createShader.

Note: If this is a Text Node, the Shader will be managed by the Node's TextRenderer and should not be set explicitly.

src

src: null | string

Image URL

Remarks

When set, the Node's texture is automatically set to an ImageTexture using the source image URL provided (with all other settings being defaults)

OptionalsrcHeight

srcHeight?: number

The height of the rectangle from which the Image Texture will be extracted. This value can be negative. If not provided, the image's source natural height will be used.

OptionalsrcWidth

srcWidth?: number

She width of the rectangle from which the Image Texture will be extracted. This value can be negative. If not provided, the image's source natural width will be used.

OptionalsrcX

srcX?: number

The x coordinate of the reference point of the rectangle from which the Texture will be extracted. width and height are provided. And only works when createImageBitmap is available. Only works when createImageBitmap is supported on the browser.

OptionalsrcY

srcY?: number

The y coordinate of the reference point of the rectangle from which the Texture will be extracted. Only used when source srcWidth width and srcHeight height are provided. Only works when createImageBitmap is supported on the browser.

strictBounds

strictBounds: boolean

By enabling Strict bounds the renderer will not process & render child nodes of a node that is out of the visible area

Remarks

When enabled out of bound nodes, i.e. nodes that are out of the visible area, will NOT have their children processed and renderer anymore. This means the children of a out of bound node will not receive update processing such as positioning updates and will not be drawn on screen. As such the rest of the branch of the update tree that sits below this node will not be processed anymore

This is a big performance gain but may be disabled in cases where the width of the parent node is unknown and the render must process the child nodes regardless of the viewport status of the parent node

Default

false

text

text: string

Text to display

Default

''

textAlign

textAlign: "center" | "left" | "right"

Text alignment

Remarks

Alignment of the text relative to it's contained bounds. For best results, use contain mode 'width' or 'both' and a set an explicit width for the text to be aligned within.

Default

'left'

textBaseline

textBaseline: TextBaseline

Baseline for text

Remarks

This property sets the text baseline used when drawing text. Not yet implemented in the SDF renderer.

Default

alphabetic

textRendererOverride

textRendererOverride: null | (keyof TextRendererMap)

Force Text Node to use a specific Text Renderer

Remarks

By default, Text Nodes resolve the Text Renderer to use based on the font that is matched using the font family and other font selection properties.

If two fonts supported by two separate Text Renderers are matched setting this override forces the Text Node to resolve to the Text Renderer defined here.

Default

null

texture

texture: null | Texture

The Node's Texture.

Remarks

The texture defines a rasterized image that is contained within the width and height dimensions of the Node. If null, the Node will use an opaque white ColorTexture when being drawn, which essentially enables colors (including gradients) to be drawn.

If set, by default, the texture will be drawn, as is, stretched to the dimensions of the Node. This behavior can be modified by setting the TBD and TBD properties.

To create a Texture in order to set it on this property, call RendererMain.createTexture.

If the src is set on a Node, the Node will use the ImageTexture by default and the Node will simply load the image at the specified URL.

Note: If this is a Text Node, the Texture will be managed by the Node's TextRenderer and should not be set explicitly.

textureOptions

textureOptions: TextureOptions

Options to associate with the Node's Texture

verticalAlign

verticalAlign: TextVerticalAlign

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

width

width: number

The width of the Node.

Default

0

x

x: number

The x coordinate of the Node's Mount Point.

Remarks

See mountX and mountY for more information about setting the Mount Point.

Default

0

y

y: number

The y coordinate of the Node's Mount Point.

Remarks

See mountX and mountY for more information about setting the Mount Point.

Default

0

zIndex

zIndex: number

The Node's z-index.

Remarks

TBD

zIndexLocked

zIndexLocked: number

Settings

Member Visibility

On This Page

Properties