The Tk Text Widget

The powerful text widget in the Tk toolkit offers many facilities to writers of Tcl, Perl and Python scripts.

All script writers need to deal with textual data at one time or another. One of the most powerful tools for manipulating text in the free software world is the text widget found in the Tk graphical user interface (GUI) toolkit. This widget is available to script writers working with Tcl, Perl/Tk and Tkinter in Python, and it boasts features and functionality that can solve almost any text-related requirement a script writer is likely to encounter.

Key features include multi-line text display and editing, comprehensive text formatting, embedded images, embedded widgets and a unique, almost boundless mechanism for endowing dynamic behaviour on areas of text. This article discusses the features of the Tk text widget that make it a rich and dynamic text manipulation utility. Examples are presented in Tcl/Tk code, but users of other languages shouldn't have much trouble translating the concepts and examples to their favoured environments. Before we get started, however, we need to take a quick look at a couple of concepts employed by the widget.

Indices in the Text

Each character stored in a text widget can be addressed by an index. An index most often is defined by two numbers, the line number and the character position on that line. As an example, the index 10.45 refers to the character on line 10, position 45.

The text widget has built-in functionality for index arithmetic; it supports expressions that allow you to find a location, say, 10 lines and 15 characters from a given point. It also handles special indices containing a pixel location (specified as @x,y) or containing certain words. For example, 1.end means the character at the end of the first line, insert means the character at the input cursor and current means the character under the mouse pointer.

Tagging Parts of the Text

The feature that provides the Tk text widget with much of its power is known as tagging. Any area of the text, defined as starting at one index and ending at another, can be tagged with a logical tag name. Each tag can be assigned certain attributes and properties, and all the areas of text given that tag immediately take on the assigned properties. A good part of this article discusses the properties that can be controlled and the uses to which this tagging feature can be put.

The Tk text widget provides all the facilities required for rich text editing. This includes flexible font handling, adjustable line spacing and margins, word wrap, colour support, cut, copy and paste, an undo stack, plus the usual array of bold, underline, italic and other formatting options. Figure 1 is a screenshot of one of the demonstration scripts supplied with Tk. It shows some of the formatting options available. Figure 1 here

All formatting is implemented using the tags mechanism. The script writer defines a tag with the formatting required, then either inserts the required text with that tag or applies that tag to an area of text already in the widget. For example, for an individual text widget named .t, a title tag might be defined with a large, underlined font and centre justification:

.t tag configure title -font "helvetica 14" \
                       -justify "center" \
                       -underline on

To insert some title text into the widget, this code can be used:

.t insert 1.0 "The Legend of Black Cave\n" title

This inserts the text at line 1, position 0, with the tag title applied. Alternatively, the tag can be applied to text already in the widget by using code like:

.t tag add title 1.0 1.end

This adds the title tag to the text between the given indices, in this case between the start and end of line 1. In a more realistic situation those indices wouldn't be hard coded. They are more likely to be calculated from the location of the selection, for example, or the results of a search. Notice that the command used to assign a tag to an area of text is add. This is because an area of text can have several tags assigned to it. For example, our title text also might need to be highlighted as the result of a search or to indicate that its status has changed to urgent.

Figure 2 is a screenshot of a small script (Listing 1) that demonstrates formatting by way of tag manipulation. It also demonstrates the text widget's useful ability to save marks, or named locations, anywhere in the text. Figure 2 here

Embedding Images and Widgets

In addition to text formatting, the Tk text widget also supports embedding images and other GUI control widgets. When images are inserted into the text, they float, so editing of the text around them causes them to move in accordance with the formatting rules configured for that area of text. The same image can be inserted into the widget multiple times, and if an image is modified dynamically elsewhere in the script, its representation in the text widget is updated immediately.

Other Tk GUI widgets can be inserted into the text widget. Simple buttons and dropdown lists, as might be found amongst the text of a web page, are only the beginning. It is possible to embed anything--a drawing canvas, a table or even another text widget. If you have a complicated set of widgets that need to be presented inside some text, the text widget has a mechanism whereby it creates only those widgets when necessary--when the appropriate area is scrolled into view, for example.



Comment viewing options


Re: The Tk Text Widget

Anonymous's picture

Error in startup script: invalid command name "tk_TextSetCursor"
while executing
"tk_TextSetCursor .t 1.0"
(file "textdemo.tcl" line 63)
What version of Tk is required for the textdemo.tcl script ?

Watch the angle brackets

Anonymous's picture

I spent about 20 minutes trying to get the tag binding code to work before I realized that the <Button-1> stuff was missing. It's in the HTML source, though, you just need to escape it. (As does this text entry box, apparently)

Not just Tcl, Perl, and Python.

techentin's picture

The Tk Text widget is available to scripters, INCLUDING those working in Perl, Python, and Tcl, but not restricted to them. Users of Ruby, PHP, Scheme, and other languages have access to the Text widget. Although Tcl/Tk, Tkinter, and Perl/Tk are the most mature.

Perl/Tk is not only one for Tk for Perl

Vadim Konovalov's picture

Perl/Tk has connection from Perl to Tk, while Tcl is striped out in this approach
CPAN module Tcl::Tk is another approach that connects to Tk via Tcl. This approach is more flexible and better than one from perl/Tk, see for comments.
To mention, Ruby, Python (dont know about others) do also this way (via Tcl)

Re: Not just Tcl, Perl, and Python.

Anonymous's picture

ruby/tk has been included with the interpreter for years, I think it's quite mature now..

Re: The Tk Text Widget

Anonymous's picture

Nice article which demonstrates well how a small body of code can do very useful things with the text widget.
However, there is an error in presentation that should be fixed ASAP:

.t tag configure title -font "helvetica 14"
-justify "center"
-underline on

Is broken Tcl code. The first two lines need to end with
backslash. As is it Tcl will complain about "-justify" being an
unknown command!

Re: The Tk Text Widget

derekfountain's picture

That's true; I missed that. The original text was:

.t tag configure title -font "helvetica 14"
-justify "center"
-underline on

There's also a (harmless) edit in another code snippet. The text insertion listing originally said this:

.t insert 1.0 "The Legend of Black Cave
" title

The LJ formatting process replaced the
for a literal newline.

Re: The Tk Text Widget

derekfountain's picture

Hmm, that's interesting. I previewed my comment to ensure it would look OK and it did. On the live page the slashes disappear again! It should be one long line; breaking with slashes was just for formatting.

.t tag configure title -font "helvetica 14" -justify "center" -underline on

.t insert 1.0 "The Legend of Black Cave
" title

Re: The Tk Text Widget

Anonymous's picture

The Tk text widget really is a fantastic thing -- powerful enough even for entire text editors or web browsers to be built on top of! Yet, in Tk 8.5 it has become even better!

Editing in the Caveats section

derekfountain's picture

The first two sentences in the "Caveats" section have been edited slightly by Linux Journal. The changes are minor, but I feel they significantly alter the feel of what I said. For the record, the original text was:

"There are very few problems with the Tk text widget. When a tool has been around for as long as this one, it gets honed closer to perfection with each release."