The characters in a text widget are addressed by their line number and the character position within the line. Lines are numbered starting at one, while characters are numbered starting at zero. The numbering for lines was chosen to be compatible with other programs that number lines starting at one, like compilers that generate line-oriented error messages. Here are some examples of text indices:

There are also symbolic indices. The insert index is the position at which new characters are normally inserted when the user types in characters. You can define new indices called marks, too, as described later. Table 36-1 summarizes the various forms for a text index.

$t insert index string ?tagList? ?string tagList? ...

$t insert insert "Hello, World
"

$t delete 1.0 2.0

$t delete 1.0 2.0 4.0 5.0 8.0 9.0

"insert lineend"
"insert -3 chars"

$t delete "insert wordstart" "insert wordend"

$t delete "insert linestart" "insert lineend +1 char"

$t compare ix1 op ix2

A mark is a symbolic name for a position between two characters. Marks have the property that when text is inserted or deleted they retain their logical position, not their numerical index position. Marks are persistent: If you delete the text surrounding a mark, it remains intact. Marks are created with the mark set operation and must be explicitly deleted with the mark unset operation. Once defined, a mark can be used in operations that require indices. The following commands define a mark at the beginning of the word containing the insert cursor and delete from there up to the end of the line:

$t mark set foobar "insert wordstart"
$t delete foobar "foobar lineend"
$t mark unset foobar

When a mark is defined, it is set to be just before the character specified by the index expression. In the previous example, this is just before the first character of the word where the insert cursor is. When a mark is used in an operation that requires an index, it refers to the character just after the mark. So, in many ways the mark seems associated with the character right after it, except that the mark remains even if that character is deleted.

You can use almost any string for the name of a mark. However, do not use pure numbers and do not include spaces, plus (+) or minus (-). These characters are used in index arithmetic and may cause problems if you put them into mark names. The mark names operation returns a list of all defined marks.

The insert mark defines where the insert cursor is displayed. The insert mark is treated specially: you cannot remove it with the mark unset operation. Attempting to do so does not raise an error, though, so the following is a quick way to unset all marks. The eval is necessary to join the list of mark names into the mark unset command:

eval {$t mark unset} [$t mark names]

Mark Gravity

$t mark gravity foobar
=> right
$t mark gravity foobar left

A tag is a symbolic name that is associated with one or more ranges of characters. A tag has attributes that affect the display of text that is tagged with it. These attributes include fonts, colors, tab stops, line spacing and justification. A tag can have event bindings so you can create hypertext. A tag can also be used to represent application-specific information. The tag names and tag ranges operations described later tell you what tags are defined and where they are applied.

You can use almost any string for the name of a tag. However, do not use pure numbers, and do not include spaces, plus (+) or minus (-). These characters are used in index arithmetic and may cause problems if you use them in tag names.

A tag is added to a range with the tag add operation. The following command applies the tag everywhere to all the text in the widget:

$t tag add everywhere 1.0 end

You can add one or more tags when text is inserted, too:

$t insert insert "new text" {someTag someOtherTag}

If you do not specify tags when text is inserted, then the text picks up any tags that are present on the characters on both sides of the insertion point. (Before Tk 4.0, tags from the left-hand character were picked up.) If you specify tags in the insert operation, only those tags are applied to the text.

A tag is removed from a range of text with the tag remove operation. However, even if there is no text labeled with a tag, its attribute settings are remembered. All information about a tag can be removed with the tag delete operation:

$t tag remove everywhere 3.0 6.end
$t tag delete everywhere

Tag Attributes

The attributes for a tag are defined with the tag configure operation. For example, a tag for blue text is defined with the following command:

$t tag configure blue -foreground blue

Table 36-3 specifies the set of attributes for tags. Some attributes can only be applied with tags; there is no global attribute for -bgstipple, -elide, -fgstipple, -justify, -lmargin1, -lmargin2, -offset, -overstrike, -rmargin, and -underline. Table 36-10 on page 557 lists the attributes for the text widget as a whole.

The -relief and -borderwidth attributes go together. If you only specify a relief, there is no visible effect. The default relief is flat, too, so if you specify a border width without a relief you won't see any effect either.

The stipple attributes require a bitmap argument. Bitmaps and colors are explained in more detail in Chapter 41. For example, to “grey out” text you could use a foreground stipple of gray50:

$t tag configure disabled -fgstipple gray50

The -elide attribute, added in Tk 8.3, controls whether or not the text is displayed. It can be quite useful to set the -elide attribute to True to hide embedded information, such as HTML or XML tags or URLs for hotlinks.

Table 36-3. Attributes for text tags

-background color	The background color for text.
-bgstipple bitmap	A stipple pattern for the background color.
-borderwidth pixels	The width for 3D border effects.
-elide boolean	If True, then the text is not displayed. (Tk 8.3)
-fgstipple bitmap	A stipple pattern for the foreground color.
-font font	The font for the text.
-foreground color	The foreground color for text.
-justify how	Justification: left, right, or center.
-lmargin1 pixels	Normal left indent for a line.
-lmargin2 pixels	Indent for the part of a line that gets wrapped.
-offset pixels	Baseline offset. Positive for superscripts.
-overstrike boolean	Draw text with a horizontal line through it.
-relief what	flat, sunken, raised, groove, solid or ridge.
-rmargin pixels	Right-hand margin.
-spacing1 pixels	Additional space above a line.
-spacing2 pixels	Additional space above wrapped part of line.
-spacing3 pixels	Additional space below a line.
-tabs tabstops	Specifies tab stops.
-underline boolean	If true, the text is underlined.
-wrap mode	Line wrap: none, char, or word.

Note

Configure tags early.

You can set up the appearance (and bindings) for tags once in your application, even before you have labeled any text with the tags. The attributes are retained until you explicitly delete the tag. If you are going to use the same appearance over and over again, then it is more efficient to do the setup once so that Tk can retain the graphics context.

On the other hand, if you change the configuration of a tag, any text with that tag will be redrawn with the new attributes. Similarly, if you change a binding on a tag, all tagged characters are affected immediately.

Example 36-1 defines a few tags for character styles you might see in an editor. The example uses the font naming system added in Tk 8.0, which is described on page 636.

Example 36-1. Tag configurations for basic character styles

proc TextStyles { t } {
   $t tag configure bold -font {times 12 bold}
   $t tag configure italic -font {times 12 italic}
   $t tag configure fixed -font {courier 12}
   $t tag configure underline -underline true
   $t tag configure super -offset 6 -font {helvetica 8}
   $t tag configure sub -offset -6 -font {helvetica 8}
}

$t tag configure deleted -background grey75
$t tag configure moved -background yellow

$t tag configure select -underline true

Line Spacing and Justification

The spacing and justification for text have several attributes. These settings are complicated by wrapped text lines. The text widget distinguishes between the first display line and the remaining display lines for a given text line. For example, if a line in the text widget has 80 characters but the window is only wide enough for 30, then the line may be wrapped onto three display lines. See Table 36-10 on page 557 for a description of the text widget's wrap attribute that controls this behavior.

Spacing is controlled with three attributes, and there are global spacing attributes as well as per-tag spacing attributes. The -spacing1 attribute adds space above the first display line, while -spacing2 adds space above the subsequent display lines that exist because of wrapping. The -spacing3 attribute adds space below the last display line, which could be the same as the first display line if the line is not wrapped.

The margin settings also distinguish between the first and remaining display lines. The -lmargin1 attribute specifies the indent for the first display line, while the -lmargin2 attribute specifies the indent for the rest of the display lines, if any. There is only a single attribute, -rmargin, for the right indent. These margin attributes are only tag attributes. The closest thing for the text widget as a whole is the -padx attribute, but this adds an equal amount of spacing on both sides:

Example 36-2. Line spacing and justification in the text widget

proc TextExample { f } {
   frame $f
   pack $f -side top -fill both -expand true
   set t [text $f.t -setgrid true -wrap word 
      -width 42 -height 14 
      -yscrollcommand "$f.sy set"]
   scrollbar $f.sy -orient vert -command "$f.t yview"
   pack $f.sy -side right -fill y
   pack $f.t -side left -fill both -expand true

   $t tag configure para -spacing1 0.25i -spacing2 0.1i 
      -lmargin1 0.5i -lmargin2 0.1i -rmargin 0.5i
   $t tag configure hang -lmargin1 0.1i -lmargin2 0.5i

   $t insert end "Here is a line with no special settings
"
   $t insert end "Now is the time for all good women and men to come to the aid of their
 country. In this great time of need, no one can avoid their responsibility.
"
   $t insert end "The quick brown fox jumps over the lazy dog."

   $t tag add para 2.0 2.end
   $t tag add hang 3.0 3.end
}

The example defines two tags, para and hang, that have different spacing and margins. The -spacing1 setting for para causes the white space before the second line. The -spacing2 setting causes the white space between the wrapped portions of the second paragraph. The hang tag has no spacing attributes, so the last paragraph starts right below the previous paragraph. You can also see the difference between the -lmargin1 and -lmargin2 settings.

The newline characters are inserted explicitly. Each newline character defines a new line for the purposes of indexing, but not necessarily for display, as this example shows. In the third line there is no newline. This means that if more text is inserted at the end mark, it will be on line three.

The values for the spacing and margin parameters are in screen units. Because different fonts are different sizes, you may need to compute the spacings as a function of the character sizes. The bbox operation returns the bounding box (x, y, width, height) for a given character:

$t insert 1.0 "ABCDE"
$t bbox 1.0
=> 4 4 8 12

The Tk 8.0 font metrics command, which is described on page 640, also gives detailed measurements:

font metrics {times 12}
-ascent 9 -descent 3 -linespace 12 -fixed 0

Text justification is limited to three styles: left, right, or center. There is no setting that causes the text to line up on both margins, which would have to be achieved by introducing variable spacing between words.

*Text.tabs: 2c left 4c right 6c center 8c numeric

$t tag configure foo -tabs ".5i left"

The selection is implemented with a predefined tag named sel. If the application tags characters with sel, those characters are added to the selection. This is done as part of the default bindings on the text widget.

The exportSelection attribute of a text widget controls whether or not selected text is exported by the selection mechanism to other applications. By default the selection is exported. In this case, when another widget or application asserts ownership of the selection then the sel tag is removed from any characters that are tagged with it. Chapter 38 describes the selection mechanism in more detail.

You cannot delete the sel tag with the tag delete operation. However, it is not an error to do so. You can delete all the tags on the text widget with the following command. The eval command is used to join the list of tag names into the tag delete command:

eval {$t tag delete} [$t tag names]

You can associate a tag with bindings so that when the user clicks on different areas of the text display, different things happen. The syntax for the tag bind command is similar to that of the main Tk bind command. You can both query and set the bindings for a tag. Chapter 29 describes the bind command and the syntax for events in detail.

The only events supported by the tag bind command are Enter, Leave, ButtonPress, ButtonRelease, Motion, KeyPress, and KeyRelease. ButtonPress and KeyPress can be shorted to Button and Key as in the regular bind command. The Enter and Leave events are triggered when the mouse moves in and out of characters with a tag, which is different from when the mouse moves in and out of the window.

If a character has multiple tags, then the bindings associated with all the tags will be invoked, in the order from lowest priority tag to highest priority tag. After all the tag bindings have run, the binding associated with the main widget is run, if any. The continue and break commands work inside tag bindings in a similar fashion as they work with regular command bindings. See Chapter 29 for the details.

Example 36-3 defines a text button that has a highlighted relief and an action associated with it. The example generates a new tag name so that each text button is unique. The relief and background are set for the tag to set it apart visually. The winfo visual command is used to find out if the display supports color before adding a colored background to the tag. On a black and white display, the button is displayed in reverse video (i.e., white on black.) The command is bound to <Button-1>, which is the same as <ButtonPress-1>.

The cursor is changed when the mouse is over the tagged area by binding to the <Enter> and <Leave> events. Upon leaving the tagged area, the cursor is restored. Another tag is used to remember the previous setting for the cursor. You could also use a global variable, but it is often useful to decorate the text with tags for your own purposes.

proc TextButton { t start end command } {
   global textbutton
   if ![info exists textbutton(uid)] {
      set textbutton(uid) 0
   } else {
      incr textbutton(uid)
   }
   set tag button$textbutton(uid)
   $t tag configure $tag -relief raised -borderwidth 2
   if {[regexp color [winfo visual $t]]} {
      $t tag configure $tag -background thistle
   } else {
      $t tag configure $tag -background [$t cget -fg]
      $t tag configure $tag -foreground [$t cget -bg]
   }
   # Bind the command to the tag
   $t tag bind $tag <Button-1> $command
   $t tag add $tag $start $end
   # use another tag to remember the cursor
   $t tag bind $tag <Enter> 
      [list TextButtonChangeCursor %W $start $end tcross]
   $t tag bind $tag <Leave> {TextButtonRestoreCursor %W}
}
proc TextButtonChangeCursor {t start end cursor} {
   $t tag add cursor=[$t cget -cursor] $start $end
   $t config -cursor $cursor
}
proc TextButtonRestoreCursor {t} {
   regexp {cursor=([^ ]*)} [$t tag names] x cursor
   $t config -cursor $cursor
}

To behave even more like a button, the action should trigger upon <ButtonRelease-1>, and the appearance should change upon <ButtonPress-1>. If this is important to you, you can always embed a real Tk button. Embedding widgets is described later.

The search operation scans the text widget for a string that matches a pattern. The index of the text that matches the pattern is returned. The search starts at an index and covers all the text widget unless a stop index is supplied. You can use end as the stop index to prevent the search from wrapping back to the beginning of the document. The general form of the search operation is this:

$t search ?options? pattern index ?stopIndex?

Table 36-4 summarizes the options to the search operation:

If you use a regular expression to match a pattern, you may be interested in how much text matched so you can highlight the match. The -count option specifies a variable that gets the number of matching characters:

set start [$t search -count cnt -regexp -- $pattern 1.0 end]
$t tag add sel $start "$start +$cnt chars"

The text widget can display embedded widgets as well as text. You can include a picture, for example, by constructing it in a canvas and then inserting the canvas into the text widget. An embedded widget takes up one character in terms of indices. You can address the widget by its index position or by the Tk pathname of the widget.

For example, suppose $t names a text widget. The following commands create a button and insert it into the text widget. The button behaves normally, and in this case it invokes the Help command when the user clicks on it:

button $t.help -bitmap questhead -command Help
$t window create end -window $t.help

By default an embedded widget is centered vertically on its text line. You can adjust this with the -align option to the window create command. This setting only takes effect if the window is smaller than the text in the line. I find that windows are usually larger than the text line, and in that case the -align setting has no effect. This setting is also used with images, however, where it is more common to have small images (e.g., for special bullets). Table 36-5 describes the window and image alignment settings:

You can postpone the creation of the embedded widget by specifying a Tcl command that creates the window, instead of specifying the -window option. The delayed creation is useful if you have lots of widgets embedded in your text. In this case the Tcl command is evaluated just before the text widget needs to display the widget. In other words, when the user scrolls the text so the widget will appear, the Tcl command is run to create the widget:

$t window create end -create [list MakeGoBack $t]
proc MakeGoBack { t } {
   button $t.goback -text "Go to Line 1" 
      -command [list $t see 1.0]
}

The MakeGoBack procedure is introduced to eliminate potential quoting problems. If you need to execute more than one Tcl command to create the widget or if the embedded button has a complex command, the quoting can quickly get out of hand.

Table 36-6 gives the complete set of options for creating embedded widgets. You can change these later with the window configure operation. For example:

$t window configure $t.goback -padx 2

You can specify the window to reconfigure by its pathname or the index where the window is located. In practice, naming the widget by its pathname is much more useful. Note that end is not useful for identifying an embedded window because the text widget treats end specially. You can insert a window at end, but end is always updated to be after the last item in the widget. Thus end will never name the position of an existing window.

Tk 8.0 added embedded images that are much like embedded windows. They provide a more efficient way to add images than creating a canvas or label widget to hold the image. You can also put the same image into a text widget many times. Example 36-5 uses an image for the bullets in a bulleted list:

proc BList_Setup { t imagefile } {
   global blist
   set blist(image) [image create photo -file $imagefile]
   $t tag configure bulletlist -tabs ".5c center 1c left" 
      -lmargin1 0 -lmargin2 1c
}
proc BList_Item { t text {mark insert}} {
   global blist
   # Assume we are at the beginning of the line
   $t insert $mark 	 bulletlist
   $t image create $mark -image $blist(image)
   $t insert $mark 	$text bulletlist
}

In Example 36-5, tabs are used to line up the bullet and the left edges of the text. The first tab centers the bullet over a point 0.5 centimeters from left margin. The second tab stop is the same as the -lmargin2 setting so the text on the first line lines up with the text that wraps onto more lines.

If you update the image dynamically, all the instances of that image in the text widget are updated, too. This follows from the image model used in Tk, which is described in Chapter 41 on page 625.

The options for embedded images are mostly the same as those for embedded windows. One difference is that images have a -name option so you can reference an image without remembering its position in the text widget. You cannot use the image name directly because the same image can be embedded many times in the text widget. If you do not choose a name, the text widget assigns a name for you. The image create operation returns this name:

$t image create 1.0 -image image1
=> image1
$t image create end -image image1
=> image1#1

Table 36-7 gives the complete set of options for creating embedded images. You can change these later with the image configure operation.

The text widget has several operations that let you examine its contents. The simplest is get, which returns of text from the widget. If only one index is given, the character at that position is returned. If there are two indices, all the characters up to but not including the second index are returned. For example, you can get all the text with this command:

$t get 1.0 end

As of Tk 8.4, you can get multiple ranges of text with a single get operation; the result in this case is a list of the range contents. For example, to retrieve the first and third lines, without the trailing newlines, as a two-element list:

$t get 1.0 1.end 3.0 3.end

$t tag names ?index?

foreach {start end} [$t tag ranges $tag] {
   # start is the beginning of a range
   # end is the end of a range
}

proc Text_CurrentRange { t tag mark } {
   set range [$t tag prevrange $tag $mark]
   set end [lindex $range 1]
   if {[llength $range] == 0 || [$t compare $end < $mark]} {
      # This occurs when the mark is at the
      # very beginning of the node
      set range [$t tag nextrange $tag $mark]
      if {[llength $range] == 0 ||
             [$t compare $mark < [lindex $range 0]]} {
          return {}
      }
   }
   return $range
}

$t dump ?options? ix1 ?ix2?

proc Text_Dump {t {start 1.0} {end end}} {
   foreach {key value index} [$t dump $start $end] {
      if {$key == "text"} {
         puts "$index "$value""
      } else {
         puts "$index $key $value"
      }
   }
}

proc Text_Dump {t {start 1.0} {end end}} {
   $t dump -command TextDump $start $end
}
proc TextDump {key value index} {
   if {$key == "text"} {
      puts "$index "$value""
   } else {
      puts "$index $key $value"
   }
}

Beginning in Tk 8.4, the text widget supports an unlimited undo and redo mechanism. You enable the undo mechanism by setting the text widget's undo attribute to True. The undo attribute has a default value of False for backward compatibility.

When enabled, each insert and delete action, whether performed by the user or programmatically, is recorded on an undo stack. You can programmatically undo an edit with the edit undo operation. The undone changes are then moved to the redo stack, so that an undone edit can be redone again with the with the edit redo operation. The redo stack is cleared whenever new edit actions are recorded on the undo stack. (Both the edit undo and edit redo operations generate error conditions if the undo or redo stack is empty, respectively.) The text widget also has default undo and redo bindings; by default, undo is <Control-z> and redo is <Control-y> on Windows, <Control-Z> on all other platforms. (See “Text Bindings” on page 551.)

Each edit undo operation undoes the last action, which is defined as all of the insert and delete commands that are recorded on the undo stack in between two separators. When the autoSeparators attribute is True (the default), a separator is automatically placed on the stack whenever:

If you set the autoSeparators attribute to False, you are responsible for programmatically placing separators on the stack with the edit separator operation. By turning the autoseparators off and inserting them at the desired points, you can define compound actions, such as search and replace. The default paste binding is an example of such an action, such that overwriting selected text by pasting from the clipboard is considered an atomic action.

As of Tk 8.4, only insert and delete operations are handled by the undo mechanism. In particular, tag operations, such as applying a tag to text, are not actions captured by the undo mechanism, even if the tag was applied as part of an insert operation. As an example, consider the following insertion:

$t insert end "Let's insert some " {} 
    "special" blue " text." {}

If this operation were undone and then redone, the text would be re-inserted, but without applying the blue tag on the word “special”.

Table 36-9 describes the text widget operations, including some that are not discussed in this chapter. In the table, $t is a text widget:

Table 36-10 lists the attributes for the text widget. The table uses the resource name, which has capitals at internal word boundaries. In Tcl commands, the attributes are specified with a dash and all lowercase: