jtext.tcl
The
jtext.tcl library is distributed as part of the
jstools package. It provides wrappers around the widget commands
that manipulate the contents of a text widget, building additional
functionality on top of them or making them more convenient to
use.
This document describes
jtext.tcl version 4.1/4.4.
Accessing the Library
In order to use the
jtext.tcl library, it (and any other libraries it depends on) must be
in your Tcl
auto_path, described in
tclvars(n). Information about how to arrange that, and other conventions
common to
the
jstools libraries, is in
the
Usage section of
The jstools Libraries.
Using jtext.tcl as an Interface to the Text Widget
The purpose of the
jtext.tcl library is as an interface to the text widget allowing additional
functionality to be built on top of its widget command. For
instance,
j:text:insert, along with the
jtexttags.tcl library, can support the notion of a set of `current tags'
automatically applied to newlyinserted text. My main goal
with this library is to use it to build a general undo facility,
allowing an arbitrary number of changes to a text widget to be
undone and redone by journaling changes to the text widget.
(This is not yet supported.) This means that it's very important
that if an application uses the
jtext.tcl procedures with a particular text widget,
all changes to that widget must be made through the
jtext.tcl procedures.
The
jtext.tcl library also keeps track of the state of the text widget -
whether it's `clean' or `dirty'. This will only be accurate
if all your accesses to the widget are through the
jtext.tcl library.
(Actions that don't affect the contents of the text widget in
any way, or that you don't care about being able to undo, don't
need to go through the library. For instance, there's no
j:text:get procedure, because there's no need to journal
pathname get commands.)
Author
Jay Sekora
js@aq.org
http://www.aq.org/~js/
Copyright
The library is copyright © 1992-1995 by Jay Sekora, but may be
freely redistributed under the conditions at the top of the file.
Procedures
j:text:insert - insert text into text widget at insert point
j:text:insert_string - deprecated alias for
j:text:insert
j:text:move - move insert mark in text widget to a particular position
j:text:delete - delete a range of characters in a text widget
j:text:replace - replace a range of characters in a text widget with a string
j:text:mark_dirty - specify that a text widget has been modified
j:text:mark_clean - specify that a text widget has been saved
j:text:is_dirty - true if a text widget has been modified since it was saved
j:text:has_selection - true if there is a selection in a text widget
j:text:insert_touches_selection - true if insert point touches or is in selection
j:text:tagged_insert - insert tagged sequences of text
j:text:find - search for patterns in a text widget
See Also
jtexttags.tcl
Usage
j:text:insert
w
text
Arguments
w is the text widget to insert into
text is the text to insert
Description
This procedure inserts
text into
w at
w's insert point.
If
w has been configured for use with the
jtexttags.tcl library (specifically, if a taglist has been set for it with
j:tag:set_tags, or
j:tag:set_tag), then the text will be inserted with
w's current tag list (and no other tags); see the
jtexttags.tcl documentation for more about this.
If
J_PREFS(typeover)is true - if the user has selected `Typing replaces selection'
on the
Global Preferences panel - then if (1) there is a selection in
w and (2) the insert point is within or adjacent to the selection,
the selection will be deleted and replaced by
text. (The requirement that the insert point be in or next to the
selection is so that the user can't inadvertently delete text
distant from the place in the document where sie's working, possibly
without realising it.)
Usage
j:text:move
t
index
Arguments
t is the text widget whose insert point is being changed
index is the new position of the insert point
Description
This procedure moved text widget
t's insert point to
index.
index can be in any of the legal forms for a text widget index;
see
text(n) for details.
If
w has been configured for use with the
jtexttags.tcl library (specifically, if a taglist has been set for it with
j:tag:set_tags, or
j:tag:set_tag), then
w's current tag list will be set based on the tags of the (new)
neighbouring characters; see the
jtexttags.tcl documentation for more about this.
Usage
j:text:delete
t
from
to
Arguments
t is the text widget whose insert point is being changed
from is the index of the first character in
t to delete
to is the index of the character after the last character in
t to delete
Description
This procedure deletes all characters in
t from
from, inclusive, to
to, exclusive. (I.e., the character at
from and any characters between
from and
to will be deleted, but the char at
to itself won't be.)
from and
to can be in any of the legal forms for a text widget index;
see
text(n) for details.
Usage
j:text:replace
t
from
to
string
Arguments
t is the text widget you want to replace text in
from is the index of the first character to replace
to is the index of the character after the last character to replace
string is the string to insert in
t in place of the range from
from to
to
Description
This procedure replaces a sequence of character in text widget
t with
string. After being inserted,
string will have all (and only) the tags that the character at
from had before the replacement. The insertion point is left
after
string.
Usage
j:text:mark_dirty
t
Argument
t is the text widget which has been changed
Description
This procedure marks the text widget
t as having been changed. It should be used after all actions
that modify the contents of the widget. It's intended for applications
such as editors, which need to know whether a document has been
modified since it was last saved.
All the
jtext.tcl procedures that modify text call this properly, so you should
never need to set it yourself.
Usage
j:text:mark_clean
t
Argument
t is the text widget which no longer has pending changes
Description
This procedure marks the text widget
t as
not having pending changes. Typically, this is used after an
application has saved the widget's contents into a file, or is
done with the widget. It's intended for applications such as
editors, which need to know whether a document has been modified
since it was last saved.
Usage
j:text:is_dirty
t
Argument
t is the text widget whose state you want to query
Description
This procedure returns true (1) if the text widget
t has pending changes (i.e., if its contents have been changed
since it was created or since it was last marked clean with
j:text:mark_clean). Otherwise it returns false (0).
Usage
j:text:has_selection
t
Argument
t is the text widget whose situation you want to query
Description
This procedure returns true (1) if there is currently a selection in text widget
t. Otherwise it returns false (0).
Usage
j:text:insert_touches_selection
t
Argument
t is the text widget whose situation you want to query
Description
This procedure returns true (1) if there is currently a selection in text widget
t and
t's insert point is within or next to the selection. Otherwise
it returns false (0).
j:text:tagged_insert
Usage
j:text:tagged_insert
t
list
Arguments
t is the text widget the text is to be inserted into
list is a list of text ranges and the tags to apply to them, described
below
Example
j:text:tagged_insert $info {
{Warning:} {bold red}
{ can't open } {}
{errlog} {typewriter}
{ for writing.} {}
}
Description
This procedure is essentially a wrapper around the (Tk4.0 and
above) text widget
insert command. The
list argument contains pairs of strings and corresponding lists
of tags. Each string (evennumbered elements of
list) is inserted into
t, tagged with all the corresponding tags (the following oddnumbered
element of
list), and no others. In the example above, for instance, the string
Warning: is inserted into text widget
$info, and tagged with the
bold and
red tags. All text is inserted at the widget's
insert mark (and after insertion, the
insert mark is left after the newlyinserted text).
Usage
j:text:find
t
[options]
Argument
t is the text widget to search in
Options
-pattern
pattern
(default
{} - not really optional)
-tag
tag
(default
select)
-backwards
backwards
(default
0)
-regexp
regexp
(default
0)
-case
case
(default
1)
-wrap
wrap
(default
1)
Example
j:text:find $t -regexp 1 -pattern "^proc[ \t]"
# The following example shows the use of the return value.
# Note the importance of specifying "-wrap 0" in this case.
$t tag configure blue -background blue -foreground white
$t mark set insert 1.0
while {[j:text:find $t \
-wrap 0 -tag blue -case 0 -pattern blue]} {
;
}
Description
This procedure searches for
pattern, which can be either a string or a regular expression, in the
contents of text widget
t, returning
1 if the pattern is found, and
0 if it is not. The search will start at the current insert
point and progress forwards unless
backwards is true, in which case (surprise!) it will progress backwards.
Unless
wrap is false (0), the search will wrap around at the end (beginning for a backwards
search) of the widget.
If a match is found, the text that matches has the tag
tag applied to it, and the insert point is moved to the end (beginning
for a backwards search) of the matching text. If
tag is
sel (the default), the text widget's selection (if any) will first
be cleared, so you don't end up with multiple ranges in a widget
tagged with
sel. (There's no problem with multiple ranges of other tags.)
If
regexp is
1, then
pattern is a regular expression and matching will follow the rules
described in Tcl's
regexp(n) man page. If it is
0 (the default), ordinary literal string matching is performed.
In either case, the search will be casesensitive if
case is
1 (the default); caseinsensitive if it is specified as
0.
This procedure uses the Tk text widget's
find method. Because the text widget performs searches linebyline,
search patterns can't span lines. I hope to work around this
in future versions. Because versions of Tk earlier than 4.0
don't provide the text widget
find method, this procedure doesn't work under Tk 3.6 or earlier.
Bugs and Misfeatures
- The interaction of
j:text:insert with
J_PREFS(typeover) is for the benefit of keyboard bindings and other changes based
on user actions. It's not appropriate for other uses. There
should really be a bindingsspecific version of
j:text:insert (perhaps
j:text:type?) and a generic one.
- The
j:text:find procedure can't search for anything that spans lines. That
means you can't (for instance) easily convert multiple contiguous
blank lines to a single blank line.
Future Directions
- As mentioned above in
Usage, I hope to implement a generalised undo facility in this library.