EditBuffer

An editable text buffer with cursor management, undo/redo, and incremental editing capabilities.

Overview

The EditBuffer class extends EventEmitter and provides a complete text editing solution with cursor management, undo/redo history, and grapheme-aware text operations. It’s designed for building text editors and interactive text input components.

Constructor

lib · RenderLib · required

The render library instance.

ptr · Pointer · required

Pointer to the native buffer.

Static Methods

create

Creates a new EditBuffer instance.

static create(widthMethod: WidthMethod): EditBuffer

widthMethod · WidthMethod · required

The width calculation method for character rendering.

return · EditBuffer

A new EditBuffer instance.

Properties

id

readonly id: number

id · number

Unique identifier for this buffer instance.

ptr

get ptr(): Pointer

ptr · Pointer

The native pointer to the buffer.

Text Operations

setText

Sets text and completely resets the buffer state (clears history).

setText(text: string): void

text · string · required

The text content to set.

setTextOwned

Sets text using owned memory and resets buffer state. Native code takes ownership.

setTextOwned(text: string): void

text · string · required

The text content to set.

replaceText

Replaces text while preserving undo history (creates an undo point).

replaceText(text: string): void

text · string · required

The replacement text content.

replaceTextOwned

Replaces text using owned memory while preserving undo history.

replaceTextOwned(text: string): void

text · string · required

The replacement text content.

getText

Retrieves the current text content.

getText(): string

return · string

The current 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.

getTextRangeByCoords

Retrieves a range of text by line/column coordinates.

getTextRangeByCoords(
  startRow: number,
  startCol: number,
  endRow: number,
  endCol: number
): string

startRow · number · required

The starting row (0-based).

startCol · number · required

The starting column (0-based).

endRow · number · required

The ending row (0-based).

endCol · number · required

The ending column (0-based).

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.

Editing Operations

insertChar

Inserts a character at the current cursor position.

insertChar(char: string): void

char · string · required

The character to insert.

insertText

Inserts text at the current cursor position.

insertText(text: string): void

text · string · required

The text to insert.

deleteChar

Deletes the character at the cursor position (forward delete).

deleteChar(): void

deleteCharBackward

Deletes the character before the cursor position (backspace).

deleteCharBackward(): void

deleteRange

Deletes a range of text by coordinates.

deleteRange(
  startLine: number,
  startCol: number,
  endLine: number,
  endCol: number
): void

startLine · number · required

The starting line (0-based).

startCol · number · required

The starting column (0-based).

endLine · number · required

The ending line (0-based).

endCol · number · required

The ending column (0-based).

newLine

Inserts a new line at the cursor position.

newLine(): void

deleteLine

Deletes the current line.

deleteLine(): void

Cursor Operations

getCursorPosition

Gets the current cursor position.

getCursorPosition(): LogicalCursor

return · LogicalCursor

Object containing row, col, and offset properties.

setCursor

Sets the cursor to a specific line and column.

setCursor(line: number, col: number): void

line · number · required

The line number (0-based).

col · number · required

The column number (0-based).

setCursorToLineCol

Sets the cursor to a specific line and column.

setCursorToLineCol(line: number, col: number): void

line · number · required

The line number (0-based).

col · number · required

The column number (0-based).

setCursorByOffset

Sets the cursor by character offset.

setCursorByOffset(offset: number): void

offset · number · required

The character offset (0-based).

moveCursorLeft

Moves the cursor one grapheme left.

moveCursorLeft(): void

moveCursorRight

Moves the cursor one grapheme right.

moveCursorRight(): void

moveCursorUp

Moves the cursor one line up.

moveCursorUp(): void

moveCursorDown

Moves the cursor one line down.

moveCursorDown(): void

gotoLine

Moves the cursor to the start of a specific line.

gotoLine(line: number): void

line · number · required

The line number (0-based).

getNextWordBoundary

Finds the next word boundary from the cursor.

getNextWordBoundary(): LogicalCursor

return · LogicalCursor

The position of the next word boundary.

getPrevWordBoundary

Finds the previous word boundary from the cursor.

getPrevWordBoundary(): LogicalCursor

return · LogicalCursor

The position of the previous word boundary.

getEOL

Gets the end-of-line position for the current line.

getEOL(): LogicalCursor

return · LogicalCursor

The end-of-line position.

Position Conversion

offsetToPosition

Converts a character offset to a line/column position.

offsetToPosition(offset: number): { row: number; col: number } | null

offset · number · required

The character offset.

return · { row: number; col: number } | null

The row/column position or null if invalid offset.

positionToOffset

Converts a line/column position to a character offset.

positionToOffset(row: number, col: number): number

row · number · required

The row number (0-based).

col · number · required

The column number (0-based).

return · number

The character offset.

getLineStartOffset

Gets the character offset of the start of a line.

getLineStartOffset(row: number): number

row · number · required

The row number (0-based).

return · number

The character offset of the line start.

Undo/Redo

undo

Undoes the last edit operation.

undo(): string | null

return · string | null

Metadata about the undo operation or null if nothing to undo.

redo

Redoes the last undone operation.

redo(): string | null

return · string | null

Metadata about the redo operation or null if nothing to redo.

canUndo

Checks if there are operations available to undo.

canUndo(): boolean

return · boolean

True if undo is available.

canRedo

Checks if there are operations available to redo.

canRedo(): boolean

return · boolean

True if redo is available.

clearHistory

Clears the entire undo/redo history.

clearHistory(): void

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

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.

Memory Management

clear

Clears the buffer content.

clear(): void

destroy

Destroys the buffer and frees native resources.

destroy(): void

debugLogRope

Logs the internal rope data structure for debugging.

debugLogRope(): void

Types

LogicalCursor

interface LogicalCursor {
  row: number
  col: number
  offset: number
}

row · number · required

The row position (0-based).

col · number · required

The column position (0-based).

offset · number · required

The character offset from start of buffer.

Events

EditBuffer extends EventEmitter and emits native events. Events are prefixed with eb_ internally but exposed without the prefix.

Example

import { EditBuffer } from "@opentui/core"

// Create an edit buffer
const buffer = EditBuffer.create("wcwidth")

// Set initial text
buffer.setText("Hello, World!")

// Insert text at cursor
buffer.insertText(" Welcome to OpenTUI.")

// Move cursor
buffer.moveCursorLeft()
buffer.moveCursorUp()

// Get cursor position
const pos = buffer.getCursorPosition()
console.log(`Cursor at ${pos.row}:${pos.col}`)

// Undo and redo
buffer.undo()
if (buffer.canRedo()) {
  buffer.redo()
}

// Get text
const text = buffer.getText()
console.log(text)

// Clean up
buffer.destroy()