C

TextRenderSupport

Show Usages
A utility class that provides text size measurement and text placement functionality, for instance, for label rendering and measurement for the implementation of ILabelStyleRenderer.
Inheritance Hierarchy

Remarks

This class cannot be instantiated

Members

No filters for this type

Static Methods

addText

(
targetElement: any
text: string
font: Font
maximumSize?: Size
wrapping?: TextWrapping
measurePolicy?: TextMeasurePolicy
rightToLeft?: boolean
shape?: GeneralPath
): string
static
Add the text content to the provided SVG text element.
static

Parameters

targetElement: any
An SVG element to add the provided text to. When using rightToLeft, it is expected as SVGGElement otherwise as SVGTextElement.
text: string
The text content to add to the provided text element (may contain newline characters).
font: Font
The Font that defines the font properties to apply to the added text.
maximumSize?: Size
The bounds that shouldn't be exceeded when placing the text. This only has an effect when a measurePolicy other than NONE is provided. Note that if the height is too small for a single line, no text will be drawn at all. When omitted, the default is an unlimited size.
wrapping?: TextWrapping
The TextWrapping policy to apply when the text exceeds the provided maximumSize. When omitted, the default is TRIM_CHARACTER_ELLIPSIS.
measurePolicy?: TextMeasurePolicy
The measure policy to use for measuring the size of the text. When omitted, the default is AUTOMATIC.
rightToLeft?: boolean
Whether to use right-to-left text direction.
shape?: GeneralPath
A convex shape where the text lines shall be placed in. The shape is translated to (0/0) and may be cut if its bounds exceed the maximumSize.

Return Value

string
The text that was actually placed in the targetElement.

Examples

Wrapping text around at a maximum width
// wraps the given text at the maximum width, between words if possible and takes as much vertical space as needed
TextRenderSupport.addText({
  targetElement: textElement,
  text: text,
  font: font,
  wrapping: TextWrapping.WRAP_WORD,
  maximumSize: new Size(30, Infinity),
})
Cutting off a single line at a maximum width
const lineHeight = TextRenderSupport.measureText({
  text: text,
  font: font,
}).height
TextRenderSupport.addText({
  targetElement: textElement,
  text: text,
  font: font,
  wrapping: TextWrapping.WRAP_CHARACTER_ELLIPSIS,
  maximumSize: new Size(40, lineHeight),
})
Wrapping text around at a maximum width until the maximum height is reached
// wraps the given text at the maximum width, between words if possible and cuts it off at a maximum size
TextRenderSupport.addText({
  targetElement: textElement,
  text: text,
  font: font,
  wrapping: TextWrapping.WRAP_WORD,
  maximumSize: new Size(30, 60),
})

invalidateTextMeasurementCache

(specificTypeface?: Font)
static
Resets the cache that stores for a Font which actual TextMeasurePolicy is used if AUTOMATIC is set.

The AUTOMATIC policy is used in particular by LabelStyle.

Explicitly resetting the cache is usually not necessary. However, it may be necessary if custom CSS rules that affect text measurement are added to the web page after the text measurement policy is already selected.

static

Parameters

specificTypeface?: Font
The specific Font to invalidate the cache for, or null in case the cache should be invalidated for all Fonts.

See Also

API
measureText, addText

measureText

(
text: string
font: Font
maximumSize?: Size
wrapping?: TextWrapping
measurePolicy?: TextMeasurePolicy
): Size
static
Calculates the width and height required to render the provided text using the provided Font, taking text-wrapping into account.
The resulting height is calculated using the maximum height for the largest glyph in the provided font, irrespective of the actual text. I.e. '_' and 'I' are assumed to be of the same height.
static

Parameters

text: string
The text that should be measured.
font: Font
The Font to apply to the text before measuring.
maximumSize?: Size
The bounds that shouldn't be exceeded when placing the text. When omitted, the default is an unlimited size.
wrapping?: TextWrapping
The TextWrapping policy to apply when the text exceeds the provided maximumSize. When omitted, the default is NONE.
measurePolicy?: TextMeasurePolicy
The measure policy to use for measuring the size of the text; AUTOMATIC per default.

Return Value

Size
The size of the measured text.

Examples

General usage
// Measures the size a text element with this text and font would require.
const size = TextRenderSupport.measureText({
  text: 'some text',
  font: font,
})
Measure required text element size if text is to be wrapped around at a maximum width
// Measures the size a text element with this text and font would require if it were word wrapped at the given width.
TextRenderSupport.addText({
  targetElement: textElement,
  text: 'some text',
  font: font,
  wrapping: TextWrapping.WRAP_WORD,
  maximumSize: new Size(60, Infinity),
})
Measure required text element size when text is wrapped around at a maximum width until a maximum height has been reached
// Measures the size a text element with this text and font would require if it were word wrapped at the given width and cut off at the maximum height.
// This takes the size of the text ellipsis into account (if any)
TextRenderSupport.addText({
  targetElement: textElement,
  text: 'a very long text, longer than what would fit into 30*50',
  font: font,
  wrapping: TextWrapping.WRAP_CHARACTER_ELLIPSIS,
  maximumSize: new Size(30, 50),
})