<!-- $Id$ -->
<HTML><HEAD>
<CENTER><TITLE>etext</TITLE>
</HEAD>
<BODY></CENTER><p><hr>
<H1>
<A NAME="etext_name_0">
NAME</A>
</H1>
textblocks - additional text widget subcommand for Tk distribution.
<p><p><hr>
<H1>
<A NAME="etext_synopsis_0">
SYNOPSIS</A>
</H1>
<XMP>
.widgetName block subcommand ?opt opt ...?
.widgetName configure -getFlags integer
</XMP>
<p>
<H2>
<A NAME="etext_what_0">
What else is in the widget?</A>
</H2>
The other difference with the stock Text widget is the object oriented
dump. It dumps a list of objects which represent the contents of the
widget in the given range. The temporary position for this command is
<p>
<XMP>
.widget block list from to
</XMP>
<p>An object is a real object in Perl, and a list with a first element
being the <EM>class id</EM> in TCL (the rest being the contests, in what
follows the first element of the rest is referenced as the first
element of the object).
<p>The particular elements of the list represent:
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_string_0">
String</A>
</STRONG>
<DD>
An object with contents being the string. Object class is
<CODE>Tk::Text::String</CODE>, <EM>class id</EM> is <CODE>S</CODE>.
<p>
<DT><STRONG>
<A NAME="etext_marks_0">
Marks</A>
</STRONG>
<DD>
The contents is the name of the mark, the classes are
<CODE>Tk::Text::MarkLeft</CODE> with <EM>id</EM> <CODE>L</CODE>, and <CODE>Tk::Text::MarkRight</CODE> with
<EM>id</EM> <CODE>R</CODE>.
<p>
<DT><STRONG>
<A NAME="etext_tags_0">
Tags</A>
</STRONG>
<DD>
The contents is the name of the tag, the classes are
<CODE>Tk::Text::TagOn</CODE> with <EM>id</EM> <CODE>T</CODE>, and <CODE>Tk::Text::TagOff</CODE> with
<EM>id</EM> <CODE>t</CODE>.
<p>
<DT><STRONG>
<A NAME="etext_window_0">
Window</A>
</STRONG>
<DD>
The contents is a list of the name of the window and the script to
create the window, the class is <CODE>Tk::Text::EmbWin</CODE> with <EM>id</EM> <CODE>W</CODE>.
<p>
<DT><STRONG>
<A NAME="etext_block_0">
block</A>
</STRONG>
<DD>
A block is dumped as a list of
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_type_0">
type</A>
</STRONG>
<DD>
The first element is a list of
<A HREF="etext.html#etext_block_0">block name</A>
, <EM>depth</EM> and (optionally)
<EM>instance data</EM>.
<p>
<DT><STRONG>
<A NAME="etext_contents_0">
contents</A>
</STRONG>
<DD>
The rest of the list represents the contents of the block in the same
form as the top-level dump, with exception for inter-leaf separators.
<p>The inter-leaf separators are dumped as on object of class
<CODE>Tk::Text::BlockSeparator</CODE>, with <EM>id</EM> <CODE>|</CODE>, the contents being the
``depth'' of the separator. Note that the minimal possible depth is 1
for separators between leaves of the same parent.
<p>
</DL>
The object class in Perl is <CODE>Tk::Text::Block</CODE>, the <EM>class id</EM> is<CODE>B</CODE>.
<p>
<DT><STRONG>
<A NAME="etext_empty_0">
Empty</A>
</STRONG>
<DD>
An empty block is dumped in the same way with the object class being
<CODE>Tk::Text::Empty</CODE>, the <EM>class id</EM> being <CODE>E</CODE>. The contenst is the
list of the block name, and (optionally) <EM>instance data</EM>.
<p>
</DL>
<H2>
<A NAME="etext_what_1">
What is a block?</A>
</H2>
A Block is an additional editable unit of information for inclusion
into widget. Block consists of
<A HREF="etext.html#etext_block_0">block type</A>
,
<A HREF="etext.html#etext_block_0">block contents</A>
, and,
possibly,
<A HREF="etext.html#etext_block_0">block instance data</A>
.
<A HREF="etext.html#etext_block_1">Block contents</A>
is a tree whose
leaves can contain anything that can be in a row in a text widget
(including other blocks).
<A HREF="etext.html#etext_block_1">Block instance data</A>
can be arbitrary data
as in a language variable.
<p>I<Current implementation allows only trees with the distance from root
to leaves being the same for all the leaves.>
<p>
<H2>
<A NAME="etext_examples_0">
Examples of blocks</A>
</H2>
Here we provide several examples on the internal structure of blocks
that can implement the following objects. To see how the internal
structure (does not) correlate with the visual appearance, see
<A HREF="etext.html#etext_display_0"><EM>Display of blocks</EM></A>
.
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_button_0">
Button</A>
</STRONG>
<DD>
<XMP>
___ Text to show when released
/
\___ Text to show when pressed
</XMP>
<p>
<DT><STRONG>
<EM>Multilevel sub-super-script</EM>
</STRONG>
<DD>
<XMP>
__ First superscript
/
/\__ Second superscript
/
\ __ First subscript
\ /
\/___ Second subscript
\
\__ Third subscript
</XMP>
<p>
<DT><STRONG>
<A NAME="etext_radical_0">
Radical</A>
</STRONG>
<DD>
<XMP>
___ Text to show inside
</XMP>
<p>
<DT><STRONG>
<A NAME="etext_tabulation_0">
Tabulation</A>
</STRONG>
<DD>
<XMP>
(Empty)
</XMP>
<p>
</DL>
<H2>
<A NAME="etext_indices_0">
Indices in blocks</A>
</H2>
A block occupies the following place in the index space: 1 index unit
for the start of the block, then all the leaves separated by 1 index
separators, and 1 index for the end of the block. Thus a block with
one empty leaf occupies 2 index units.
<p>An <EM>empty</EM> block (without leaves) occupies 1 unit of the index space.
<p>Note that a block (however complicated) always fits in one line of the
index space. In particular, the usual bindings for <CODE>up</CODE> and <CODE>down</CODE>
will move you out of a block. (You should expect it, since leaves of a
block <EM>may</EM> be placed one under another, but may be not.)
<p>
<H2>
<A NAME="etext_string_1">
String representation of blocks</A>
</H2>
The commands that convert block contents to string (<CODE>.t get</CODE>,
selection and search) see the contents of a block as a string of the
same size as the size of block in the index space. The start of the
block looks like <CODE>{</CODE>, end like <CODE>}</CODE>, interleaf separators like <CODE>|</CODE>.
<p>An <EM>empty</EM> block looks like <CODE>.</CODE>.
<p>Note that a string representation of a block (however complicated)
always fits in one line.
<p>
<H2>
<A NAME="etext_insertion_0">
Insertion in blocks</A>
</H2>
Insertion changes contents of the block if the insertion point is
inside the block, i.e.,
after starting index of the block and before the ending position (and
not inside some other block contained in the given one). Note that it
is impossible to be inside an empty block.
<p>If inserted text contains no newlines, it is added to the leaf of tree
the insertion point is in (i.e., at or after the start of, and before
the end of). If it contains newlines, then the resulting leaf is split
into several at the inserted newlines. All the new leaves have the
same parent node as the initial leaf. Registered callback will be
called on insertion of newlines <EM>(not implemented)</EM>.
<p>
<H2>
<A NAME="etext_destruction_0">
Destruction of blocks</A>
</H2>
When the block is destructed, it contents is merged into the
surrounding environment. Block's head and tail disappear, interleaf
separators behave like newlines. I.e., if block was contained in
another block, interleaf separators of deceased block became interleaf
separators of the parent block, otherwise they became line separators
in the text widget.
<p>
<H2>
<A NAME="etext_deletion_0">
Deletion of text in blocks</A>
</H2>
<p>
<UL>
<LI>If the deletion range does not include any index unit occupied by the
block, the block does not change.
<p>
<LI>If a range contains a block as a whole, block is deleted. Registered
callback will be called <EM>(not implemented)</EM>. Same happens if the
range contains all the block except either head or tail index.
<p>
<LI>Otherwise, if the range includes head or tail of the block, the block is
destroyed, and what remains of the contents is merged into enclosing
structure as is described in
<A HREF="etext.html#etext_destruction_0"><EM>Destruction of blocks</EM></A>
.
<p>
<LI>If a range is completely contained inside some leaf, the inner
structure of the block does not change (but if a leaf becomes empty,
registered callback will be called <EM>(not implemented)</EM>).
<p>
<LI>If the range contains leaves separators, two survived leaves are
merged together. If their parents were different, they are also merged
together, and the process continues until the common parent is
met. This is exact opposite to the
<A HREF="etext.html#etext_block_0">block split ??</A>
subcommand that
would create this separator. Registered callbacks are called I<(not
implemented)>.
<p>
</UL>
<H2>
<A NAME="etext_tags_1">
Tags and blocks</A>
</H2>
Characters inside leaves can be tagged in the usual way. Interleaf
separators and tail of the block behave like end-of-lines when
tagged. The behaviour of tags on the start of block is undefined.
<p>
<H2>
<A NAME="etext_bounding_0">
Bounding boxes</A>
</H2>
<p>
<UL>
<LI>If index in the text corresponds to a character in a leaf of a block,
it behaves as usual.
<p>
<LI>If the index corresponds to the interleaf separator or tail of a
block, the bounding box of the preceeding leaf is returned.
<p>
<LI>If the index corresponds to the head of the block, the bounding box
for the whole block is returned.
<p>
</UL>
Bounding box for anything <EM>invisible</EM> is of size 0 and at theupper-left corner of the block.
<p><p><hr>
<H1>
<A NAME="etext_display_0">
Display of blocks</A>
</H1>
The display of blocks is completely customizable. It is based on the
current configuration of the
<A HREF="etext.html#etext_type_0">type</A>
of displayed block.
<p>
<UL>
<LI>If no customization is registered for the block, then the tree
structure is ignored, all the leaves are drawn on the display one
under another, left justified, with wrap enabled, and the resulting
object is vertically centered about the middle of the ascent of the
default font. In what follows we refer to this behavior as <EM>default layout</EM>.
<p>
<LI>If the block registers a layout callback, it will be called when the
block is about to be drawn. This procedure takes the information on
the size the leaves take on the display, and returns information on
what size the block takes on the display and what should be relative
offsets of leaves in the resulting rectangle. I<Details are subject to
change.> No clipping is performed.
<p>
<LI>Layout callback can also specify which leaves <EM>should not</EM> be shown
at all, and what additional details to show in the rectangle.
<p>
<LI>* <EM>(Not implemented)</EM>
Block can also specify that some leaves have some additional tags.
<p>
</UL>
<p><hr>
<H1>
<A NAME="etext_layout_0">
Layout callback</A>
</H1>
Layout callback is the main component of the block.
<p><EM>Details are subject to change.</EM>
<p>A layout procedure takes a variable number of <EM>input arguments</EM>. The
<EM>first element</EM>
is a list containing the block name and widget name, (possibly with an
addition, say, if <EM>instance data</EM> is present in the block, it will be
the next element). The <EM>second element</EM> gives the horizontal offset of the start
of the block inside the ambient line (it can be different from the
absolute horizontal position if the block is inside some other
block). The <EM>remaining elements</EM> specify the tree structure of the block and the
layout details of the leaves. Any child of the root node of the tree
provides one argument of the function. All the arguments are lists,
and
<p>
<UL>
<LI>if the child is a leaf, then the list consists of the <EM>repeat count</EM>
(necessarily 1), current <CODE>y</CODE> offset inside the block, width, I<total
width>, height, baseline, and some additional data on the leaf I<(last
part is not implemented, but it will contain horizontal stretchability
of the leaf, vertical one and stretchability of the baseline)>.
<p>
<LI>If the child is a node, the list elements are themselves lists that
are obtained using the same rules recursively: if children are leaves,
the elements are lists of numbers, otherwise lists of lists.
<p>
<LI>If block is configured to lie to the layout procedure about its contents, it
can present several lines or a whole subtree of itself in the same
form as a single leaf. In this case the <EM>repeat count</EM> above can be
bigger than 1.
<p>
</UL>
<STRONG>Summary:</STRONG>
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_input_0">
Input arguments:</A>
</STRONG>
<DD>
<XMP>
{bname wname ...} ho {rc yo w tw h b hs vs bs} ...
</XMP>
<p>
<DT><STRONG>
<A NAME="etext_abbreviations_0">
Abbreviations:</A>
</STRONG>
<DD>
BlockNAME, WidgetNAME, Horizontal Offset, Repeat Count, Y Offset,
Width, Total Width, Baseline. hs, vs, bs are currently not used.
<p>
</DL>
The return value of the callback must be a list. The length of thelist (counting multiplicities, see below) must be at least the number of
leaves plus one. The first element of the list specifies the layout
information on the block as a whole, the others specify layout
information for the leaves and (possibly) additional elements to show.
<p>There are three possible formats of the elements in this list. All
are lists of numbers (and should be of the form <CODE>{dd ... dd}</CODE>)
of lengths 1, 7, or 13. The first number is either <EM>repeat count</EM>, or
<EM>id</EM> of additional line to show (i.e., the same data as returned by
<CODE>textWidget block addline index</CODE> command). Lists of different length have
the following meaning:
<p>
<OL>
<LI>the child is not shown at all. This format is prohibited for the
layout information of the block as a whole and for additional
lines. The only element of the list is the <EM>repeat count</EM>.
<p>
<LI>If the block as a whole is not laid out yet, this is the information
about it, and all the elements but what describe width,
height and baseline are ignored. If not all the leaves are laid out
yet, the first element is the <EM>repeat count</EM>, what means the number
of leaves that are described by this list (it can be 0).
<p>The remaining elements of the list provide x and y offsets of
the upper-left corner inside the ambient block, width, <EM>total width</EM>,
height, and baseline of the block as a whole, or of a group of leaves,
or a leaf. If it describes a group of leaves, the leaves are laid out
as by default layout procedure. Width, height, and baseline
information is used for displaying background of the line.
<p>If all the leaves are laid out, then this list describes an additional
element to draw if the first element is greater than 0, i.e. it is
considered a
<A HREF="etext.html#etext_block_1">Block ID</A>
of an additional drawing element, and the
rest specifies the layout of this element. If it is 0, then this
element of the list is ignored exactly as in other cases.
<p>
<LI><EM>(not implemented, but accepted by the widget):</EM> the first 7 elements
have the same meaning as above, the last 6 provide stretchability
x and y position of upper-left corner, width, <EM>total width</EM>, height,
and baseline.
<p>
</OL>
The <EM>total width</EM> above is the width of the leaf including the spacereserved for showing the background of the leaf terminator.
<p><STRONG>Summary:</STRONG>
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_return_0">
Return list elements:</A>
</STRONG>
<DD>
<XMP>
{Block Layout} {Leaf0 Layout} ...
{Leafn Layout} {Additional Element0 Layout} ...
{Additional Elementn Layout}
</XMP>
<p>
<DT><STRONG>
<A NAME="etext_layout_1">
Layout Styles</A>
</STRONG>
<DD>
<p>
<DL COMPACT>
<DT><STRONG>
Block Layout - <CODE>{ig ig ig w ig h b}</CODE>
</STRONG>
<DD>
<p>
<DT><STRONG>
Show one or more leaves - <CODE>{rc xo yo w tw h b}</CODE>
</STRONG>
<DD>
<p>
<DT><STRONG>
Hide one or more leaves - <CODE>{rc}</CODE>
</STRONG>
<DD>
<p>
<DT><STRONG>
Show Additional Elements - <CODE>{bi xo yo w tw h b}</CODE>
</STRONG>
<DD>
(<CODE>w</CODE> is not very important), put after leaves.
<p>
</DL>
<DT><STRONG>
<A NAME="etext_abbreviations_0">
Abbreviations:</A>
</STRONG>
<DD>
IGnored, Width, Total Width, Height, Baseline, XOffset, YOffset,
Repeat Count, Block Id
<p>
</DL>
None of the returned date is used for clipping. However, it is used indirecting the mouse events and reporting bounding boxes.
<p>
<H2>
<A NAME="etext_lying_0">
Lying to layout callback</A>
</H2>
It is possible to configure a block to lie about its structure to the
layout callback. This can greatly simplify writing the callback in
interpreted languages, if the default layout procedure is satisfactory for
<EM>parts</EM> of a block.
<p>Setting the <CODE>-layoutdepth</CODE> and/or <CODE>-layoutwidths</CODE> options for a block
forces the layout procedure to be called with agruments corresponding
to modified tree structure.
<p>If <CODE>-layoutdepth</CODE> is set, the depth of the tree is modified to be the
given number. If the true depth of the tree is too small, tree is
extended from the root side, if it too deep, the subtrees on the
maximal allowed depth level are mocked as lines with <EM>repeat count</EM>.
<p>If <CODE>-layoutwidths</CODE> is set, this can restrict the number of branches
going out of any node of the modified tree. The value of this option
should be a list, elements of this list are either numbers, or lists
of the form <CODE>{min max}</CODE>. (A single <CODE>number</CODE> is equivalent to a pair
<CODE>{number number}</CODE>). N-th element of the list controls the number of
branches going out of nodes on the distance N from the root. If there
are too few branches, it adds branches that contain simulated groups
of leaves with <EM>repeat count</EM> 0. If there are too many branches, it
groups several last brunches into one with appropriate I<repeat
count>. I<(Current implementation is buggy in interaction of
<CODE>-layoutwidths</CODE> and <CODE>-layoutdepth</CODE> if the depth of the node is less
than <CODE>-layoutdepth</CODE>.)>
<p><p><hr>
<H1>
<A NAME="etext_block_2">
Block subcommands</A>
</H1>
<p>
<DL COMPACT>
<DT><STRONG>
<A NAME="etext_configure_0">
configure</A>
<EM>blockName ?option value ... ?</EM>
</STRONG>
<DD>
Standard procedure for creating and configuring block type. Currently
supported configuration options are
<p>
<DL COMPACT>
<DT><STRONG>
<STRONG>-layoutcmd</STRONG>
</STRONG>
<DD>
Layout callback.
<p>
<DT><STRONG>
<STRONG>-layoutdepth</STRONG>
</STRONG>
<DD>
Depth of simulated tree for layout callback. Default -1.
<p>
<DT><STRONG>
<STRONG>-layoutwidths</STRONG>
</STRONG>
<DD>
List of widths of levels of simulated tree for layout
callback. Default <CODE>{}</CODE>.
<p>
<DT><STRONG>
<STRONG>-empty</STRONG>
</STRONG>
<DD>
Boolean value that specifies that the blocks of this type contain no
leaves (<EM>empty</EM> blocks).
<p>
</DL>
<DT><STRONG>
<A NAME="etext_cget_0">
cget</A>
</STRONG>
<DD>
Standard configuration get procedure.
<p>
<DT><STRONG>
<A NAME="etext_at_0">
at</A>
<EM>index</EM>
</STRONG>
<DD>
Returns information in the block that starts at the given index or
``nothing'' if there is no such block. Returned information is a list
consisting of block start index, block length in index space, block
name, block instance data, structure of the block. The latter is a
list (possibly of lists) with leaves being lengths of block leaves.
<p>
<DT><STRONG>
<A NAME="etext_of_0">
of</A>
<EM>index</EM>
</STRONG>
<DD>
Returns information in the innermost block that contains the given index or
empty list if there is no such block. See
<A HREF="etext.html#etext_at_0">at</A>
subcommand for
description of return value.
<p>
<DT><STRONG>
<A NAME="etext_delete_0">
delete</A>
<EM>blockName ?blockName ...?</EM>
</STRONG>
<DD>
Deletes the information on
<A HREF="etext.html#etext_block_0">block types</A>
. Error is returned if the
are blocks of the given types in the widget.
<p>
<DT><STRONG>
<A NAME="etext_insert_0">
insert</A>
<EM>blockName index1 ?index2?</EM>
</STRONG>
<DD>
Inserts block of the given type in the widget. The block contains one
node, and all the leaves are immediate children of this node. If
<EM>index2</EM> is not specified, creates a block with one empty leaf,
otherwise moves the contents of the widget between <EM>index1</EM> and
<EM>index2</EM> into the tree.
<p>In the latter case <EM>index1</EM> and <EM>index2</EM> should be outside of any
block, or properly inside the same block. The newlines (or,
correspondingly, interleaf separators of enclosing block) are
converted into interleaf separators of newly created block. This is
prohibited for <EM>empty</EM> blocks.
<p>
<DT><STRONG>
<A NAME="etext_names_0">
names</A>
</STRONG>
<DD>
Returns list of names of currently defined
<A HREF="etext.html#etext_block_0">block types</A>
.
<p>
<DT><STRONG>
<A NAME="etext_split_0">
split</A>
<EM>index ?level?</EM>
</STRONG>
<DD>
<p>
<UL>
<LI>If <EM>index</EM> is outside of blocks, inserts newline.
<p>
<LI>Otherwise, if
<EM>level</EM> is not specified, or is 0, is equivalent to insertion of
newline, i.e., splits the leaf into two with the same
parent.
<p>
<LI>If <EM>level</EM> is positive, splits the leaf in two and changes the
structure of the tree.
<p>
<UL>
<LI>If <EM>level</EM> is less than the distance from the leaf to the root,
splits the <EM>level</EM>th parent (and all the parents of less order) in
two. The beginning of the split leaf goes to one node, the rest
(together with the leafs in the same node after the splitted one) goes
to another. Example of
<A HREF="etext.html#etext_split_0">split 1</A>
follows (the leaf marked <STRONG>X</STRONG> is
split into two marked <STRONG>x</STRONG>):
<p><UL><LI> ___ ___</LI>
<LI> / __ / _</LI>
<LI> / / / /</LI>
<LI> .-------X .-------x</LI>
<LI> \ \__ \ \____x</LI>
<LI> \_____ \ \_</LI>
<LI> \____</LI>
</UL>
<p>
<LI>If <EM>level</EM> is too big to proceed with the above procedure, the tree is
extended to the left first. The added nodes have one child each.
<p>
</UL>
</UL>
<LI>
<A NAME="etext_trim_0">
trim</A>
<EM>index</EM>
If the block at index has only one edge coming from the root, and this
edge does not end in a leaf, deletes the root. The resulting tree will
be 1 level more shallow. Returns error if out of block or the above
conditions are not met.
<p>
<LI>
<A NAME="etext_data_0">
data</A>
<EM>index ?data?</EM>
Returns or sets <EM>instance data</EM> information for the block at <CODE>index</CODE>.
<p>
<LI>
<A NAME="etext_addline_0">
addline</A>
<EM>index</EM>
``Steals'' the displayed structure of the line starting at
<EM>index</EM>. Returns the <EM>id</EM> of the resulting element. This <EM>id</EM> can
be used in the return value of the layout callback to specify
additional elements used in drawing of the block. I<Beware that the
behaviour is undefined if the line contains something more complicated
than tagged characters.>
<p>
<LI>
<A NAME="etext_deletelines_0">
deletelines</A>
Deletes all the ``stolen'' lines.
<p>
<LI>
<A NAME="etext_list_0">
list</A>
<EM>from</EM> <EM>to</EM>
See
<A HREF="etext.html#etext_what_0"><EM>What else is in the widget?</EM></A>
.
<p>
</UL>
<p><hr>
<H1>
<A NAME="etext_additional_0">
Additional text widget options</A>
</H1>
<p>
<DL COMPACT>
<DT><STRONG>
<CODE>-getFlags</CODE>
</STRONG>
<DD>
The value is an integer, binary bits of this integer denote current
<EM>text representation</EM> options. If no bits are set, the operations
that consider text contents as a string behave like the standard Tk
text widget.
<p>If bit <CODE>1</CODE> is set, the string representation of a text range
<EM>always</EM> gives a string of the same length as the length of the
interval in the index space. If some text annotation results in an
empty string in the standard representation, it is represented as an
appropriate number of <CODE>*</CODE>s if this bit is set. Currently this
concerns embedded windows only, which are represented as <CODE>*</CODE>.
<p>All undocumented bits are reserved and should be 0.
<p>
</DL>
<p><hr>
<H1>
<A NAME="etext_minitutorial_0">
Minitutorial</A>
</H1>
<p>
<H2> <EM>Example of a simple ``pedestal'' block</EM></H2>
Suppose you are satisfied with the standard layout procedure, but want
to extend the resulting group of lines 10 points to the right (so when
part of block is selected, selection extends 10 points to the
right of the rightmost element in leaves), and want to add a blue
3D background of width 5 with ``height'' 2 around the resulting guy,
and draw the block on gray 3D background of width 2.
<p>Note that it is not enough to use a tag even for gray background,
since the border of the tag is inside the rectangle that contains the
letter, and to get a correct pedestal look we want the border to
surround the letter, not to be drawn outside of them.
<p>In what follows we use TCL as the language for callback. Of course,
the resulting code will be much simpler in some other languages.
<p>First, we create the 2 new additional elements to display:
<p>
<XMP>
.t tag configure backgr1 -background blue -border 2 -relief raised
.t tag configure backgr2 -background gray90 -border 2 -relief raised
.t insert 1.0 \n backgr1
set backgrId1 [.t block addline 1.0]
.t delete 1.0 1.0+1c
.t insert 1.0 \n backgr2
set backgrId2 [.t block addline 1.0]
.t delete 1.0 1.0+1c
</XMP>
<p>(or we could use existing ones, if possible). The third row creates a
row in the text widget that is empty, and has tag ``backgr1''. This row
will show the background only, and we will use it to show the raised
background behind the block. The fourth row memorizes the <EM>id</EM> of this
additional line, and the fifth one returns the text in the widget to
its initial state. The line is not shown anymore, but the way to show
it is preserved in a safe place. The second element is created in the
same way.
<p>Next, since we are satisfied with the way the leaves of the tree are
places on the screen (i.e., one under another), we do not want to be
concerned with internal structure of the block tree, so we ask the
widget to lie about internal structure of the tree:
<p>
<XMP>
.t block config myBlock -layoutdepth 1 \
-layoutwidths 1 -layoutcmd myLayoutCmd
</XMP>
<p>Now the data given to <CODE>myLayoutCmd</CODE> will be always the same, as if
the block consisted of one leaf only that is the direct child of the
root. So the arguments the <CODE>myLayoutCmd</CODE> receives are the following
ones:
<p>
<XMP>
proc myLayoutCmd {block x row} {
global backgrId1 backgrId2
set c [lindex $row 0]
set w [lindex $row 2]
set tw [lindex $row 3]
set h [lindex $row 4]
set b [lindex $row 5]
</XMP>
<p>Now <CODE><STRONG>$c</STRONG></CODE>, <CODE><STRONG>$w</STRONG></CODE>, <CODE><STRONG>$tw</STRONG></CODE>, <CODE><STRONG>$h</STRONG></CODE>, <CODE><STRONG>$b</STRONG></CODE> contain the count, width,
<EM>total width</EM>, height and baseline of the contents of the block.
Next we extend the <EM>total width</EM> of the row.
<p>
<XMP>
set tw [expr $tw+10]
set tw2 [expr $tw+4]
set tw1 [expr $tw+10]
</XMP>
<p>We will not replace the width of the row, so mouse events could be
directed to outside of the block if clicked in the extended area. (In
fact they won't, since we will extend the size of the ambient block.)
Next we calculated widths of additonal rows,
<p>
<XMP>
set h2 [expr $h+4]
set h1 [expr $h+10]
set b2 [expr $b+2]
set b1 [expr $b+5]
</XMP>
<p>and their height and baselines. All is prepared now to layout the rows:
<p>
<XMP>
set addrow1 [list $backgrId1 0 0 $tw1 $tw1 $h1 $b1]
set addrow2 [list $backgrId2 3 3 $tw2 $tw2 $h2 $b2]
</XMP>
<p>Note that the same list <STRONG>$addrow1</STRONG> is good for specifying the size of the
total block, since the first element of the list (that is <STRONG>$backgrId</STRONG>)
is ignored in the information for the whole block. Now we need to
move the real contents of the block 5 points to the right and down
with respect to the rectangle occupied by the
block, and return the calculated information:
<p>
<XMP>
set row [list $c 5 5 $w $tw $h $b]
return [list $addrow1 $row $addrow1 $addrow2]
}
</XMP>
<p>Note that it is vital to put addrow2 after addrow1, since it should be
drawn after the addrow1 for it to appear to be on top of addrow1.
<p>That's all! Now you can create a binding for insertion of empty block
into the widget (this binding supposes that <CODE>bindtags</CODE> are reverted):
<p>
<XMP>
bind .text <Control-Meta-m> {
%W block insert myBlock insert
%W mark set index index-1c
break
}
</XMP>
<p>This binding moves the insertion point inside the block, so you are
ready to fill block with whatever information you need.
<p>Sample code in the distribution of extended text widget
provides other examples of blocks: superSub, Fraction, and so on.
<p>
<H2> <EM>Example of a simple ``tabulation'' block</EM></H2>
Here we describe how to code blocks that contain no editable
information, but provide geometry management. Consider an example of
tabulation: if we implement tabulation as a block, the size of this
block should change depending on the position of the start, but the
only editing operation should be the deletion of the block as a whole.
<p>While it is possible to implement this kind of block using the same
types of blocks as in the previous section, we will need a lot of code
change in the bindings if we use this approach: a usual block takes at
least 2 positions in the index space, so it is possible to make an
insertion inside this block. Thus we either need correction of
keybindings that move the insertion point, or should correct the the
insertion code to check whether the insertion happens inside a block
of this type. If we do not do this, we need additional decision how to
handle blocks of this type that have not-empty contents.
<p>The solution is to use ``empty'' blocks that take only 1 position in the
index space, so it is impossible to insert text inside them. We make
block type empty by using configuration option <CODE>-empty</CODE>:
<p>
<XMP>
.t block configure Tab -empty on -layoutcmd {layoutTab 5 35}
</XMP>
<p>Note the spaces in the name of layoutcmd: No quoting is performed
during the call, so <CODE>5</CODE> and <CODE>35</CODE> become first two arguments of
<CODE>layoutTab</CODE> procedure. This procedure can be as simple as follows:
<p>
<XMP>
proc layoutTab {min mult block x} {
global backgrId2
set w [expr $min + $mult - ($x + $min - 1) % $mult - 1]
set totblock [list $backgrId2 0 0 $w $w 5 3]
return [list $totblock $totblock]
}
</XMP>
<p>The only ``working'' row is the <CODE>set w</CODE> one. It calculates the width
of the block using the following rule:
<p>
<DL COMPACT>
<DT><STRONG>
the width is at least <STRONG>$min</STRONG>, and the right end is on the position that
</STRONG>
<DD>
is proportional to <STRONG>$mult</STRONG> counting from the left of the line.
<p>
</DL>
The last row returns a list of length 2. The first element is thedescription of the block as a whole, the next one is necesssarily the
description of an additional element (since there are no ``regular''
leaves in the tree). This additional element is the same size as the
block itself, and is used only to provide some visual feedback. We use
<EM>id</EM> <STRONG>$backgrId2</STRONG> created elsewhere (say, by the code in the previous
example), and ask for the rectangle to be 3 points above the baseline,
and 2 points below.
<p><p><hr>
<H1>
<A NAME="etext_author_0">
AUTHOR</A>
</H1>
Ilya Zakharevich <<A HREF="MAILTO:ilya@math.ohio-state.edu">ilya@math.ohio-state.edu</A>>
<p><p><hr>
<H1>
<A NAME="etext_availability_0">
AVAILABILITY</A>
</H1>
<A HREF="L<ftp://ftp.math.ohio-state.edu/pub/users/ilya>">L<ftp://ftp.math.ohio-state.edu/pub/users/ilya></A>.
<p>
</BODY>
</HTML>