Skip to content

gh-135658: Add documentation for tkinter.Text widget #146467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SHAHID-glitch wants to merge 1 commit into
base: main
Choose a base branch
from
Open

gh-135658: Add documentation for tkinter.Text widget #146467

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions Doc/library/tkinter.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -963,6 +963,101 @@
labelled ``last``, ``active``, or ``none`` may be interpreted as the above
literals, instead.

.. _tkinter-text-widget:

Text
^^^^

The :class:`tkinter.Text` widget provides a multi-line text editing area

Check warning on line 971 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:class reference target not found: tkinter.Text [ref.class]
with support for rich features such as text formatting, embedded widgets,
and undo/redo functionality. It is one of the most flexible and powerful
widgets available in Tkinter.

Unlike simpler widgets such as :class:`Entry`, the :class:`tkinter.Text` widget

Check warning on line 976 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:class reference target not found: tkinter.Text [ref.class]

Check warning on line 976 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:class reference target not found: Entry [ref.class]
supports multiple lines of text and allows fine-grained control over the
content using indexes, tags, and marks.

Basic usage::

import tkinter as tk

root = tk.Tk()
text = tk.Text(root)
text.pack()

text.insert("1.0", "Hello, world!")

root.mainloop()

Indexes
-------

Text positions are specified using *index* values. The most common format
is ``line.column``, where *line* and *column* are integers starting from
1 and 0 respectively.

Indexes can also include symbolic names.
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This new section adds a concrete description of Text indexes, but earlier in the same “The index Parameter” section there is still a paragraph saying Text widget index notation is “best described in the Tk man pages.” Consider updating that earlier paragraph to link to this new “Text” section (or trimming it) to avoid contradictory guidance.

Suggested change
Indexes can also include symbolic names.
Indexes can also include symbolic names. This section provides a brief
overview; for a complete description of text index syntax, see the Tk
:manpage:`text(n)` manual page.

Copilot uses AI. Check for mistakes.

Examples:

* ``"1.0"`` – the beginning of the text
* ``"end"`` – the end of the text
* ``"insert"`` – the current insertion cursor position

Comment on lines +1004 to +1006
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description of the "end" index as “the end of the text” is a bit misleading for Text widgets: Tk text widgets maintain a trailing newline, so using end commonly includes an extra newline and users often need end-1c (or similar) to exclude it. It would be helpful to mention this nuance in the index examples.

Suggested change
* ``"end"`` – the end of the text
* ``"insert"`` – the current insertion cursor position
* ``"end"`` – the position just after the last character (for :class:`Text`
widgets this is after the trailing newline, so use ``"end-1c"`` to exclude it)
* ``"insert"`` – the current insertion cursor position

Copilot uses AI. Check for mistakes.
Methods
-------

.. method:: insert(index, chars, *args)

Insert *chars* at the given *index*.

.. method:: get(index1, index2=None)

Return the text between *index1* and *index2*. If *index2* is omitted,
returns the character at *index1*.

.. method:: delete(index1, index2=None)
Comment on lines +1010 to +1019
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new .. method:: directives are unqualified (e.g., just insert/get/delete). In this file, method directives are otherwise qualified (e.g., Widget.tk.createfilehandler), and unqualified method targets are likely to create ambiguous index entries / weak cross-references. Consider qualifying these (e.g., Text.insert or tkinter.Text.insert) or introducing a .. class:: Text directive and indenting the methods under it so Sphinx can associate them with the class.

Suggested change
.. method:: insert(index, chars, *args)
Insert *chars* at the given *index*.
.. method:: get(index1, index2=None)
Return the text between *index1* and *index2*. If *index2* is omitted,
returns the character at *index1*.
.. method:: delete(index1, index2=None)
.. method:: Text.insert(index, chars, *args)
Insert *chars* at the given *index*.
.. method:: Text.get(index1, index2=None)
Return the text between *index1* and *index2*. If *index2* is omitted,
returns the character at *index1*.
.. method:: Text.delete(index1, index2=None)

Copilot uses AI. Check for mistakes.

Delete text between *index1* and *index2*.
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

delete(index1, index2=None): the text says it deletes “between index1 and index2”, but doesn’t describe the index2-omitted behavior. For Text.delete(index1) this deletes a single character at index1; documenting that would make this method description accurate and consistent with the preceding get description.

Suggested change
Delete text between *index1* and *index2*.
Delete text between *index1* and *index2*. If *index2* is omitted,
deletes the character at *index1*.

Copilot uses AI. Check for mistakes.

Tags
----

Tags allow you to apply formatting and other attributes to ranges of text.

Example::

text.tag_add("highlight", "1.0", "1.5")
text.tag_config("highlight", background="yellow")

Tags can control styling such as fonts, colors, and spacing, and can also
be used to bind events to specific text regions.

Marks
-----

Marks represent named positions within the text. They move automatically
as the text is modified.

Example::

text.mark_set("my_mark", "1.0")

Embedded widgets
----------------

The :class:`tkinter.Text` widget can contain other widgets, such as buttons or images,

Check warning on line 1049 in Doc/library/tkinter.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:class reference target not found: tkinter.Text [ref.class]
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Embedded widgets” example text mixes widgets and images (“widgets, such as buttons or images”). In Tk terminology, images aren’t widgets; they’re embedded via image handling APIs. Consider rephrasing to distinguish embedding windows (widgets) vs embedding images, to avoid conceptual confusion.

Suggested change
The :class:`tkinter.Text` widget can contain other widgets, such as buttons or images,
The :class:`tkinter.Text` widget can contain other widgets, such as buttons,

Copilot uses AI. Check for mistakes.
embedded directly within the text flow.
Comment on lines +1049 to +1050
Copy link

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The line describing embedded widgets is quite long and exceeds the line-wrapping style used throughout this document. Please wrap it to match the surrounding reST formatting (typically ~79–80 columns) so future diffs stay readable.

Suggested change
The :class:`tkinter.Text` widget can contain other widgets, such as buttons or images,
embedded directly within the text flow.
The :class:`tkinter.Text` widget can contain other widgets, such as buttons
or images, embedded directly within the text flow.

Copilot uses AI. Check for mistakes.

Undo and redo
-------------

The widget optionally supports undo and redo operations when configured
with the ``undo=True`` option.

Example::

text = tk.Text(root, undo=True)

Images
^^^^^^
Expand Down
Loading