TextBuffer

A high-performance text storage and rendering buffer with support for styling, syntax highlighting, and Unicode.

Overview

The TextBuffer class provides efficient text storage with support for styled text, syntax highlighting, and grapheme-aware operations. It handles text rendering with Unicode support and manages highlights for code or text display.

Constructor

lib · RenderLib · required

The render library instance.

ptr · Pointer · required

Pointer to the native buffer.

Static Methods

create

Creates a new TextBuffer instance.

static create(widthMethod: WidthMethod): TextBuffer

widthMethod · WidthMethod · required

The width calculation method for character rendering.

return · TextBuffer

A new TextBuffer instance.

Properties

length

get length(): number

length · number

The character length of the text in the buffer.

byteSize

get byteSize(): number

byteSize · number

The byte size of the text in the buffer.

ptr

get ptr(): Pointer

ptr · Pointer

The native pointer to the buffer.

Text Operations

setText

Sets the entire text content of the buffer.

setText(text: string): void

text · string · required

The text content to set.

append

Appends text to the end of the buffer.

append(text: string): void

text · string · required

The text to append.

loadFile

Loads text content from a file.

loadFile(path: string): void

path · string · required

The file path to load.

setStyledText

Sets styled text with formatting.

setStyledText(text: StyledText): void

text · StyledText · required

Styled text with formatting chunks.

getPlainText

Retrieves the plain text content without styling.

getPlainText(): string

return · string

The plain text content.

getTextRange

Retrieves a range of text by character offsets.

getTextRange(startOffset: number, endOffset: number): string

startOffset · number · required

The starting character offset.

endOffset · number · required

The ending character offset.

return · string

The text in the specified range.

getLineCount

Gets the number of lines in the buffer.

getLineCount(): number

return · number

The number of lines.

Styling

setDefaultFg

Sets the default foreground color.

setDefaultFg(fg: RGBA | null): void

fg · RGBA | null · required

The foreground color or null to clear.

setDefaultBg

Sets the default background color.

setDefaultBg(bg: RGBA | null): void

bg · RGBA | null · required

The background color or null to clear.

setDefaultAttributes

Sets default text attributes (bold, italic, etc.).

setDefaultAttributes(attributes: number | null): void

attributes · number | null · required

Bitfield of text attributes or null to clear.

resetDefaults

Resets all default styling to original values.

resetDefaults(): void

Syntax Highlighting

setSyntaxStyle

Sets the syntax highlighting style.

setSyntaxStyle(style: SyntaxStyle | null): void

style · SyntaxStyle | null · required

The syntax style or null to disable.

getSyntaxStyle

Gets the current syntax highlighting style.

getSyntaxStyle(): SyntaxStyle | null

return · SyntaxStyle | null

The current syntax style or null if none is set.

Highlights

addHighlight

Adds a highlight to a specific line by column positions.

addHighlight(lineIdx: number, highlight: Highlight): void

lineIdx · number · required

The line index (0-based).

highlight · Highlight · required

The highlight definition with start/end columns.

addHighlightByCharRange

Adds a highlight using absolute character offsets.

addHighlightByCharRange(highlight: Highlight): void

highlight · Highlight · required

The highlight definition with start/end character offsets.

removeHighlightsByRef

Removes all highlights with a specific reference ID.

removeHighlightsByRef(hlRef: number): void

hlRef · number · required

The highlight reference ID.

clearLineHighlights

Clears all highlights on a specific line.

clearLineHighlights(lineIdx: number): void

lineIdx · number · required

The line index (0-based).

clearAllHighlights

Removes all highlights from the buffer.

clearAllHighlights(): void

getLineHighlights

Retrieves all highlights for a specific line.

getLineHighlights(lineIdx: number): Array<Highlight>

lineIdx · number · required

The line index (0-based).

return · Array<Highlight>

Array of highlights on the line.

getHighlightCount

Gets the total number of highlights in the buffer.

getHighlightCount(): number

return · number

The total highlight count.

Configuration

setTabWidth

Sets the display width of tab characters.

setTabWidth(width: number): void

width · number · required

The tab width in columns.

getTabWidth

Gets the current tab width setting.

getTabWidth(): number

return · number

The tab width in columns.

Memory Management

clear

Clears the buffer content but preserves internal state.

clear(): void

reset

Resets the buffer to initial state, clearing all content and state.

reset(): void

destroy

Destroys the buffer and frees native resources.

destroy(): void

Types

TextChunk

interface TextChunk {
  __isChunk: true
  text: string
  fg?: RGBA
  bg?: RGBA
  attributes?: number
  link?: { url: string }
}

text · string · required

The text content of the chunk.

fg · RGBA

Foreground color for the chunk.

bg · RGBA

Background color for the chunk.

attributes · number

Text attributes bitfield (bold, italic, etc.).

link · { url: string }

Optional hyperlink URL.

Example

import { TextBuffer } from "@opentui/core"

// Create a text buffer
const buffer = TextBuffer.create("wcwidth")

// Set text content
buffer.setText("Hello, World!\nWelcome to OpenTUI")

// Get line count
console.log(buffer.getLineCount()) // 2

// Add syntax highlighting
const style = SyntaxStyle.create("typescript")
buffer.setSyntaxStyle(style)

// Add a highlight
buffer.addHighlight(0, {
  start: 0,
  end: 5,
  fg: new RGBA(255, 0, 0, 255),
  ref: 1
})

// Get plain text
const text = buffer.getPlainText()

// Clean up
buffer.destroy()