class

Tryst::UI::TextContent

Inherits Reference < Object

The rich text API for one ui.text_area widget's content - reached via Handle#text_content, the same shape Handle#tagged/#line use to hand back a CanvasItem: a small, focused companion object rather than a pile of widget-specific methods on Handle itself.

Indices (every index/from/to/at parameter below) are Tk's own text index syntax, passed through verbatim: "1.0", "end", "sel.first", "insert +1 line", a mark name, "@12,34" - see the Tk text manual page for the full grammar. Deliberately NOT wrapped in an index type of its own: sugar, not a wall. Two Symbol shortcuts cover the common cases - :end, and :cursor for the insert mark (renamed so it doesn't collide with #insert the method).

Naming: a Tk text "tag" is not an HTML tag - it's a named, reusable set of display properties applied to ranges, like a CSS class. The primary vocabulary here calls that a "format" (avoiding "style", already taken by ttk's own style: widget option); the Tk-named methods (#tag_configure, #tag_add, ...) are plain delegations to it, so reading Tk's own documentation and Tk-fluent muscle memory both keep working.

Every content-mutating method (#insert/#delete/#replace/#value=/ #clear/#insert_image) lifts a read-only (-state disabled) widget to normal for the duration of the call and puts it back afterwards. Tk itself silently no-ops a mutation against a disabled text widget, which is exactly the kind of wonk this DSL exists to hide: an app author building a read-only log pane never has to know about it.

Constructors

new(app : AppContract, path : String)

@api private - reached through Handle#text_content.

Instance methods

add_marker(name : Name, at : Index) : Nil

A marker is a named position that floats with edits around it - a bookmark, not a range.

apply_format(name : Name, from : Index, to : Index) : Nil

Applies an already-#format'ed name to [from, to).

clear

Empties the whole buffer.

clear_format(name : Name, from : Index, to : Index) : Nil

Removes name from [from, to). The definition itself is untouched and still applyable elsewhere - see #delete_format to remove that too.

cursor

Where the text cursor is (Tk's insert mark), as "line.char".

cursor=(spec : Index) : Nil

Moves the text cursor.

delete(from : Index, to : Index | Nil = nil) : Nil

Deletes [from, to), or the single character at from when to is left out.

delete_format(name : Name) : Nil

Deletes a format's definition entirely, and with it every range it was applied to.

format(name : Name, **opts) : Nil

Defines (or redefines) a named format - a reusable set of display properties, e.g. format(:error, foreground: "red", underline: true), applied to ranges with #apply_format.

format_ranges(name : Name) : Array(String)

A flat list of index pairs - [start1, end1, start2, end2, ...], one pair per contiguous range name is currently applied to.

get(from : Index = "1.0", to : Index = "end") : String

The text in [from, to). Defaults to the whole buffer, including the synthetic trailing newline Tk keeps at "end" - see #value for the buffer without it.

image_create(index : Index, image : Image | Tryst::Photo | String) : Nil

index(spec : Index) : String

Resolves any index expression to its canonical "line.char" form.

insert(index : Index, text : String) : Nil

ditto, with no formats to apply. Its own overload because a splat carrying a type restriction has to receive at least one argument, and dropping the restriction would let any TclArgValue member through as a format name.

insert(index : Index, text : String, *tags : Name) : Nil

Inserts text at index, optionally applying one or more formats to it - the same trailing tagList Tk's own insert takes.

insert_image(index : Index, image : Image | Tryst::Photo | String) : Nil

Embeds an image inline in the text flow at index. A DSL Image or a raw Tryst::Photo both work - what Tk needs is the Tcl image name either one is named by.

mark_gravity(name : Name, direction : Name | Nil = nil) : String

Which way name drifts when text is inserted exactly at it. Reads the current gravity ("left" or "right") when direction is left out. Advanced and rarely needed, so this keeps its Tk name only - there's no friendlier spelling to offer.

mark_names

mark_set(name : Name, at : Index) : Nil

mark_unset(name : Name) : Nil

markers

Every marker currently defined, including Tk's own built-in insert/current.

on_format(name : Name, event : String, &block : Array(String), CallbackSignal -> Nil) : Nil

#on_format_click for an arbitrary Tk event pattern instead of the common left-click case. The angle brackets are optional - "Double-Button-1" and "<Double-Button-1>" both work.

on_format_click(name : Name, &block : Array(String), CallbackSignal -> Nil) : Nil

Fires on a left click anywhere text carrying name is displayed. Wired through tag bind rather than a raw tcl_eval, so tryst's own leak-safe reconcile (TagBindInterceptor, registered for the text widget) releases the callback once name stops being bound - the same leak safety every other binding in this DSL gets.

on_tag(name : Name, event : String, &block : Array(String), CallbackSignal -> Nil) : Nil

on_tag_click(name : Name, &block : Array(String), CallbackSignal -> Nil) : Nil

read_only

Whether the widget currently refuses direct typing (its Tk -state is disabled). The mutating methods here work either way, lifting this for their own duration - see this class's own doc comment.

read_only=(value : Bool) : Nil

remove_marker(name : Name) : Nil

replace(from : Index, to : Index, text : String) : Nil

Atomic delete-then-insert over [from, to).

scroll_to(index : Index) : Nil

Scrolls the view until index is visible.

search(pattern : String, from : Index = "insert", to : Index = "end", backwards : Bool = false, regexp : Bool = false, nocase : Bool = false) : String | Nil

The index of the first match, or nil if there isn't one. to is the boundary the search may reach, which with backwards: true is the EARLIEST index rather than the latest - same as plain Tk search.

see(index : Index) : Nil

tag_add(name : Name, from : Index, to : Index) : Nil

tag_configure(name : Name, **opts) : Nil

tag_delete(name : Name) : Nil

tag_ranges(name : Name) : Array(String)

tag_remove(name : Name, from : Index, to : Index) : Nil

value

The whole buffer, without the synthetic trailing newline Tk always keeps at "end".

value=(text : String) : Nil

Replaces the whole buffer's content outright.

Nested types