Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:21

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

Example

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

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

Advanced

Constructors

Constructor

> new CanvasTextMetrics(text, style, width, height, lines, lineWidths, lineHeight, maxLineWidth, fontProperties, taggedData?): CanvasTextMetrics

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:138

Parameters

text

string

the text that was measured

style

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

FontMetrics

the font properties object from TextMetrics.measureFont

taggedData?

optional object containing tagged text specific data

hasDropShadow?

boolean

whether any run has a drop shadow

lineAscents?

number[]

per-line ascent values for tagged text

lineDescents?

number[]

per-line descent values for tagged text

lineHeights?

number[]

per-line height values for tagged text

runsByLine?

TextStyleRun[][]

per-line style runs for tagged text

Returns

CanvasTextMetrics

Properties

fontProperties

> fontProperties: FontMetrics

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:39

The font properties object from TextMetrics.measureFont.

hasDropShadow?

> optional hasDropShadow?: boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:74

Internal

Whether any run in the tagged text has a drop shadow. Cached during measurement to avoid per-render iteration. Only populated when text contains tag markup.

height

> height: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:29

The measured height of the text.

lineAscents?

> optional lineAscents?: number[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:53

Internal

Per-line ascent values for tagged text with mixed fonts. Represents the max ascent across all runs on each line. Only populated when text contains tag markup.

lineDescents?

> optional lineDescents?: number[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:60

Internal

Per-line descent values for tagged text with mixed fonts. Represents the max descent across all runs on each line. Only populated when text contains tag markup.

lineHeight

> lineHeight: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:35

The measured line height for this style.

lineHeights?

> optional lineHeights?: number[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:67

Internal

Per-line heights for tagged text with mixed fonts. Each line may have different height based on the fonts used. Only populated when text contains tag markup.

lines

> lines: string[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:31

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

lineWidths

> lineWidths: number[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:33

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

maxLineWidth

> maxLineWidth: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:37

The maximum line width for all measured lines.

runsByLine?

> optional runsByLine?: TextStyleRun[][]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:46

Internal

Per-line style runs for tagged text rendering. Each element is an array of runs for that line. Only populated when text contains tag markup.

style

> style: TextStyle

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:25

The style that was measured.

text

> text: string

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:23

The text that was measured.

width

> width: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:27

The measured width of the text.

_experimentalLetterSpacingSupported?

> static optional _experimentalLetterSpacingSupported?: boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:98

BASELINE_MULTIPLIER

> static BASELINE_MULTIPLIER: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:83

Baseline multiplier for calculate font metrics.

BASELINE_SYMBOL

> static BASELINE_SYMBOL: string

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:81

Baseline symbol for calculate font metrics.

experimentalLetterSpacing

> static experimentalLetterSpacing: boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:114

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.

See

CanvasTextMetrics.experimentalLetterSpacingSupported

graphemeSegmenter

> static graphemeSegmenter: (s) => string[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:97

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]https://www.npmjs.com/package/grapheme-splitter or [graphemer]https://www.npmjs.com/package/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.

Parameters

s

string

Returns

string[]

HEIGHT_MULTIPLIER

> static HEIGHT_MULTIPLIER: number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:85

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

METRICS_STRING

> static METRICS_STRING: string

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:79

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

Accessors

experimentalLetterSpacingSupported

Get Signature

> get static experimentalLetterSpacingSupported(): boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:107

Checking that we can use modern canvas 2D API.

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

See

CanvasTextMetrics.experimentalLetterSpacing
https://developer.mozilla.org/en-US/docs/Web/API/ICanvasRenderingContext2D/letterSpacing
https://developer.chrome.com/origintrials/#/view_trial/3585991203293757441

Returns

boolean

Methods

_measureText()

> static _measureText(text, letterSpacing, context): number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:177

Internal

Measures the rendered width of a string, accounting for letter spacing and using the provided context. Returns the larger of the advance width and the bounding box width.

Parameters

text

string

The text to measure

letterSpacing

number

Letter spacing in pixels

context

ICanvasRenderingContext2D

Canvas 2D context

Returns

number

The measured width of the text with spacing

_measureTextAdvance()

> static _measureTextAdvance(text, letterSpacing, context): number

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:187

Internal

Measures advance width only (no bounding box). Advance widths are additive, making this suitable for word wrap line-fitting where per-token widths must sum correctly.

Parameters

text

string

The text to measure

letterSpacing

number

Letter spacing in pixels

context

ICanvasRenderingContext2D

Canvas 2D context

Returns

number

The advance width of the text

canBreakChars()

> static canBreakChars(_char, _nextChar, _token, _index, _breakWords): boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:242

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.

Parameters

_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

boolean

whether to break word or not

canBreakWords()

> static canBreakWords(_token, breakWords): boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:227

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.

Parameters

_token

string

The token

breakWords

boolean

The style attr break words

Returns

boolean

Whether to break word or not

clearMetrics()

> static clearMetrics(font?): void

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:264

Clear font metrics in metrics cache.

Parameters

font?

string

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

Returns

void

isBreakingSpace()

> static isBreakingSpace(char, _nextChar?): boolean

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:216

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.

Parameters

char

string

The character

_nextChar?

string

The next character

Returns

boolean

True if whitespace, False otherwise.

measureFont()

> static measureFont(font): FontMetrics

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:259

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

Parameters

font

string

String representing the style of the font

Returns

FontMetrics

Font properties object

measureText()

> static measureText(text, style, canvas?, wordWrap?): CanvasTextMetrics

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:153

Measures the supplied string of text and returns a Rectangle.

Parameters

text

string

The text to measure.

style

TextStyle

The text style to use for measuring

canvas?

ICanvas

optional specification of the canvas to use for measuring.

wordWrap?

boolean

Returns

CanvasTextMetrics

Measured width and height of the text.

wordWrapSplit()

> static wordWrapSplit(token): string[]

Defined in: node_modules/pixi.js/lib/scene/text/canvas/CanvasTextMetrics.d.ts:253

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.

Parameters

token

string

The token to split

Returns

string[]

The characters of the token

See

CanvasTextMetrics.graphemeSegmenter

Class: CanvasTextMetrics

Example

Advanced

Constructors

Constructor

Parameters

text

style

width

height

lines

lineWidths

lineHeight

maxLineWidth

fontProperties

taggedData?

hasDropShadow?

lineAscents?

lineDescents?

lineHeights?

runsByLine?

Returns

Properties

fontProperties

hasDropShadow?

height

lineAscents?

lineDescents?

lineHeight

lineHeights?

lines

lineWidths

maxLineWidth

runsByLine?

style

text

width

_experimentalLetterSpacingSupported?

BASELINE_MULTIPLIER

BASELINE_SYMBOL

experimentalLetterSpacing

See

graphemeSegmenter

Parameters

s

Returns

HEIGHT_MULTIPLIER

METRICS_STRING

Accessors

experimentalLetterSpacingSupported

Get Signature

See

Returns

Methods

_measureText()

Parameters

text

letterSpacing

context

Returns

_measureTextAdvance()

Parameters

text

letterSpacing

context

Returns

canBreakChars()

Parameters

_char

_nextChar

_token

_index

_breakWords

Returns

canBreakWords()

Parameters

_token

breakWords

Returns

clearMetrics()