Text#

Text is tkinter’s multi-line text widget (tk.Text), themed by ttkbootstrap. This page is the complete reference for its own options and methods — the shared capabilities every widget has (configuration, lifecycle, focus, introspection) are listed at the bottom.

For a task-oriented walkthrough — indices, tags, marks, search, undo — see the Text widget guide.

Options#

Set at construction or with configure(...); read with cget("name").

Option

Type

Description

autostyle

bool

Constructor only. True (the default) paints the widget with the active theme and repaints it on a theme switch; False opts out, leaving tkinter’s default appearance for you to style yourself. This is ttkbootstrap’s one addition to the widget — everything below is native tk.

font

str | Font

The default font for the text.

wrap

str

How lines that exceed the width wrap: "char", "word", or "none" (no wrap — scroll horizontally instead).

tabs

str

Tab stops, as a list of distances (optionally each followed by "left"/"right"/"center"/"numeric").

tabstyle

str

How tabs interact with the tabs list: "tabular" or "wordprocessor".

spacing1

int

Extra vertical space above the first display line of each text line.

spacing2

int

Extra vertical space between the display lines of a single wrapped line.

spacing3

int

Extra vertical space below the last display line of each text line.

foreground (fg)

str

The text color.

background (bg)

str

The page (background) color.

selectforeground

str

The text color within the selection.

selectbackground

str

The background color of the selection.

inactiveselectbackground

str

The selection background when the widget doesn’t have focus (an empty string hides the selection when unfocused).

insertbackground

str

The color of the blinking insert cursor.

insertwidth

int

The width of the insert cursor, in pixels.

insertborderwidth

int

The 3-D border width drawn around the insert cursor.

insertontime

int

Milliseconds the cursor is shown per blink.

insertofftime

int

Milliseconds the cursor is hidden per blink (0 disables blinking).

insertunfocussed

str

How the cursor is drawn when the widget lacks focus: "none", "hollow", or "solid".

blockcursor

bool

True draws the insert cursor as a block over the next character rather than a thin bar.

width

int

The requested width in characters (not pixels).

height

int

The requested height in lines (not pixels).

padx

int

Internal horizontal padding between the text and the border, in pixels.

pady

int

Internal vertical padding between the text and the border, in pixels.

relief

str

The border style: "flat", "raised", "sunken", "groove", "ridge", or "solid".

borderwidth (bd)

int

The width of the 3-D border, in pixels.

selectborderwidth

int

The border width drawn around selected text.

highlightthickness

int

The width of the focus highlight drawn around the widget.

highlightcolor

str

The focus-highlight color when the widget has focus.

highlightbackground

str

The focus-highlight color when the widget does not have focus.

undo

bool

True enables the built-in undo/redo stack.

autoseparators

bool

True auto-inserts undo boundaries as the user types.

maxundo

int

The maximum number of undo steps to keep (-1 for unlimited).

state

str

"normal" (editable) or "disabled" (read-only; the widget also ignores insert/delete while disabled).

cursor

str

The mouse cursor shown over the widget (see Cursors).

takefocus

bool

Whether the widget accepts focus during keyboard traversal.

exportselection

bool

Whether a selection is exported to the X selection / clipboard.

setgrid

bool

True makes the containing window resize in whole character cells.

startline

int

Restrict the widget to start at this line of the underlying store (used by peer widgets; None for the full range).

endline

int

Restrict the widget to end at this line of the underlying store (used by peer widgets; None for the full range).

xscrollcommand

callable

A callback connecting the widget to a horizontal scrollbar.

yscrollcommand

callable

A callback connecting the widget to a vertical scrollbar.

Methods#

Content and editing#

insert(index, chars, *args)

Insert text at a position. Any trailing args alternate a tag (or tuple of tags) with more text, so text can be tagged as it is inserted.

Parameters:

  • index – where to insert — any index expression (e.g. "insert", "end", "1.0").

  • chars (str) – the text to insert.

  • args – optional alternating tag / text values applied to the inserted runs.

Returns:

None.

delete(index1, index2=None)

Delete a character or a range of text.

Parameters:

  • index1 – start of the range.

  • index2 – end of the range, exclusive. If omitted, only the single character at index1 is deleted.

Returns:

None.

replace(index1, index2, chars, *args)

Delete the text between two indices and insert chars in its place — a delete followed by an insert at index1.

Parameters:

  • index1 – start of the range to replace.

  • index2 – end of the range, exclusive.

  • chars (str) – the replacement text.

  • args – optional alternating tag / text values, as for insert.

Returns:

None.

get(index1, index2=None)

Return text from the widget.

Parameters:

  • index1 – start of the range.

  • index2 – end of the range, exclusive. If omitted, returns the single character at index1.

Returns:

the text in the range.

Return type:

str

count(index1, index2, *options, return_ints=False)

Count text units between two indices.

Parameters:

  • index1 – start of the range.

  • index2 – end of the range.

  • options – one or more units to count, each a string — "chars", "indices", "lines", "displaylines", "xpixels", "ypixels", and so on.

  • return_ints (bool) – return a bare int when a single unit is requested, instead of a one-tuple.

Returns:

the counts, in the order the options were given.

Return type:

tuple[int, …] | int

dump(index1, index2=None, command=None, **kinds)

Return the contents of a range broken into its pieces — text, tags, marks, and embedded images/windows — as (key, value, index) triples.

Parameters:

  • index1 – start of the range.

  • index2 – end of the range; if omitted, dumps at index1.

  • command – a callback invoked once per piece instead of returning them.

  • kinds – booleans selecting which piece types to include — text, tag, mark, image, window, or all.

Returns:

a list of (key, value, index) triples (None if command is given).

Return type:

list[tuple[str, str, str]]

Positions and display#

index(index)

Resolve any index expression to a concrete position.

Parameters:

index – an index expression ("insert", "end-1c", "1.0", …).

Returns:

the position as "line.column".

Return type:

str

compare(index1, op, index2)

Compare two positions.

Parameters:

  • index1 – the first index.

  • op (str) – a comparison operator — "<", "<=", "==", "!=", ">=", ">".

  • index2 – the second index.

Returns:

the result of the comparison.

Return type:

bool

see(index)

Scroll the view so that index is visible.

Parameters:

index – the position to reveal.

Returns:

None.

dlineinfo(index)

Return the bounding box of the display line containing index.

Parameters:

index – a position on the line.

Returns:

(x, y, width, height, baseline) in pixels, or None if the line is not visible.

Return type:

tuple | None

bbox(index)

Return the bounding box of the character at index.

Parameters:

index – the character’s position.

Returns:

(x, y, width, height) in pixels, or None if not visible.

Return type:

tuple | None

scan_mark(x, y)

Record a starting point for a fast drag-scroll (paired with scan_dragto).

Parameters:

  • x (int) – pointer x, in pixels.

  • y (int) – pointer y, in pixels.

Returns:

None.

scan_dragto(x, y)

Scroll the view relative to the scan_mark point, accelerated for click-drag panning.

Parameters:

  • x (int) – current pointer x, in pixels.

  • y (int) – current pointer y, in pixels.

Returns:

None.

Tags#

tag_add(tagName, index1, *args)

Apply a tag to one or more ranges.

Parameters:

  • tagName (str) – the tag to apply.

  • index1 – start of the first range.

  • args – an end index, then optional further start/end index pairs.

Returns:

None.

tag_remove(tagName, index1, index2=None)

Remove a tag from a range. The tag itself still exists and keeps its config.

Parameters:

  • tagName (str) – the tag to remove.

  • index1 – start of the range.

  • index2 – end of the range, exclusive; one character if omitted.

Returns:

None.

tag_delete(*tagNames)

Delete tags entirely, removing them from all text and discarding their config.

Parameters:

tagNames – the tag names to delete.

Returns:

None.

tag_configure(tagName, **options)

Set (or query) a tag’s appearance. Alias: tag_config.

Parameters:

  • tagName (str) – the tag to configure.

  • options – appearance options — foreground, background, font, underline, overstrike, justify, lmargin1/lmargin2, rmargin, spacing1/2/3, tabs, elide.

Returns:

the option spec when queried with a single option name, else None.

tag_cget(tagName, option)

Return one option of a tag.

Parameters:

  • tagName (str) – the tag.

  • option (str) – the option name.

Returns:

the option’s value.

tag_bind(tagName, sequence, func, add=None)

Bind an event to every range wearing a tag — the way to make text clickable.

Parameters:

  • tagName (str) – the tag.

  • sequence (str) – an event sequence, e.g. "<Button-1>".

  • func – the callback, receiving the event object.

  • add – "+" to add a handler rather than replace.

Returns:

a binding id (for tag_unbind).

Return type:

str

tag_unbind(tagName, sequence, funcid=None)

Remove a tag binding.

Parameters:

  • tagName (str) – the tag.

  • sequence (str) – the bound sequence.

  • funcid – the id returned by tag_bind, to remove one handler.

Returns:

None.

tag_names(index=None)

Return tag names.

Parameters:

index – if given, only the tags covering that position.

Returns:

the tag names, in priority order (lowest first).

Return type:

tuple[str, …]

tag_ranges(tagName)

Return the ranges a tag covers.

Parameters:

tagName (str) – the tag.

Returns:

a flat sequence of alternating start/end indices.

Return type:

tuple

tag_nextrange(tagName, index1, index2=None)

Find the next range of a tag at or after a position.

Parameters:

  • tagName (str) – the tag.

  • index1 – where to start searching.

  • index2 – where to stop; optional.

Returns:

(start, end) of the next range, or an empty tuple if none.

Return type:

tuple

tag_prevrange(tagName, index1, index2=None)

Find the previous range of a tag before a position (counterpart of tag_nextrange()).

Returns:

(start, end) of the previous range, or an empty tuple.

Return type:

tuple

tag_raise(tagName, aboveThis=None)

Raise a tag’s priority. When tags overlap, the higher-priority tag wins on any conflicting option.

Parameters:

  • tagName (str) – the tag to raise.

  • aboveThis – raise just above this tag; if omitted, raise to the top.

Returns:

None.

tag_lower(tagName, belowThis=None)

Lower a tag’s priority (counterpart of tag_raise()).

Parameters:

  • tagName (str) – the tag to lower.

  • belowThis – lower just below this tag; if omitted, lower to the bottom.

Returns:

None.

Marks#

mark_set(markName, index)

Create a mark, or move an existing one, to a position. A mark is a named position that floats with the text as it changes.

Parameters:

  • markName (str) – the mark name ("insert" is the cursor).

  • index – where to place the mark.

Returns:

None.

mark_unset(*markNames)

Delete marks.

Parameters:

markNames – the marks to remove.

Returns:

None.

mark_gravity(markName, direction=None)

Get or set a mark’s gravity — which side it sticks to when text is inserted exactly at it.

Parameters:

  • markName (str) – the mark.

  • direction – "left" or "right"; omit to query.

Returns:

the current gravity when queried, else None.

Return type:

str | None

mark_names()

Return all mark names, including the built-in "insert" and "current".

Return type:

tuple[str, …]

mark_next(index)

Return the name of the next mark at or after a position.

Parameters:

index – where to start.

Returns:

the mark name, or "" if none.

Return type:

str

mark_previous(index)

Return the name of the previous mark before a position (counterpart of mark_next()).

Return type:

str

Undo stack#

Each edit_* method wraps the generic edit(*args) dispatcher.

edit_undo()

Undo the changes back to the last separator. Requires undo=True.

Returns:

None.

Raises:

TclError – if there is nothing to undo.

edit_redo()

Redo the changes undone by the last edit_undo().

Returns:

None.

Raises:

TclError – if there is nothing to redo.

edit_separator()

Insert a separator (an undo boundary) onto the undo stack.

Returns:

None.

edit_reset()

Clear the undo and redo stacks.

Returns:

None.

edit_modified(arg=None)

Get or set the widget’s “modified” flag.

Parameters:

arg (bool) – the new flag value; omit to query.

Returns:

the current flag when queried, else None.

Return type:

bool | None

Embedded images#

image_create(index, **options)

Embed an image in the text at a position.

Parameters:

  • index – where to insert the image.

  • options – image= a PhotoImage, align= ("baseline"/"top"/"center"/"bottom"), padx=, pady=, name=.

Returns:

the name of the embedded image.

Return type:

str

image_cget(index, option)

Return one option of the embedded image at index.

Return type:

str

image_configure(index, **options)

Set (or query) the options of the embedded image at index.

image_names()

Return the names of all embedded images.

Return type:

tuple[str, …]

Embedded windows#

window_create(index, **options)

Embed a child widget in the text at a position.

Parameters:

  • index – where to insert the widget.

  • options – window= an existing widget, or create= a factory called to build it lazily; plus align=, padx=, pady=, stretch=.

Returns:

None.

window_cget(index, option)

Return one option of the embedded window at index.

window_configure(index, **options)

Set (or query) the options of the embedded window at index.

window_names()

Return the embedded child widgets.

Return type:

tuple

Scrolling (view)#

yview(*args)

Query or set the vertical view. Usually connected to a scrollbar via the yscrollcommand option rather than called directly.

Returns:

with no args, the visible fraction (first, last); otherwise None.

Return type:

tuple | None

yview_moveto(fraction)

Scroll vertically so that fraction of the content is above the top edge.

Parameters:

fraction (float) – a value from 0.0 to 1.0.

Returns:

None.

yview_scroll(number, what)

Scroll vertically by a number of units or pages.

Parameters:

  • number (int) – how far, positive or negative.

  • what (str) – "units" (lines) or "pages".

Returns:

None.

xview(*args)

Horizontal counterpart of yview(); xview_moveto and xview_scroll mirror the vertical versions.

Peer widgets#

peer_create(newPathName, **options)

Create a second text widget that shares this one’s underlying content — edits to either show in both.

Parameters:

  • newPathName (str) – the Tk path name for the new peer.

  • options – any Text options for the peer.

Returns:

None.

peer_names()

Return the peers sharing this widget’s content store.

Return type:

tuple

Shared capabilities#

Text also has the methods every widget inherits — configuration, placement, event binding, lifecycle, focus, and introspection. These are documented under Capabilities.

See also#