The Perl/Tk Text Widget Extended Methods

These methods are available only with the Perl/Tk Text widget and are documented nowhere else but in this tutorial. Another unique feature is the built-in Menu, activated by a <Button-3> click, which calls many of these methods for common text-related activities. The built-in Menu is shown in Figure 8-7.

Figure 8-7. Built-in Menu

To disable the default Menu, use $text->menu(undef). To supply your own Menu, first create it and then use $text->menu(my_menu).

Here, then, is the complete list of extended Text widget methods. These methods should be considered experimental, so use them with caution and expect that you may have to change your code in the future.

• $text->adjustSelect
• Moves the end point of selection and anchor point to the mouse pointer location.
• $text->clipboardColumnCopy
• Performs a rectangular copy of the currently selected text, with basic compensation for tab characters.
• $text->clipboardColumnCut
• Performs a rectangular cut of the currently selected text, with basic compensation for tab characters.
• $text->clipboardColumnPaste
• Performs a rectangular paste of the text in the clipboard. The upper-left corner is specified by the current position of the insert mark, with basic compensation for tab characters.
• $text->deleteSelected
• Deletes the currently selected text.
• $text->DeleteTextTaggedWith(tag)
• Deletes the text tagged with the tag parameter.
• $text->deleteToEndofLine
• Deletes from the insert mark location to end of line.
• $text->FindAll(mode case pattern)
• First removes any current selections, then performs a global text search, tagging all matches with the sel tag. mode can be -exact or -regexp, and case can be -nocase or -case. pattern is an exact string to match if mode is -exact or a regular expression if the match mode is -regexp.
• $text->FindAndReplaceAll(mode case find replace)
• Works just like FindAll, but additionally substitutes the matched text with the characters replace.
• $text->FindAndReplacePopUp
• Creates a find-and-replace popup if one doesn't already exist. If there is text currently selected, pre-fills the "find" field with it.
• $text->FindNext(direction mode case pattern)
• First removes any current selections, then performs a forward or reverse text search, tagging a match with the sel tag. direction can be -forward or -reverse. mode, case, and pattern are as for FindAll.
• $text->FindPopUp
• Creates a find popup, if one doesn't already exist. If there is text currently selected, pre-fills the "find" field with it.
• $text->FindSelectionNext
• Gets the currently selected text and removes all selections. It then finds the next exact, case-sensitive string that matches in a forward direction, selects the new text, and makes it visible.
• $text->FindSelectionPrevious
• Gets the currently selected text and removes all selections. It then finds the next exact, case-sensitive string that matches in a reverse direction, selects the new text, and makes it visible.
• $text->getSelected
• Returns the currently selected text.
• $text->GetTextTaggedWith(tag)
• Returns the text tagged with the tag parameter.
• $text->GotoLineNumber(line_number)
• Sets the insert mark to line_number and displays the line.
• $text->GotoLineNumberPopUp
• Displays a popup, pre-filling it with selected numeric text, if any, or the line number from GotoLineNumber, if any.
• $text->Insert(string)
• Inserts string at the point of the insertion cursor. If there is a selection in the text, and it covers the point of the insertion cursor, delete the selection before inserting.
• $text->InsertKeypress(character)
• Inserts character at the insert mark. If in overstrike mode, delete the character at the insert mark first.
• $text->InsertSelection
• Inserts the current selection at the insert mark.
• $text->insertTab
• Inserts a tab (t) character at the insert mark.
• $text->markExists(markname)
• Returns true if markname exists.
• $text->menu(?menu?)
• Returns the Text widget's Menu reference if menu is omitted, disables the Menu if menu is undef, or changes the Menu if menu is another Menu reference.
• $text->openLine
• Inserts a newline (n) at the insert mark.
• $text->OverstrikeMode(?boolean?)
• Returns the overstrike mode if boolean is omitted or sets the overstrike mode to boolean. True means overstrike mode is enabled.
• $text->PostPopupMenu(x, y)
• Creates a popup Menu at the specified (x, y) pixel coordinates. The default Menu has File, Edit, Search, and View menu items that cascade to submenus for further commands. There is an implicit <Button-3> binding to this method that posts the Menu over the cursor.
• $text->ResetAnchor
• Sets the selection anchor to whichever end is farthest from the index argument.
• $text->selectAll
• Selects all the text in the widget.
• $text->selectLine
• Selects the line with the insert mark.
• $text->selectWord
• Selects the word with the insert mark.
• $text->SetCursor(position)
• Moves the insert mark to position.
• $text->ToggleInsertMode
• Toggles the current overstrike mode.
• $text->unselectAll
• Unselects all the text in the widget.
• $text->WhatLineNumberPopUp
• Creates a popup that displays the current line number of the insert mark.

For a demonstration of these extended Text widget features, run the widget demonstration "Gedi master advanced text editor"[18] from the "User Contributed Demonstrations" section of the program.

[18] Yes, that's "Gedi," not "Jedi" (with apologies to George Lucas).