Marks (Mastering Perl/Tk)

8.16. Marks

There are several ways to refer to different positions throughout the Text widget. An index value refers to a character. A tag is a named reference to a specific character or group of characters. The term mark refers to the spaces between characters. Similar to tags, a mark has a name. For example, the "insert" mark refers to the position of the insert cursor. However, tags refer to the actual characters, and if those characters are deleted, the tag is no longer associated with those characters. The mark stays in place whether the characters surrounding it are deleted or other characters are added. Marks can refer only to one location within the Text widget at a time.

Once a mark is created, you can use it as an index. The gravity of the mark will determine if the mark moves or not when you insert text with it. Using a gravity of 'right' (the default) means that any text inserted using that mark will go to the left of the mark. A gravity of 'left' means that text inserted using that mark will go to the right of the mark. Another way to think about it is the gravity tells you which side the mark will stick to. For example, suppose we have the string "abcdef" and place the mark in between the c and the d. We'll represent the mark as a ^ character. Using 'right' gravity, "abc^def" becomes "abc1232^def" because the mark sticks to the character to its right. Using 'left' gravity, "abc^def" becomes "abc^123def" because the mark sticks to the character to its left.

There are two special marks that are set automatically by the Text widget: "insert" and "current". The "insert" mark is wherever the insert cursor is. The "current" mark is the position closest to the mouse and adjusts as the mouse moves (as long as a mouse button is pressed). Both marks are maintained internally and cannot be deleted.

You will also see a mark called "anchor" that shows up in the markNames method after you click in the Text widget. It always has the same index value as the "insert" mark, but "anchor" might not always exist.

8.16.1. Setting and Getting the Gravity

To set the gravity of the mark, you can use markGravity:

$text->markGravity(markname [ , direction ])

The possible values for direction are "right" and "left". The default gravity for new marks is "right". If you don't specify a gravity, the current gravity for that mark is returned.

8.16.2. Determining Mark Names

To get a list of all the marks in the Text widget, you can use markNames:

@names = $text->markNames( )

There are no arguments to the markNames function, and it returns a list. Here is an example of how to report the marks within the Text widget:

$f->Button(-text => "Report", 
           -command => sub { my @m = $t->markNames( ); 
                             foreach (@m) {
                               print "MARK: $_ at ", $t->index($_), "\n";
                           }})->pack(-side => 'left');

The results after clicking in the window to set the insertion cursor are as follows:

MARK: insert at 2.15
MARK: anchor at 2.15
MARK: current at 3.0

8.16.3. Creating and Deleting Marks

You can create a mark and set it at a specific index by using the markSet method.

$text->markSet(markname, index)

In addition to the markname you want to create, specify the index where the mark should be placed. For instance, if you always want to be able to insert at the end of line 3:

$text->markSet("end of line3", "3.0 lineend");
...
$text->insert("end of line3", "text to insert");

The markUnset method removes the mark from the Text widget and deletes the mark completely. It will no longer show up in the markNames list after it has been unset, and it can't be used as an index value either. You can specify more than one markname in markUnset:

$text->markUnset(markname [, markname, markname ... ])