TTkTextWrap

class TTkTextWrap(document: TTkTextDocument)

Bases: object

TTkTextWrap:

Incremental text wrapping helper for TTkTextDocument. It maps document positions to wrapped screen rows and vice versa.

Create a wrap manager bound to a text document.

param document:

the source text document to wrap.

type document:

TTkTextDocument

Signals

wrapChanged

This signal is emitted whenever wrapped line mapping changes.

Slots

ensureScreenRows(y, h)

Force materialization of wrapped rows in a viewport range.

Members

wrapChanged: pyTTkSignal

This signal is emitted whenever wrapped line mapping changes.

It is triggered after incremental updates from document edits and after explicit full rewrap requests.

Methods

dataToScreenPosition(line: int, pos: int) → _RetScreenPositions

Map a document position to wrapped screen coordinates.

Parameters:

• line (int) – logical line index.

• pos (int) – character position in the logical line.

Returns:

wrapped screen coordinates.

Return type:

_RetScreenPositions

documentLineCount() → int

Return the number of logical data lines in the document.

Returns:

document line count.

Return type:

int

engine() → WrapEngine

ensureScreenRows(y: int, h: int) → None

Force materialization of wrapped rows in a viewport range.

For lazy-loading engines (FastWrap, VimWrap, HybridVimWrap), this materializes the rows that would be returned by screenRows(). For eager engines (FullWrap, NoWrap), this is typically a no-op.

This is useful when you need size() to return an accurate estimate instead of a prediction, as lazy engines improve their estimates as more chunks are materialized.

Parameters:

• y (int) – first screen row to materialize.

• h (int) – number of rows to materialize.

normalizeScreenPosition(x: int, y: int) → Tuple[int, int]

Snap a screen position to the nearest editable character cell.

Parameters:

• x (int) – horizontal widget-relative coordinate.

• y (int) – vertical widget-relative coordinate.

Returns:

normalized (x, y) screen position.

Return type:

Tuple[int, int]

rewrap() → None

Force a complete wrap refresh and emit wrapChanged.

This invalidates any incremental wrapping cache maintained by the active engine.

screenRows(y: int, h: int) → _RetScreenRows

Return wrapped slices visible in the requested viewport.

Parameters:

• y (int) – first screen row.

• h (int) – number of rows to extract.

Returns:

wrapped row slices.

Return type:

_RetScreenRows

screenToDataPosition(x: int, y: int) → Tuple[int, int]

Map wrapped screen coordinates to a document position.

Parameters:

• x (int) – horizontal screen coordinate.

• y (int) – vertical screen coordinate.

Returns:

(line, pos) document position.

Return type:

Tuple[int, int]

setEngine(engine: WrapEngine, width: int | None = None) → None

Switch the wrapping backend implementation.

Parameters:

• engine (TTkK.WrapEngine) – engine selector from TTkK.WrapEngine.

• width (Optional[int]) – optional wrap width applied before switching engines when the engine type actually changes.

setWordWrapMode(mode: WrapMode) → None

Set the word-wrap mode and invalidate cached wrapping.

Parameters:

mode (TTkK.WrapMode) – new wrap mode.

setWrapWidth(width: int) → None

Set wrap width and trigger a full rewrap.

Parameters:

width (int) – target width in terminal cells.

size() → int

Return the estimated wrapped row count.

Returns:

wrapped size in screen rows.

Return type:

int

wordWrapMode() → WrapMode

Return the active word-wrap mode.

Returns:

current wrap mode.

Return type:

TTkK.WrapMode

wrapWidth() → int

Return the current wrap width in terminal cells.

Returns:

wrap width.

Return type:

int