Text Indexes (Mastering Perl/Tk)

8.4. Text Indexes

When we talked about Listbox index values, each index referred to a line in the Listbox. The first line in the Listbox was at index 0, and so on. With a Text widget, the index can point to a specific line, but it can also point to a character within that line. An index for a Text widget is built using a base index and then optionally modifying that index. The entire index, base, and modifier should be put in double quotes.

8.4.1. Base Index Values

Here is a list of base index values:

'n.m': This format allows you to explicitly specify a line number and a character number within that line. Lines start at 1 (which is different than the Listbox widget), and characters start at 0.
'@x,y': The character in the widget that is closest to the (x, y) coordinate.
'end': The very end of the Text widget, after any "\n" characters as well.
'mark': This specifies the character after the location named mark. The two mark names provided by Tk are "current" and "insert". We'll discuss what they refer to later in this chapter.
'tag.first': A tag name is simply a placeholder for some special formatting instructions (discussed in the very next section). After creating tags, you can use this index form. tag.first is the first character in the Text widget that is of type tag. That is, you could create a "heading" tag and use a "heading.first" index.
'tag.last': This specifies the character directly after the text marked with tag.
$widget: If you have an embedded widget, you can refer to its location within the Text widget by the variable referring to it.
$image: You can have embedded images as of Tk 8.0. You can refer to their locations by using the variables referring to them.

8.4.2. Index Modifiers

The index modifiers can be used following a base index value.

[ + | - ] count [ chars | lines ]

8.4.3. Text Index Examples

Here are some text index examples:

'end': The position right after the last line of text in the widget, no matter how much text is in the widget.
'1.0': The first character on the first line in the Text widget. The 1 represents the line, and 0 represents the character.
'2.0 - 1 chars': The last character on the end of the first line. We reference it by using the first character on the second line (2.0) and subtracting one character value from that. If we use the insert method with this item, we insert the text right before the "\n" at the end of the first line.
'1.end': Also the last character on the end of the first line. This is a simpler way of getting to it.
'2.0 lineend': The end of the second line. It is necessary to specify 2.0, not just 2, because 2 is an invalid base index.
'sel.first': The beginning of the current selection. This index might not exist if there isn't currently a selection.

The basic indexes are easy. When you start doing index arithmetic, it becomes a little more complicated. Just remember that you are referring to a position in the Text widget that may change if other text is inserted or deleted (either by the user or the application).

Although some of the combinations may seem silly (e.g., '1.0 linestart'), keep in mind that you will most likely be calling methods that return indeterminate information about an event. For example, a user clicks in the Text widget and presses a Button that will increase the font size of that entire line. The index arithmetic allows you to reference that entire line without even knowing for sure which line it is on.