Interface Settings

Text Texture Settings

interface Settings {
    advancedRenderer?: boolean;
    cutEx?: number;
    cutEy?: number;
    cutSx?: number;
    cutSy?: number;
    fontBaselineRatio?: number;
    fontFace?: null | string | string[];
    fontSize?: number;
    fontStyle?: string;
    h?: number;
    highlight?: boolean;
    highlightColor?: number;
    highlightHeight?: number;
    highlightOffset?: number;
    highlightPaddingLeft?: number;
    highlightPaddingRight?: number;
    letterSpacing?: number;
    lineHeight?: null | number;
    maxLines?: number;
    maxLinesSuffix?: string;
    offsetY?: null | number;
    paddingLeft?: number;
    paddingRight?: number;
    precision?: number;
    resizeMode?: null | ResizeMode;
    shadow?: boolean;
    shadowBlur?: number;
    shadowColor?: number;
    shadowOffsetX?: number;
    shadowOffsetY?: number;
    text?: string;
    textAlign?: TextAlign;
    textBaseline?: TextBaseline;
    textColor?: number;
    textIndent?: number;
    textOverflow?: null | TextOverflow;
    type?: typeof Lightning.textures.TextTexture;
    verticalAlign?: TextVerticalAlign;
    w?: number;
    wordBreak?: boolean;
    wordWrap?: boolean;
    wordWrapWidth?: number;
    x?: number;
    y?: number;
}

Hierarchy (View Summary)

Properties

advancedRenderer? cutEx? cutEy? cutSx? cutSy? fontBaselineRatio? fontFace? fontSize? fontStyle? h? highlight? highlightColor? highlightHeight? highlightOffset? highlightPaddingLeft? highlightPaddingRight? letterSpacing? lineHeight? maxLines? maxLinesSuffix? offsetY? paddingLeft? paddingRight? precision? resizeMode? shadow? shadowBlur? shadowColor? shadowOffsetX? shadowOffsetY? text? textAlign? textBaseline? textColor? textIndent? textOverflow? type? verticalAlign? w? wordBreak? wordWrap? wordWrapWidth? x? y?

Properties

OptionaladvancedRenderer

advancedRenderer?: boolean

Enables the Advanced Text Renderer

Remarks

The Advanced Text Renderer adds support for:

  • <b> tag for bold text
    • Example: <b>This is bold</b>
  • <i> tag for italics text
    • Example: <i>This is italics</i>
  • <color=$ARGB> tag for colored text
    • Example: <color=0xff00ff00>This is green</color>
  • Enables the use of wordBreak

See: https://github.com/rdkcentral/Lightning/pull/318 for more details

Default Value

false

See

OptionalcutEx

cutEx?: number

X coordinate of text cutting end position (in pixels)

Default Value

0

OptionalcutEy

cutEy?: number

Y coordinate of text cutting end position (in pixels)

Default Value

0

OptionalcutSx

cutSx?: number

X coordinate of text cutting start position (in pixels)

Default Value

0

OptionalcutSy

cutSy?: number

Y coordinate of text cutting start position (in pixels)

Default Value

0

OptionalfontBaselineRatio

fontBaselineRatio?: number

Font baseline ratio (Advanced Text Renderer only)

Remarks

This can be used to improve vertical text alignment when using the Advanced Text Renderer.

You MUST enable advancedRenderer in order to use this.

See PR #378 for more information about this feature.

To calculate the ratio for a particular font face, you can do this calculation from font metadata:

    (head.unitsPerEm − hhea.Ascender − hhea.Descender) / (2 × head.unitsPerEm)

This give you the ratio for the baseline, which is then used to figure out where the baseline is relative to the bottom of the text bounding box.

The input values can be retrieved using the opentype.js Font Inspector.

Default Value

0

OptionalfontFace

fontFace?: null | string | string[]

Font family

Remarks

If an array is provided, font families that appear later in the array are used as fallbacks. If the (default) null value is specified, the font family value specified in the defaultFontFace Stage Option is used. If the resolved font family (or families) is unavailable to the browser, a fallback is chosen by the browser. The special CSS defined font family values of "serif" and "sans-serif" may be used as well.

Default Value

null (uses Stage.Options.defaultFontFace)

OptionalfontSize

fontSize?: number

Font size (in pixels)

Default Value

40

OptionalfontStyle

fontStyle?: string

Font style

Default Value

"normal"

Optionalh

h?: number

Texture clipping height

Remarks

If 0 then shows full width.

This should not be set at the same time as resizeMode.

See Clipping for more information.

Optionalhighlight

highlight?: boolean

Highlight mode

Remarks

If set, enables a solid color highlight behind the rendered text controlled by these properties:

Default Value

false

OptionalhighlightColor

highlightColor?: number

Highlight color

Remarks

highlight must be enabled for this property to have any affect.

Default Value

0xFF000000 (black)

OptionalhighlightHeight

highlightHeight?: number

Highlight height (in pixels)

Remarks

highlight must be enabled for this property to have any affect.

Default Value

0 (fontSize multiplied by 1.5)

OptionalhighlightOffset

highlightOffset?: number

Highlight Y offset (in pixels)

Remarks

Shifts the rendered highlight blocks down the Y-axis.

highlight must be enabled for this property to have any affect.

Default Value

0

OptionalhighlightPaddingLeft

highlightPaddingLeft?: number

Highlight left padding (in pixels)

Remarks

  • If > 0:
    • Adds additional highlight to the left of each highlighted line.
  • If < 0:
    • Removes highlight from the left side of each highlighted line.

highlight must be enabled for this property to have any affect.

Default Value

0

OptionalhighlightPaddingRight

highlightPaddingRight?: number

Highlight right padding (in pixels)

Remarks

  • If > 0:
    • Adds additional highlight to the right of each highlighted line.
  • If < 0:
    • Removes highlight from the right side of each highlighted line.

highlight must be enabled for this property to have any affect.

Default Value

0

OptionalletterSpacing

letterSpacing?: number

Spacing between letters

Remarks

Adds or removes spacing between letters. Negative values are allowed.

Warning: Setting this to anything but 0 can slow down the rendering of text.

Default Value

0 (disabled)

OptionallineHeight

lineHeight?: null | number

Line height (in pixels)

Default Value

null

OptionalmaxLines

maxLines?: number

Maximum number of lines to display before truncation

Remarks

If this is set to a value greater than 0, multiline text will be truncated at this number of lines. The maxLinesSuffix will be inserted at the end of the last rendered line of text.

Default Value

0 (line truncation disabled)

OptionalmaxLinesSuffix

maxLinesSuffix?: string

String rendered at the end of a truncated line of text

Remarks

This suffix is used in the following situations:

Default Value

".."

OptionaloffsetY

offsetY?: null | number

Text Y offset (in pixels)

Remarks

Translates the position of rendered text along the Y-axis.

This value must be equal to at least the fontSize (which is the default) for the first line of text to be completely visible in the texture. If set to 0, the first line of text will be completely clipped.

Default Value

null (fontSize)

OptionalpaddingLeft

paddingLeft?: number

Padding left (in pixels)

Remarks

Using this will result in a larger texture size allocation.

OptionalpaddingRight

paddingRight?: number

Padding right (in pixels)

Remarks

Using this will result in a larger texture size allocation.

Optionalprecision

precision?: number

Render precision of text

See

Stage.Options.precision

Default Value

Stage.Options.precision stage option

OptionalresizeMode

resizeMode?: null | ResizeMode

Texture resize mode (Automatic resize + clipping)

Remarks

When set, enables automatic clipping to a specific rectangular area.

Note: resizeMode actually modifies the following texture clipping properties, so it should not be set at the same time as them:

See Clipping - ResizeMode for more information.

Default Value

null (disabled)

Optionalshadow

shadow?: boolean

Text shadow mode

Remarks

If set, enables a text shadow behind the rendered text controlled by these properties:

See CanvasRenderingContext2D - Shadows (MDN) for more information on the properties that determine shadows.

Default Value

false

OptionalshadowBlur

shadowBlur?: number

Text shadow blur iterations

Remarks

shadow must be enabled for this property to have any affect.

See CanvasRenderingContext2D.shadowBlur (MDN) for more information on this property.

Default Value

5

OptionalshadowColor

shadowColor?: number

Text shadow color

Remarks

shadow must be enabled for this property to have any affect.

See CanvasRenderingContext2D.shadowColor (MDN) for more information on this property.

Default Value

0xFF000000 (black)

OptionalshadowOffsetX

shadowOffsetX?: number

Text shadow X offset (in pixels)

Remarks

shadow must be enabled for this property to have any affect.

See CanvasRenderingContext2D.shadowOffsetX (MDN) for more information on this property.

Default Value

0

OptionalshadowOffsetY

shadowOffsetY?: number

Text shadow Y offset

Remarks

shadow must be enabled for this property to have any affect.

See CanvasRenderingContext2D.shadowOffsetY (MDN) for more information on this property.

Default Value

0

Optionaltext

text?: string

Text to display

Default Value

""

OptionaltextAlign

textAlign?: TextAlign

Horizontal text alignment

Default Value

"left"

OptionaltextBaseline

textBaseline?: TextBaseline

Text baseline

Remarks

See CanvasRenderingContext2D.textBaseline (MDN) for the available options.

Default Value

"alphabetic"

OptionaltextColor

textColor?: number

Text color

Default Value

0xFFFFFFFF (white)

OptionaltextIndent

textIndent?: number

Indent of the first line of text (in pixels)

Default Value

0

OptionaltextOverflow

textOverflow?: null | TextOverflow

Text overflow mode

Remarks

When enabled, truncates long blocks of text with a suffix (like "..") to the size specified in wordWrapWidth. wordWrap must be disabled for this to work.

Values

  • "ellipsis": Truncated text will end in maxLinesSuffix.
  • "clip": Truncated text will not end in a suffix.
  • any string: Truncated text will end in this user-defined suffix.

Default Value

null (disabled)

Optionaltype

type?: typeof Lightning.textures.TextTexture

OptionalverticalAlign

verticalAlign?: TextVerticalAlign

Vertical text aligment

Remarks

If lineHeight is larger than fontSize, this value specifies how text should be aligned vertically inside each line.

Default Value

"top"

Optionalw

w?: number

Texture clipping width

Remarks

If 0 then shows full width.

This should not be set at the same time as resizeMode.

See Clipping for more information.

OptionalwordBreak

wordBreak?: boolean

Word Breaking mode (Advanced Text Renderer only)

Remarks

When enabled, words that overflow the set width of the texture will be broken to another line.

You MUST enable advancedRenderer in order to use this.

Default Value

false

OptionalwordWrap

wordWrap?: boolean

Word wrap mode

Remarks

When enabled (default), long lines that exceed wordWrapWidth will be be broken into new lines.

Default Value

true

OptionalwordWrapWidth

wordWrapWidth?: number

Word wrap width (in pixels)

Remarks

  • When wordWrap is enabled:
    • Long lines that exceed this width will be broken into new lines.
  • When wordWrap is disabled AND when textOverflow is enabled:
    • Text that exceeds this width will be truncated.

Default Value

0

Optionalx

x?: number

Texture clipping x-offset

Remarks

This should not be set at the same time as resizeMode.

See Clipping for more information.

Optionaly

y?: number

Texture clipping x-offset

Remarks

This should not be set at the same time as resizeMode.

See Clipping for more information.

Settings

Member Visibility

On This Page

Properties