/ 
etext-2.01
/ Tk::eText

NAME

Tk::eText - a Tk text widget with nestable "blocks" (editable formulas)

SYNOPSIS

use Tk;
use Tk::eText;

my $mw   = MainWindow->new;
my $text = $mw->ScrleText(-wrap => 'word')->pack(-expand => 1, -fill => 'both');

$text->blockConfigure('Fraction', -layoutcmd => \&fraction_layout);
$text->insert('end', "A fraction: ");
$text->blockInsert('end', 'Fraction', "numerator\ndenominator");

DESCRIPTION

Tk::eText is a drop-in replacement for Tk::Text (it inherits all of its Perl-level bindings and methods) which adds one more kind of text annotation to tags, marks and embedded windows: the block.

Blocks have an internal structure (they contain lines of text, which in turn may contain nested blocks), nest arbitrarily, and perform geometry management over their contents. The geometry management is governed by a Perl callback (the -layoutcmd of the block type), which makes it possible to typeset -- and edit in place -- things like fractions, super- and subscripts, radicals, labeled equations, tables, etc. All the usual editing commands work on blocks.

The widget command additionally supports the block subcommand (available as the blockXxx methods) and an "object-oriented dump" (blockList), which returns the contents of a range as a list of strings and blessed objects (Tk::Text::Block, Tk::Text::TagOn, ...).

The complete documentation of the widget, of blocks and of the -layoutcmd protocol is in doc/etext.pod of this distribution (source repository: https://github.com/ilyaz-ai/etext); a large demo (with TeX import/export) is in demo/etext.pl.

HISTORY

The C part of this widget is the tk4.0b3 text widget as modified by Ilya Zakharevich in 1995-1997 (etext 0.4 ... 1.6.2 on CPAN), which was written against the Perl/Tk b9 "portable Tk" layer. Version 2.00 (2026, never released) is the same widget code ported to the API of Perl/Tk 804 and Perl 5.38, built as an ordinary standalone extension; 2.01 is the first release of the modernized distribution.

The features that the Tk text widget acquired after tk4.0 were added in version 2.00: indices count characters (the text is UTF-8), the edit (undo/redo, modified flag) and image (embedded images) subcommands and the -elide tag option exist and work inside blocks, the display and any index modifiers of Tk 8.5 are understood (display lines, display linestart and display lineend included), the cursor keys skip elided text, and the widget binds the <<Undo>> and <<Redo>> virtual events (Control-z and friends) to editUndo and editRedo. Note that edit undo undoes here, while in Perl/Tk's own Tk::Text it never has anything to undo (that widget's undo is Tk::TextUndo, written in Perl). search -regexp is handled by Perl's regexp engine.

Differences from Tk::Text: undoing a deletion re-creates the blocks, tags, marks, embedded images and embedded windows that were in the range, the blocks the deletion cut included (Tk re-creates none of these; a window given with -window was destroyed with the deletion and comes back as an empty window segment, one with -create is created again when displayed); dump looks into blocks and reports block and blockend elements (the -block switch); +N lines keeps the character position where Tk keeps the byte offset; search -nocase leaves alone the few characters whose lower-case form has another UTF-8 length; the insertion cursor skips elided text (Left, Right, Home, End and the word keys step by display indices, as in Tk 8.5). Display lines never span logical lines: a line whose newline is elided still ends a display line, and an entirely elided line is a display line of no height, where Tk 8.5 merges such lines with the next one; display lines passes over the elided lines and stops at the last display line of the text, and the widget wraps as Tk 8.4 does (a space at the right margin needs a pixel of room, Tk 8.5 lets it hang over). The object-oriented dump (blockList) reports embedded images as Tk::Text::EmbImage objects, and lists the options of embedded images and windows after their names (see doc/etext.pod).

SEE ALSO

Tk::Text, doc/etext.pod in the distribution.

AUTHOR

Ilya Zakharevich.