PixiJS

Class: TextMetrics

PIXI.TextMetrics

The TextMetrics object represents the measurement of a block of text with a specified style.

new PIXI.TextMetrics (text, style, width, height, lines, lineWidths, lineHeight, maxLineWidth, fontProperties)

TextMetrics.ts:205
Name Type Description
text string

the text that was measured
style PIXI.TextStyle

the style that was measured
width number

the measured width of the text
height number

the measured height of the text
lines string[]

an array of the lines of text broken by new lines and wrapping if specified in style
lineWidths number[]

an array of the line widths for each line matched to lines
lineHeight number

the measured line height for this style
maxLineWidth number

the maximum line width for all measured lines
fontProperties PIXI.IFontMetrics

the font properties object from TextMetrics.measureFont

Example

 import { TextMetrics, TextStyle } from 'pixi.js';

 const style = new TextStyle({
     fontFamily: 'Arial',
     fontSize: 24,
     fill: 0xff1010,
     align: 'center',
 });
 const textMetrics = TextMetrics.measureText('Your text', style);

Members

PIXI.TextMetrics.BASELINE_MULTIPLIER number static

Baseline multiplier for calculate font metrics.

Default Value:
  • 1.4

PIXI.TextMetrics.BASELINE_SYMBOL string static

Baseline symbol for calculate font metrics.

Default Value:
  • "M"

PIXI.TextMetrics.experimentalLetterSpacing boolean static

New rendering behavior for letter-spacing which uses Chrome's new native API. This will lead to more accurate letter-spacing results because it does not try to manually draw each character. However, this Chrome API is experimental and may not serve all cases yet.

Default Value:
  • false
See:

PIXI.TextMetrics.experimentalLetterSpacingSupported boolean static

Checking that we can use modern canvas 2D API.

Note: This is an unstable API, Chrome < 94 use textLetterSpacing, later versions use letterSpacing.

See:

PIXI.TextMetrics.graphemeSegmenter (s: string) => string[] static

A Unicode "character", or "grapheme cluster", can be composed of multiple Unicode code points, such as letters with diacritical marks (e.g. '\u0065\u0301', letter e with acute) or emojis with modifiers (e.g. '\uD83E\uDDD1\u200D\uD83D\uDCBB', technologist). The new Intl.Segmenter API in ES2022 can split the string into grapheme clusters correctly. If it is not available, PixiJS will fallback to use the iterator of String, which can only spilt the string into code points. If you want to get full functionality in environments that don't support Intl.Segmenter (such as Firefox), you can use other libraries such as grapheme-splitter or graphemer to create a polyfill. Since these libraries can be relatively large in size to handle various Unicode grapheme clusters properly, PixiJS won't use them directly.

PIXI.TextMetrics.HEIGHT_MULTIPLIER number static

Height multiplier for setting height of canvas to calculate font metrics.

Default Value:
  • 2

PIXI.TextMetrics.METRICS_STRING string static

String used for calculate font metrics. These characters are all tall to help calculate the height required for text.

Default Value:
  • "|ÉqÅ"

fontProperties PIXI.IFontMetrics

The font properties object from TextMetrics.measureFont.

height number

The measured height of the text.

lineHeight number

The measured line height for this style.

lines string[]

An array of lines of the text broken by new lines and wrapping is specified in style.

lineWidths number[]

An array of the line widths for each line matched to lines.

maxLineWidth number

The maximum line width for all measured lines.

style PIXI.TextStyle

The style that was measured.

text string

The text that was measured.

width number

The measured width of the text.

Methods

PIXI.TextMetrics.canBreakChars (_char, _nextChar, _token, _index, _breakWords) boolean static

TextMetrics.ts:721

Overridable helper method used internally by TextMetrics, exposed to allow customizing the class's behavior.

It allows one to determine whether a pair of characters should be broken by newlines For example certain characters in CJK langs or numbers. It must return a boolean.

Name Type Description
_char string

The character
_nextChar string

The next character
_token string

The token/word the characters are from
_index number

The index in the token of the char
_breakWords boolean

The style attr break words
Returns:
Type Description
boolean whether to break word or not

PIXI.TextMetrics.canBreakWords (_token, breakWords) boolean static

TextMetrics.ts:706

Overridable helper method used internally by TextMetrics, exposed to allow customizing the class's behavior.

It allows one to customise which words should break Examples are if the token is CJK or numbers. It must return a boolean.

Name Type Description
_token string

The token
breakWords boolean

The style attr break words
Returns:
Type Description
boolean Whether to break word or not

PIXI.TextMetrics.clearMetrics (font) void static

TextMetrics.ts:870

Clear font metrics in metrics cache.

Name Type Attributes Default Description
font string <optional>
 ''

font name. If font name not set then clear cache for all fonts.

PIXI.TextMetrics.isBreakingSpace (char, _nextChar) boolean static

TextMetrics.ts:642

Determines if char is a breaking whitespace.

It allows one to determine whether char should be a breaking whitespace For example certain characters in CJK langs or numbers. It must return a boolean.

Name Type Attributes Description
char string

The character
_nextChar string <optional>

The next character
Returns:
Type Description
boolean True if whitespace, False otherwise.

PIXI.TextMetrics.measureFont (font) PIXI.IFontMetrics static

TextMetrics.ts:756

Calculates the ascent, descent and fontSize of a given font-style

Name Type Description
font string

String representing the style of the font
Returns:
Type Description
PIXI.IFontMetrics Font properties object

PIXI.TextMetrics.measureText (text, style, wordWrap, canvas) PIXI.TextMetrics static

TextMetrics.ts:230

Measures the supplied string of text and returns a Rectangle.

Name Type Attributes Description
text string

The text to measure.
style PIXI.TextStyle

The text style to use for measuring
wordWrap boolean <optional>

Override for if word-wrap should be applied to the text.
canvas PIXI.ICanvas

optional specification of the canvas to use for measuring.
Returns:
Type Description
PIXI.TextMetrics Measured width and height of the text.

PIXI.TextMetrics.wordWrapSplit (token) string[] static

TextMetrics.ts:741

Overridable helper method used internally by TextMetrics, exposed to allow customizing the class's behavior.

It is called when a token (usually a word) has to be split into separate pieces in order to determine the point to break a word. It must return an array of characters.

Name Type Description
token string

The token to split
See:
  • TextMetrics.graphemeSegmenter
Returns:
Type Description
string[] The characters of the token