Text Measurement

/**
 * Creates a TextMetrics object with measurement results
 * @param text - The measured text string
 * @param style - The TextStyle used for measurement
 * @param width - Total measured width
 * @param height - Total measured height
 * @param lines - Array of text lines after wrapping
 * @param lineWidths - Width of each individual line
 * @param lineHeight - Line height used for measurement
 * @param maxLineWidth - Maximum width among all lines
 * @param fontProperties - Font metrics data
 */
constructor(
  text: string, 
  style: TextStyle, 
  width: number, 
  height: number,
  lines: string[], 
  lineWidths: number[], 
  lineHeight: number, 
  maxLineWidth: number, 
  fontProperties: IFontMetrics
);

/**
 * Measures text dimensions and returns comprehensive metrics
 * @param text - Text string to measure
 * @param style - TextStyle configuration for measurement
 * @param wordWrap - Override word wrap setting (uses style.wordWrap if undefined)
 * @param canvas - Optional canvas for measurement (uses internal canvas if not provided)
 * @returns Complete TextMetrics with dimensions and line data
 */
static measureText(
  text: string,
  style: TextStyle,
  wordWrap?: boolean,
  canvas?: HTMLCanvasElement | OffscreenCanvas
): TextMetrics;

import { TextMetrics, TextStyle } from "@pixi/text";

const style = new TextStyle({
  fontSize: 24,
  fontFamily: 'Arial',
  wordWrap: true,
  wordWrapWidth: 300
});

// Basic measurement
const metrics = TextMetrics.measureText('Hello World', style);
console.log(`Size: ${metrics.width}x${metrics.height}`);

// Measure with custom word wrap setting
const noWrapMetrics = TextMetrics.measureText(
  'This is a long text that would normally wrap',
  style,
  false  // Disable word wrap for this measurement
);

// Measure with custom canvas
const canvas = document.createElement('canvas');
const customMetrics = TextMetrics.measureText('Custom canvas', style, true, canvas);

/**
 * Calculates font metrics for a given font string
 * @param font - CSS font string (e.g., "24px Arial")
 * @returns Font metrics with ascent, descent, and fontSize
 */
static measureFont(font: string): IFontMetrics;

interface IFontMetrics {
  /** Distance from baseline to top of tallest characters */
  ascent: number;
  /** Distance from baseline to bottom of lowest characters */
  descent: number;
  /** Total font height (ascent + descent) */
  fontSize: number;
}

// Measure font metrics
const fontMetrics = TextMetrics.measureFont('24px Arial');
console.log(`Ascent: ${fontMetrics.ascent}`);
console.log(`Descent: ${fontMetrics.descent}`);
console.log(`Font size: ${fontMetrics.fontSize}`);

// Use with TextStyle
const style = new TextStyle({ fontSize: 32, fontFamily: 'Helvetica' });
const fontString = style.toFontString();
const metrics = TextMetrics.measureFont(fontString);

/**
 * Clears cached font metrics
 * @param font - Specific font to clear, or empty string to clear all
 */
static clearMetrics(font?: string): void;

// Clear all cached metrics
TextMetrics.clearMetrics();

// Clear specific font metrics
TextMetrics.clearMetrics('24px Arial');

// Clear with empty string (same as clearMetrics())
TextMetrics.clearMetrics('');

/**
 * The original text that was measured
 */
text: string;

/**
 * The TextStyle used for measurement
 */
style: TextStyle;

/**
 * Total width including effects like stroke and drop shadow
 */
width: number;

/**
 * Total height including line spacing and effects
 */
height: number;

/**
 * Array of text lines after word wrapping and line breaks
 */
lines: string[];

/**
 * Width of each individual line
 */
lineWidths: number[];

/**
 * Line height value used for measurement
 */
lineHeight: number;

/**
 * Maximum width among all lines
 */
maxLineWidth: number;

/**
 * Font metrics data for the measured font
 */
fontProperties: IFontMetrics;

const metrics = TextMetrics.measureText('Multi-line\ntext sample', style);

// Access measurement data
console.log(`Total size: ${metrics.width}x${metrics.height}`);
console.log(`Number of lines: ${metrics.lines.length}`);
console.log(`Lines: ${metrics.lines.join(', ')}`);
console.log(`Line widths: ${metrics.lineWidths.join(', ')}`);
console.log(`Max line width: ${metrics.maxLineWidth}`);
console.log(`Font ascent: ${metrics.fontProperties.ascent}`);

/**
 * Determines if a character is a breaking whitespace
 * @param char - Character to check
 * @param nextChar - Optional next character for context
 * @returns True if character should break lines/words
 */
static isBreakingSpace(char: string, nextChar?: string): boolean;

/**
 * Determines if words can be broken at character level
 * @param token - Word/token to check
 * @param breakWords - Style setting for word breaking
 * @returns True if word can be broken
 */
static canBreakWords(token: string, breakWords: boolean): boolean;

/**
 * Determines if specific characters can be broken between
 * @param char - Current character
 * @param nextChar - Next character
 * @param token - Full word/token
 * @param index - Character position in token
 * @param breakWords - Style setting for word breaking
 * @returns True if break is allowed between characters
 */
static canBreakChars(
  char: string, 
  nextChar: string, 
  token: string, 
  index: number,
  breakWords: boolean
): boolean;

/**
 * Splits a token into individual characters for word breaking
 * @param token - Token to split
 * @returns Array of character strings
 */
static wordWrapSplit(token: string): string[];

// Check breaking spaces
const isSpace = TextMetrics.isBreakingSpace(' ');
const isTab = TextMetrics.isBreakingSpace('\t');

// Check word breaking
const canBreak = TextMetrics.canBreakWords('supercalifragilisticexpialidocious', true);

// Check character breaking
const canBreakHere = TextMetrics.canBreakChars('a', 'b', 'word', 0, true);

// Split token for breaking
const chars = TextMetrics.wordWrapSplit('hello');
console.log(chars); // ['h', 'e', 'l', 'l', 'o']

/**
 * Internal canvas used for text measurement
 * Automatically created as HTMLCanvas or OffscreenCanvas based on environment
 */
static get _canvas(): HTMLCanvasElement | OffscreenCanvas;

/**
 * Internal 2D context for measurement operations
 */
static get _context(): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;

// Access measurement canvas
const measurementCanvas = TextMetrics._canvas;
console.log(`Canvas size: ${measurementCanvas.width}x${measurementCanvas.height}`);

// Access measurement context (advanced usage)
const ctx = TextMetrics._context;
ctx.font = '16px Arial';
const width = ctx.measureText('test').width;

/**
 * String used for font metrics calculation
 * Contains tall characters to measure full font height
 */
static METRICS_STRING: string; // '|ÉqÅ'

/**
 * Baseline symbol for font measurement
 */
static BASELINE_SYMBOL: string; // 'M'

/**
 * Multiplier for baseline calculation
 */
static BASELINE_MULTIPLIER: number; // 1.4

/**
 * Multiplier for canvas height during measurement
 */
static HEIGHT_MULTIPLIER: number; // 2.0

// Access measurement constants
console.log(`Metrics string: ${TextMetrics.METRICS_STRING}`);
console.log(`Baseline symbol: ${TextMetrics.BASELINE_SYMBOL}`);
console.log(`Baseline multiplier: ${TextMetrics.BASELINE_MULTIPLIER}`);

import { TextStyle, TextMetrics } from "@pixi/text";

const styles = [
  new TextStyle({ fontSize: 16 }),
  new TextStyle({ fontSize: 24 }),
  new TextStyle({ fontSize: 32 })
];

const texts = ['Small', 'Medium', 'Large'];

// Pre-calculate dimensions for layout
const measurements = texts.map((text, i) => ({
  text,
  style: styles[i],
  metrics: TextMetrics.measureText(text, styles[i])
}));

// Use measurements for layout calculations
let totalHeight = 0;
measurements.forEach(({ metrics }) => {
  totalHeight += metrics.height + 10; // 10px spacing
});

// Wait for font to load, then measure
document.fonts.ready.then(() => {
  // Clear cached metrics after font loads
  TextMetrics.clearMetrics();
  
  const style = new TextStyle({
    fontFamily: 'MyCustomFont',
    fontSize: 24
  });
  
  const metrics = TextMetrics.measureText('Custom font text', style);
  console.log(`Measured size: ${metrics.width}x${metrics.height}`);
});

const longText = 'This is a very long text that will be wrapped across multiple lines when the word wrap width is set to a specific value.';

const style = new TextStyle({
  fontSize: 16,
  wordWrap: true,
  wordWrapWidth: 200
});

const metrics = TextMetrics.measureText(longText, style);

console.log(`Original text length: ${longText.length}`);
console.log(`Number of lines: ${metrics.lines.length}`);
console.log(`Lines:`);
metrics.lines.forEach((line, i) => {
  console.log(`  ${i + 1}: "${line}" (width: ${metrics.lineWidths[i]})`);
});

// Batch measurements for better performance
const textsToMeasure = ['Text 1', 'Text 2', 'Text 3'];
const style = new TextStyle({ fontSize: 18 });

// Use the same canvas for all measurements
const canvas = document.createElement('canvas');
const measurements = textsToMeasure.map(text =>
  TextMetrics.measureText(text, style, undefined, canvas)
);

// Clear metrics cache when done
TextMetrics.clearMetrics();