Struct TerminalBuilder 

pub struct TerminalBuilder { /* private fields */ }

Builder for configuring and creating a Terminal.

Provides a fluent API for terminal configuration with sensible defaults. The terminal will use the default embedded font atlas unless explicitly configured.

Examples

// Simple terminal with default configuration
use beamterm_renderer::{FontAtlasData, Terminal};

let terminal = Terminal::builder("#canvas").build().unwrap();

// Terminal with custom font atlas
let atlas = FontAtlasData::from_binary(unimplemented!(".atlas data")).unwrap();
let terminal = Terminal::builder("#canvas")
    .font_atlas(atlas)
    .fallback_glyph("X".into())
    .build().unwrap();

Implementations

impl TerminalBuilder

pub fn font_atlas(self, atlas: FontAtlasData) -> Self

Sets a custom static font atlas for the terminal.

By default, the terminal uses an embedded font atlas. Use this method to provide a custom atlas with different fonts, sizes, or character sets.

Static atlases are pre-generated using the beamterm-atlas CLI tool and loaded from binary .atlas files. They provide consistent rendering but require the character set to be known at build time.

For dynamic glyph rasterization at runtime, see dynamic_font_atlas.

pub fn dynamic_font_atlas(self, font_family: &[&str], font_size: f32) -> Self

Configures the terminal to use a dynamic font atlas.

Unlike static atlases, the dynamic atlas rasterizes glyphs on-demand using the browser’s Canvas API. This enables:

• Runtime font selection without pre-generation
• Support for any system font available in the browser
• Automatic handling of unpredictable Unicode content

Parameters

• font_family - Font family names in priority order (e.g., &["JetBrains Mono", "Fira Code"])
• font_size - Font size in pixels

For pre-generated atlases with fixed character sets, see font_atlas.

pub fn debug_dynamic_font_atlas( self, font_family: &[&str], font_size: f32, pattern: DebugSpacePattern, ) -> Self

Configures the terminal to use a dynamic font atlas with debug space pattern.

This is the same as dynamic_font_atlas, but replaces the space glyph with a checkered pattern for validating pixel-perfect rendering.

Parameters

• font_family - Font family names in priority order
• font_size - Font size in pixels
• pattern - The checkered pattern to use (1px or 2x2 pixels)

pub fn fallback_glyph(self, glyph: &str) -> Self

Sets the fallback glyph for missing characters.

When a character is not found in the font atlas, this glyph will be displayed instead. Defaults to a space character if not specified.

pub fn canvas_padding_color(self, color: u32) -> Self

Sets the background color for the canvas area outside the terminal grid.

When the canvas dimensions don’t align perfectly with the terminal cell grid, there may be unused pixels around the edges. This color fills those padding areas to maintain a consistent appearance.

pub fn enable_debug_api(self) -> Self

Enables the debug API that will be exposed to the browser console.

When enabled, a debug API will be available at window.__beamterm_debug with methods like getMissingGlyphs() for inspecting the terminal state.

pub fn mouse_input_handler<F>(self, callback: F) -> Self

where F: FnMut(TerminalMouseEvent, &TerminalGrid) + 'static,

Sets a callback for handling terminal mouse input events.

pub fn mouse_selection_handler(self, configuration: MouseSelectOptions) -> Self

Enables mouse-based text selection with automatic clipboard copying.

When enabled, users can click and drag to select text in the terminal. Selected text is automatically copied to the clipboard on mouse release.

Example

use beamterm_renderer::{Terminal, SelectionMode};
use beamterm_renderer::mouse::{MouseSelectOptions, ModifierKeys};

let terminal = Terminal::builder("#canvas")
    .mouse_selection_handler(
        MouseSelectOptions::new()
            .selection_mode(SelectionMode::Linear)
            .require_modifier_keys(ModifierKeys::SHIFT)
            .trim_trailing_whitespace(true)
    )
    .build()
    .unwrap();

pub fn default_mouse_input_handler( self, selection_mode: SelectionMode, trim_trailing_whitespace: bool, ) -> Self

👎Deprecated since 0.13.0: Use mouse_selection_handler with MouseSelectOptions instead

Sets a default selection handler for mouse input events. Left button selects text, it copies the selected text to the clipboard on mouse release.

pub fn build(self) -> Result<Terminal, Error>

Builds the terminal with the configured options.