/ 
Tk-Text-SuperText-0.13
/ Tk::Text::SuperText

NAME

Tk::Text::SuperText - An improved text widget for Perl/Tk

SYNOPSIS

use Tk;
use Tk::Text::SuperText;

my $mw = MainWindow->new;
my $super_text = $mw->SuperText(
    -wrap       => 'none',
    -indentmode => 'auto',
    -readonly   => 0,
)->pack(-fill => 'both', -expand => 1);

MainLoop;

STANDARD OPTIONS

-background -highlightbackground -insertontime -selectborderwidth -borderwidth -highlightcolor -insertwidth -selectforeground -cursor -highlightthickness -padx -setgrid -exportselection -insertbackground -pady -takefocus -font -insertborderwidth -relief -xscrollcommand -foreground -insertofftime -selectbackground -yscrollcommand

See Tk::options for details of the standard options.

-height -spacing1 -spacing2 -spacing3 -state -tabs -width -wrap

See Tk::Text for details of these options.

WIDGET-SPECIFIC OPTIONS

Name: readOnly
Class: ReadOnly
Switch: -readonly

Defaults to 0. When true, prevents interactive edits, including cut, paste, rectangular selection shifts, and undo/redo. Navigation, selection, copying, and matching-pair commands remain available. The option can be changed at runtime with $w->configure(-readonly => 1) or the $w->readonly(1) method; $w->readonly returns the current value.

Application calls to insert and delete remain available, allowing the displayed content to be updated while read-only. Unlike -state => 'disabled', this option only blocks editing commands. Toggling it does not clear the content, selection, or undo/redo history. Programmatic edits retain normal undo behavior; call resetUndo after replacing content if its old history is no longer needed.

Name: indentMode
Class: IndentMode
Switch: -indentmode

Specifies how to indent when a new line is inserted in the text. The possible modes are none for no indentation or auto for positioning the insertion cursor directly below the first non-whitespace character of the previous line.

Name: undoDepth
Class: UndoDepth
Switch: -undodepth

Sets the maximum depth of the undo buffer. A positive number specifies how many insert or delete operations can be stored before the oldest one is discarded. 0 disables undo; undef allows unlimited depth.

Name: redoDepth
Class: RedoDepth
Switch: -redodepth

Sets the maximum depth of the redo buffer. A positive number specifies how many undo operations can be stored before the oldest one is discarded. 0 disables redo; undef allows unlimited depth.

Name: showMatching
Class: ShowMatching
Switch: -showmatching

A value of 1 enables automatic matching-pair highlighting; 0 disables it.

Name: matchHighlightTime
Class: MatchHighlightTime
Switch: -matchhighlighttime

Sets the number of milliseconds that a matching character remains highlighted. With a value of 0, the highlight remains until it is cleared or replaced by another match.

Name: matchForeground
Class: MatchForeground
Switch: -matchforeground

Sets the foreground color of the character highlighted by a matching-pair command.

Name: matchBackground
Class: MatchBackground
Switch: -matchbackground

Sets the background color of the character highlighted by a matching-pair command.

Name: matchingCouples
Class: MatchingCouples
Switch: -matchingcouples

Specifies the characters for which matching counterparts are searched. The value is a string of character pairs, with each pair in opening-closing order, for example {}[]()"". When both characters in a pair are identical, as in "", matching searches only forward.

Name: insertMode
Class: InsertMode
Switch: -insertmode

Sets the insertion mode to insert or overwrite.

Name: ansiColor
Class: AnsiColor
Switch: -ansicolor

Enables or disables interpretation of ANSI color codes in inserted text. This feature requires Term::ANSIColor and was adapted from Tk::TextANSIColor by Jim Turner. Thank you for the contribution!

DESCRIPTION

Tk::Text::SuperText extends the standard Tk::Text widget with additional editing features. It can be used in the same way as Tk::Text. Its additional features include:

  • Unlimited undo/redo.

    Insertions and deletions can be undone and redone. The history is unlimited unless -undodepth or -redodepth sets a limit. To clear both history buffers, call:

    $w->resetUndo;

  • Rectangular selections.

    Rectangular text regions can be selected with the mouse or keyboard, then copied, deleted, or shifted.

  • Shifting selections left or right.

    Text selections can be shifted left or right by a character or a tab.

  • Normal and inline paste.

    For example, suppose the clipboard contains these two lines, each ending with a newline:

    line x
line y

    The text buffer contains:

    line 1
line 2

    Normal paste at the start of line 1 inserts the clipboard contents together:

    line x
line y
line 1
line 2

    Inline paste inserts each clipboard line at the same column on successive lines of the text buffer. At the start of line 1, the result is:

    line xline 1
line yline 2

    Include trailing spaces in the clipboard text if a separator is needed.

  • Parentheses matching.

    To help you inspect nested parentheses, brackets, and other characters, SuperText provides both automatic matching-pair highlighting and explicit matching commands. Automatic parenthesis matching is activated when you type or when you move the insertion cursor onto a parenthesis. It momentarily highlights the matching character if that character is visible in the window. To find a matching character anywhere in the buffer, position the cursor on a delimiter and call findMatchingChar. Use jumpToMatchingChar to move the cursor to its counterpart.

  • Auto-indenting.

    When you press the Return or Enter key, spaces and tabs are inserted to line up the insertion point with the first non-whitespace character of the previous line.

  • Inserting control codes.

    You can directly insert a non-printable control character in the text.

  • Commands are managed via virtual events.

    Editing and navigation commands are bound to virtual events. Use the Tk::event methods to generate these events or associate them with key sequences. Ordinary bindings can also be used.

    For example:

    $w->eventAdd('<<SelectAll>>', '<Control-a>');
$w->eventGenerate('<<SelectAll>>');

    To restore the default event bindings, call:

    $w->bindDefault;

  • Redefined default key bindings.

    Each virtual event has an associated public method with the same name, but with its first character in lowercase. For example, <<MouseSelect>> corresponds to $super_text->mouseSelect.

    Virtual Event/Command     Default Key Binding

MouseSetInsert            <Button-1>
MouseSelect               <B1-Motion>
MouseSelectWord           <Double-1>
MouseSelectLine           <Triple-1>
MouseSelectAdd            <Shift-1>
MouseSelectAddWord        <Double-Shift-1>
MouseSelectAddLine        <Triple-Shift-1>
MouseSelectAutoScan       <B1-Leave>
MouseSelectAutoScanStop   <B1-Enter>,<ButtonRelease-1>
MouseMoveInsert           <Alt-1>
MouseRectSelection        <Control-B1-Motion>
MouseMovePageTo           <2>
MouseMovePage             <B2-Motion>
MousePasteSelection       <ButtonRelease-2>

MoveLeft                  <Left>
SelectLeft                <Shift-Left>
SelectRectLeft            <Shift-Alt-Left>
MoveLeftWord              <Control-Left>
SelectLeftWord            <Shift-Control-Left>
MoveRight                 <Right>
SelectRight               <Shift-Right>
SelectRectRight           <Shift-Alt-Right>
MoveRightWord             <Control-Right>
SelectRightWord           <Shift-Control-Right>
MoveUp                    <Up>
SelectUp                  <Shift-Up>
SelectRectUp              <Shift-Alt-Up>
MoveUpParagraph           <Control-Up>
SelectUpParagraph         <Shift-Control-Up>
MoveDown                  <Down>
SelectDown                <Shift-Down>
SelectRectDown            <Shift-Alt-Down>
MoveDownParagraph         <Control-Down>
SelectDownParagraph       <Shift-Control-Down>
MoveLineStart             <Home>
SelectToLineStart         <Shift-Home>
MoveTextStart             <Control-Home>
SelectToTextStart         <Shift-Control-Home>
MoveLineEnd               <End>
SelectToLineEnd           <Shift-End>
MoveTextEnd               <Control-End>
SelectToTextEnd           <Shift-Control-End>
MovePageUp                <Prior>
SelectToPageUp            <Shift-Prior>
MovePageLeft              <Control-Prior>
MovePageDown              <Next>
SelectToPageDown          <Shift-Next>
MovePageRight             <Control-Next>
SetSelectionMark          <Control-space>,<Select>
SelectToMark              <Shift-Control-space>,<Shift-Select>

SelectAll                 <Control-a>
SelectionShiftLeft        <Control-comma>
SelectionShiftLeftTab     <Control-Alt-comma>
SelectionShiftRight       <Control-period>
SelectionShiftRightTab    <Control-Alt-period>

Ins                       <Insert>
Enter                     <Return>
AutoIndentEnter           <Control-Return>
NoAutoIndentEnter         <Shift-Return>
Del                       <Delete>
Backspace                 <BackSpace>
DeleteToWordStart         <Shift-BackSpace>
DeleteToWordEnd           <Shift-Delete>
DeleteToLineStart         <Alt-BackSpace>
DeleteToLineEnd           <Alt-Delete>
DeleteWord                <Control-BackSpace>
DeleteLine                <Control-Delete>

InsertControlCode         <Control-Escape>

FocusNext                 <Control-Tab>
FocusPrev                 <Shift-Control-Tab>

FlashMatchingChar         <Control-b>
RemoveMatch               <Control-B>
FindMatchingChar          <Control-j>
JumpToMatchingChar        <Control-p>

Escape                    <Escape>

Tab                       <Tab>

LeftTab                   <Shift-Tab>

Copy                      <Control-c>

Cut                       <Control-x>

Paste                     <Control-v>

InlinePaste               <Control-V>

Undo                      <Control-z>

Redo                      <Control-Z>

Destroy                   <Destroy>

MenuSelect                <Alt-KeyPress>

METHODS

The following editing and navigation methods correspond to the virtual events listed above:

$widget->mouseSetInsert;
$widget->mouseSelect;
$widget->mouseSelectWord;
$widget->mouseSelectLine;
$widget->mouseSelectAdd;
$widget->mouseSelectAddWord;
$widget->mouseSelectAddLine;
$widget->mouseSelectAutoScan;
$widget->mouseSelectAutoScanStop;
$widget->mouseMoveInsert;
$widget->mouseRectSelection;
$widget->mouseMovePageTo;
$widget->mouseMovePage;
$widget->mousePasteSelection;
$widget->moveLeft;
$widget->selectLeft;
$widget->selectRectLeft;
$widget->moveLeftWord;
$widget->selectLeftWord;
$widget->moveRight;
$widget->selectRight;
$widget->selectRectRight;
$widget->moveRightWord;
$widget->selectRightWord;
$widget->moveUp;
$widget->selectUp;
$widget->selectRectUp;
$widget->moveUpParagraph;
$widget->selectUpParagraph;
$widget->moveDown;
$widget->selectDown;
$widget->selectRectDown;
$widget->moveDownParagraph;
$widget->selectDownParagraph;
$widget->moveLineStart;
$widget->selectToLineStart;
$widget->moveTextStart;
$widget->selectToTextStart;
$widget->moveLineEnd;
$widget->selectToLineEnd;
$widget->moveTextEnd;
$widget->selectToTextEnd;
$widget->movePageUp;
$widget->selectToPageUp;
$widget->movePageLeft;
$widget->movePageDown;
$widget->selectToPageDown;
$widget->movePageRight;
$widget->setSelectionMark;
$widget->selectToMark;
$widget->selectAll;
$widget->selectionShiftLeft;
$widget->selectionShiftLeftTab;
$widget->selectionShiftRight;
$widget->selectionShiftRightTab;
$widget->ins;
$widget->enter;
$widget->autoIndentEnter;
$widget->noAutoIndentEnter;
$widget->del;
$widget->backSpace;
$widget->deleteToWordStart;
$widget->deleteToWordEnd;
$widget->deleteToLineStart;
$widget->deleteToLineEnd;
$widget->deleteWord;
$widget->deleteLine;
$widget->insertControlCode;
$widget->focusNext;
$widget->focusPrev;
$widget->flashMatchingChar;
$widget->removeMatch;
$widget->findMatchingChar;
$widget->jumpToMatchingChar;
$widget->escape;
$widget->tab;
$widget->leftTab;
$widget->copy;
$widget->cut;
$widget->paste;
$widget->inlinePaste;
$widget->undo;
$widget->redo;
$widget->destroy;
$widget->menuSelect;

readonly

$widget->readonly returns whether interactive editing is blocked. $widget->readonly($boolean) sets the mode, just like configuring -readonly, and returns the new value. Each widget has its own mode.

paste

$widget->paste inserts the clipboard contents at the insertion cursor using normal paste behavior. Use inlinePaste to insert successive clipboard lines at the same column on successive buffer lines. Both commands are blocked when -readonly is true.

tab

$widget->tab inserts a tab at the insertion cursor and keeps keyboard focus in the widget. This command is blocked when -readonly is true.

AUTHOR

The current maintainer is Alexander Becker, asb@cpan.org.

Originally written by Alessandro Iob.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Tk::Text Tk::ROText Tk::TextUndo

KEYWORDS

text, widget