or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

2d-controls.md2d-layout.md3d-controls.md3d-materials.mdindex.mdinput-controls.mdutilities.md
tile.json

utilities.mddocs/

Utilities

Utility classes for measurements, styling, gradients, and value parsing that support both 2D and 3D GUI systems.

Capabilities

Measurement and Sizing

Classes for handling dimensions, positioning, and size calculations.

class Measure {
  constructor(left: number, top: number, width: number, height: number);
  
  left: number;
  top: number;
  width: number;
  height: number;

  copyFrom(other: Measure): void;
  copyFromFloats(left: number, top: number, width: number, height: number): void;
  isEqualsTo(other: Measure): boolean;
  
  static Empty(): Measure;
}

Usage Examples:

import { Measure } from "@babylonjs/gui";

// Create a measure
const measure = new Measure(10, 20, 100, 50);
console.log(measure.left, measure.top, measure.width, measure.height);

// Copy from another measure
const measure2 = new Measure(0, 0, 0, 0);
measure2.copyFrom(measure);

// Create empty measure
const emptyMeasure = Measure.Empty();

// Check equality
if (measure.isEqualsTo(measure2)) {
    console.log("Measures are equal");
}

Value and Unit System

CSS-like value and unit parsing for flexible sizing and positioning.

class ValueAndUnit {
  constructor(value: number, unit?: number, negativeValueAllowed?: boolean);
  
  value: number;
  unit: number;
  negativeValueAllowed: boolean;
  ignoreAdaptiveScaling: boolean;

  readonly isPercentage: boolean;
  readonly isPixel: boolean;

  onChangedObservable: Observable<void>;

  getValue(host: Control): number;
  getValueInPixel(host: AdvancedDynamicTexture, refValue: number): number;
  toString(): string;
  fromString(source: string | number): boolean;
  
  static Parse(source: string): ValueAndUnit;
  
  // Unit mode constants
  static readonly UNITMODE_PERCENTAGE: number;
  static readonly UNITMODE_PIXEL: number;
}

Usage Examples:

import { ValueAndUnit, Control } from "@babylonjs/gui";

// Create pixel-based value
const pixelValue = new ValueAndUnit(100, ValueAndUnit.UNITMODE_PIXEL);
console.log(pixelValue.toString()); // "100px"

// Create percentage-based value
const percentValue = new ValueAndUnit(50, ValueAndUnit.UNITMODE_PERCENTAGE);
console.log(percentValue.toString()); // "50%"

// Parse from string
const parsedValue = ValueAndUnit.Parse("75%");
console.log(parsedValue.value, parsedValue.isPercentage); // 75, true

// Use with controls
const button = Button.CreateSimpleButton("btn", "Click");
button.width = new ValueAndUnit(200, ValueAndUnit.UNITMODE_PIXEL);
button.height = new ValueAndUnit(10, ValueAndUnit.UNITMODE_PERCENTAGE);

// Listen for value changes
pixelValue.onChangedObservable.add(() => {
    console.log("Value changed to:", pixelValue.value);
});

Styling System

Style objects for consistent font and appearance management across controls.

class Style implements IDisposable {
  constructor(host: AdvancedDynamicTexture);
  
  fontSize: string | number;
  fontFamily: string;
  fontStyle: string;
  fontWeight: string;

  onChangedObservable: Observable<Style>;
  
  dispose(): void;
}

Usage Examples:

import { Style, AdvancedDynamicTexture, TextBlock } from "@babylonjs/gui";

// Create GUI and style
const advancedTexture = AdvancedDynamicTexture.CreateFullscreenUI("UI");
const titleStyle = new Style(advancedTexture);

// Configure style
titleStyle.fontSize = 24;
titleStyle.fontFamily = "Arial";
titleStyle.fontWeight = "bold";
titleStyle.fontStyle = "italic";

// Apply to controls
const title = new TextBlock();
title.text = "Welcome";
title.style = titleStyle;

const subtitle = new TextBlock();
subtitle.text = "Please login";
subtitle.style = titleStyle;

// Listen for style changes
titleStyle.onChangedObservable.add((style) => {
    console.log("Style updated:", style.fontFamily, style.fontSize);
});

// Clean up
titleStyle.dispose();

Gradient System

Gradient classes for visual effects on 2D controls.

interface GradientColorStop {
  offset: number;
  color: string;
}

abstract class BaseGradient {
  abstract getCanvasGradient(context: CanvasRenderingContext2D): CanvasGradient;
  
  addColorStop(offset: number, color: string): BaseGradient;
}

class LinearGradient extends BaseGradient {
  constructor(x0: number, y0: number, x1: number, y1: number);
  
  rotation: number;
  
  getCanvasGradient(context: CanvasRenderingContext2D): CanvasGradient;
}

class RadialGradient extends BaseGradient {
  constructor(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number);
  
  centerX: number;
  centerY: number;
  radius: number;
  
  getCanvasGradient(context: CanvasRenderingContext2D): CanvasGradient;
}

Usage Examples:

import { LinearGradient, RadialGradient, Rectangle } from "@babylonjs/gui";

// Create linear gradient
const linearGrad = new LinearGradient(0, 0, 1, 1);
linearGrad.addColorStop(0, "red");
linearGrad.addColorStop(0.5, "yellow");
linearGrad.addColorStop(1, "blue");

// Apply to rectangle
const rect = new Rectangle();
rect.width = "200px";
rect.height = "100px";
rect.background = linearGrad;

// Create radial gradient
const radialGrad = new RadialGradient(0.5, 0.5, 0, 0.5, 0.5, 0.5);
radialGrad.addColorStop(0, "white");
radialGrad.addColorStop(1, "black");

// Apply to another control
const circle = new Ellipse();
circle.width = "100px";
circle.height = "100px";
circle.background = radialGrad;

Multi-line Text Utilities

Utilities for handling multi-line text positioning and word wrapping.

class MultiLinePoint {
  constructor(line: number, offset: number);
  
  line: number;
  offset: number;
  x: number;
  y: number;
}

Usage Examples:

import { MultiLinePoint, TextBlock } from "@babylonjs/gui";

// Create multi-line text
const textBlock = new TextBlock();
textBlock.text = "This is a long text that will wrap to multiple lines";
textBlock.textWrapping = true;
textBlock.width = "200px";

// Work with line positions
const point = new MultiLinePoint(0, 5);
point.x = 10;
point.y = 20;

// Use for cursor positioning in complex text scenarios
console.log(`Cursor at line ${point.line}, offset ${point.offset}`);

XML Loading

Utilities for loading GUI layouts from XML definitions.

namespace XMLLoader {
  function parseFromSnippetAsync(snippetId: string, guiTexture: AdvancedDynamicTexture): Promise<void>;
  function parseFromFileAsync(file: File, guiTexture: AdvancedDynamicTexture): Promise<void>;
}

Usage Examples:

import { XMLLoader, AdvancedDynamicTexture } from "@babylonjs/gui";

// Create GUI texture
const advancedTexture = AdvancedDynamicTexture.CreateFullscreenUI("UI");

// Load from snippet
XMLLoader.parseFromSnippetAsync("SNIPPET_ID", advancedTexture)
  .then(() => {
    console.log("GUI loaded from snippet");
  })
  .catch((error) => {
    console.error("Failed to load GUI:", error);
  });

// Load from file
const fileInput = document.getElementById("fileInput") as HTMLInputElement;
fileInput.addEventListener("change", (event) => {
  const file = (event.target as HTMLInputElement).files?.[0];
  if (file) {
    XMLLoader.parseFromFileAsync(file, advancedTexture)
      .then(() => {
        console.log("GUI loaded from file");
      });
  }
});

Constants

Common constants used throughout the GUI system for alignment, states, and unit modes.

// Alignment constants
const HORIZONTAL_ALIGNMENT_LEFT: number;
const HORIZONTAL_ALIGNMENT_RIGHT: number;
const HORIZONTAL_ALIGNMENT_CENTER: number;
const VERTICAL_ALIGNMENT_TOP: number;
const VERTICAL_ALIGNMENT_BOTTOM: number;
const VERTICAL_ALIGNMENT_CENTER: number;

// Input state constants
const TEXTINPUT_STATE_IDLE: number;
const TEXTINPUT_STATE_FOCUSED: number;
const TEXTINPUT_STATE_DISABLED: number;

These utilities provide the foundational support for flexible, CSS-like sizing, comprehensive styling systems, and advanced layout capabilities that power both 2D and 3D GUI elements in Babylon.js applications.