{jtext.tcl

Introduction
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

This document describes jtext.tcl version 4.0/4.0.

Usage
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 the it's widget command.  For instance, j:text:insert_string, along with the jtexttags.tcl library, can support the notion of a set of `current tags' automatically applied to newly­inserted 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.)

Credits and Copyright
Author
Jay Sekora 
js@calumet.org
http://shore.net/~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.

Overview
Procedures
j:text:insert_string - insert text into text widget at insert point
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

See Also
	jtexttags.tcl

j:text:insert_string
Usage
	j:text:insert_string 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 tag­list 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.)

j:text:move
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.

j:text:delete
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.

j:text:replace
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.

j:text:mark_dirty
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.

j:text:mark_clean
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.

j:text:is_dirty
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).

j:text:has_selection
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).

j:text:insert_touches_selection
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).

Bugs and Misfeatures
* The interaction of j:text:insert_string 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 bindings­specific version of j:text:insert_string (perhaps j:text:type?) and a generic one.

Future Directions
* As mentioned above in Usage, I hope to implement a generalised undo facility in this library.
} {{{jdoc:xref:link {4.52 4.59 10.210 10.231 10.239 10.256 10.260 10.281 13.208 13.221 30.0 30.20 31.0 31.11 32.0 32.13 33.0 33.14 34.0 34.17 35.0 35.17 36.0 36.15 37.0 37.20 38.0 38.31 41.1 41.14 53.42 53.55 53.118 53.132 53.137 53.150 55.90 55.108 117.174 117.191}} {jdoc:xref:manpage {10.126 10.133 65.129 65.133 76.281 76.285}} {jdoc:anchor:anchorname {3.0 4.0 8.0 9.0 19.0 20.0 28.0 29.0 43.0 44.0 57.0 58.0 67.0 68.0 78.0 79.0 90.0 91.0 101.0 102.0 110.0 111.0 119.0 120.0 128.0 129.0}} {richtext:font:roman {2.0 3.0 4.0 4.4 4.13 4.52 4.59 6.24 6.33 8.0 10.0 10.20 10.29 10.102 10.111 10.126 10.133 10.214 10.221 10.243 10.248 10.260 10.281 12.0 13.0 13.19 13.28 13.171 13.191 13.208 13.221 13.628 13.637 13.680 13.683 13.732 13.741 15.4 15.13 15.185 15.194 17.184 17.194 17.241 17.253 19.0 21.0 22.0 22.14 23.0 23.21 25.0 26.0 28.0 30.20 31.0 31.11 32.0 32.13 33.0 33.14 34.0 34.17 35.0 35.17 36.0 36.15 37.0 37.20 38.0 38.31 40.0 41.0 41.1 41.14 43.0 45.0 45.1 45.28 46.0 47.0 47.1 47.2 48.1 48.5 50.0 51.0 51.23 51.27 51.33 51.34 51.38 51.39 53.3 53.4 53.42 53.55 53.118 53.132 53.137 53.150 53.189 53.190 53.239 53.252 55.3 55.20 55.153 55.154 55.266 55.270 57.0 59.0 59.1 59.20 60.0 61.0 61.1 61.2 62.1 62.6 64.0 65.0 65.33 65.34 65.53 65.58 65.61 65.66 65.129 65.133 67.0 69.0 69.1 69.24 70.0 71.0 71.1 71.2 72.1 72.5 72.45 72.46 73.1 73.3 73.62 73.63 75.0 76.0 76.41 76.42 76.48 76.52 76.68 76.70 76.108 76.112 76.140 76.144 76.149 76.151 76.185 76.187 76.207 76.211 76.216 76.218 76.281 76.285 77.0 80.0 80.1 80.32 81.0 82.0 82.1 82.2 83.1 83.5 84.1 84.3 85.1 85.7 85.35 85.36 85.64 85.68 85.72 85.74 87.0 88.0 88.63 88.64 88.70 88.76 88.101 88.107 88.164 88.168 88.232 88.238 90.0 92.0 92.1 92.20 93.0 94.0 94.1 94.2 96.0 97.0 97.37 97.38 99.8 99.17 101.0 103.0 103.1 103.20 104.0 105.0 105.1 105.2 107.0 108.0 108.37 108.38 108.42 108.45 110.0 112.0 112.1 112.18 113.0 114.0 114.1 114.2 116.0 117.0 117.29 117.30 117.51 117.52 117.174 117.191 119.0 121.0 121.1 121.23 122.0 123.0 123.1 123.2 125.0 126.0 126.29 126.30 126.81 126.82 128.0 130.0 130.1 130.34 131.0 132.0 132.1 132.2 134.0 135.0 135.29 135.30 135.81 135.82 135.87 135.88 137.0 138.0 138.21 138.41 138.47 138.64 138.239 138.259 138.269 138.280 140.0 141.0 141.24 141.29 142.0}} {richtext:font:italic {13.680 13.683 17.241 17.249 45.22 45.23 45.24 45.28 47.1 47.2 48.1 48.5 51.23 51.27 51.33 51.34 51.38 51.39 53.3 53.4 53.189 53.190 55.153 55.154 55.266 55.270 59.13 59.14 59.15 59.20 61.1 61.2 62.1 62.6 65.33 65.34 65.53 65.58 65.61 65.66 69.15 69.16 69.17 69.21 69.22 69.24 71.1 71.2 72.1 72.5 72.45 72.46 73.1 73.3 73.62 73.63 76.41 76.42 76.48 76.52 76.68 76.70 76.108 76.112 76.140 76.144 76.149 76.151 76.185 76.187 76.207 76.211 76.216 76.218 80.16 80.17 80.18 80.22 80.23 80.25 80.26 80.32 82.1 82.2 83.1 83.5 84.1 84.3 85.1 85.7 85.35 85.36 85.64 85.68 85.72 85.74 88.63 88.64 88.70 88.76 88.101 88.107 88.164 88.168 88.232 88.238 92.19 92.20 94.1 94.2 97.37 97.38 103.19 103.20 105.1 105.2 108.37 108.38 108.42 108.45 112.17 112.18 114.1 114.2 117.51 117.52 121.22 121.23 123.1 123.2 126.81 126.82 130.33 130.34 132.1 132.2 135.81 135.82 135.87 135.88}} {richtext:font:bold {4.4 4.13 4.52 4.59 6.24 6.33 10.20 10.29 10.214 10.221 13.19 13.28 13.208 13.221 13.628 13.637 13.732 13.741 15.4 15.13 15.185 15.194 41.1 41.14 53.42 53.55 53.239 53.252 99.8 99.17}} {richtext:font:bolditalic {10.243 10.248 10.260 10.281 141.24 141.29}} {richtext:font:typewriter {10.102 10.111 10.126 10.133 13.171 13.191 17.184 17.194 17.249 17.253 22.0 22.14 23.0 23.21 30.0 30.20 31.0 31.11 32.0 32.13 33.0 33.14 34.0 34.17 35.0 35.17 36.0 36.15 37.0 37.20 38.0 38.31 45.1 45.22 45.23 45.24 53.118 53.132 53.137 53.150 55.3 55.20 59.1 59.13 59.14 59.15 65.129 65.133 69.1 69.15 69.16 69.17 69.21 69.22 76.281 76.285 77.0 78.0 80.1 80.16 80.17 80.18 80.22 80.23 80.25 80.26 92.1 92.19 103.1 103.19 112.1 112.17 117.29 117.30 117.174 117.191 121.1 121.22 126.29 126.30 130.1 130.33 135.29 135.30 138.21 138.41 138.47 138.64 138.239 138.259 138.269 138.280}} {richtext:font:heading0 {1.0 2.0}} {richtext:font:heading1 {3.0 4.0 8.0 9.0 19.0 20.0 28.0 29.0 43.0 44.0 57.0 58.0 67.0 68.0 78.0 79.0 90.0 91.0 101.0 102.0 110.0 111.0 119.0 120.0 128.0 129.0 137.0 138.0 140.0 141.0}} {richtext:font:heading2 {9.0 10.0 12.0 13.0 20.0 21.0 25.0 26.0 29.0 30.0 40.0 41.0 44.0 45.0 46.0 47.0 50.0 51.0 58.0 59.0 60.0 61.0 64.0 65.0 68.0 69.0 70.0 71.0 75.0 76.0 79.0 80.0 81.0 82.0 87.0 88.0 91.0 92.0 93.0 94.0 96.0 97.0 102.0 103.0 104.0 105.0 107.0 108.0 111.0 112.0 113.0 114.0 116.0 117.0 120.0 121.0 122.0 123.0 125.0 126.0 129.0 130.0 131.0 132.0 134.0 135.0}} {{} {19.0 24.0 25.0 26.0}} {jdoc:link:jstools.jdoc {4.52 4.59}} {jdoc:manpage:tclvars {10.126 10.133}} {jdoc:link:jslibraries.jdoc#Usage {10.239 10.256}} {jdoc:link:jslibraries.jdoc {10.260 10.281}} {jdoc:anchorname:Credits_and_Copyright {19.0 20.0}} {jdoc:anchorname:Introduction {3.0 4.0}} {jdoc:anchorname:Overview {28.0 29.0}} {jdoc:anchorname:Usage {8.0 9.0}} {jdoc:link:panels/prefs.jdoc {55.90 55.108}} {jdoc:link:jslibraries.tcl {10.210 10.231}} {jdoc:link:jtexttags.tcl.jdoc {13.208 13.221 41.1 41.14 53.42 53.55}} {jdoc:anchorname:j:text:insert_string {43.0 44.0}} {jdoc:link:#j:text:insert_string {30.0 30.20}} {jdoc:link:#j:text:move {31.0 31.11}} {jdoc:link:#j:text:delete {32.0 32.13}} {jdoc:link:#j:text:mark_dirty {34.0 34.17}} {jdoc:link:#j:text:mark_clean {35.0 35.17 117.174 117.191}} {jdoc:link:#j:text:is_dirty {36.0 36.15}} {jdoc:link:#j:text:has_selection {37.0 37.20}} {jdoc:link:#j:text:insert_touches_selection {38.0 38.31}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:set_tags {53.118 53.132}} {jdoc:link:jtexttags.tcl.jdoc#j:tag:set_tag {53.137 53.150}} {jdoc:anchorname:j:text:mark_clean {101.0 102.0}} {jdoc:anchorname:j:text:is_dirty {110.0 111.0}} {jdoc:anchorname:j:text:mark_dirty {90.0 91.0}} {jdoc:anchorname:j:text:has_selection {119.0 120.0}} {jdoc:anchorname:j:text:insert_touches_selection {128.0 129.0}} {jdoc:manpage:text {65.129 65.133 76.281 76.285}} {jdoc:anchorname:j:text:move {57.0 58.0}} {jdoc:anchorname:j:text:delete {67.0 68.0}} {jdoc:anchorname:j:text:replace {78.0 79.0}} {jdoc:link:#j:text:replace {33.0 33.14}}} {{richptr 56.0} {del_from 142.0} {matchend 88.47} {abbrevstart 29.0} {abbrevend 30.0} {insert 1.0} {del_to 142.0} {matchstart 88.38} {anchor 1.0} {emacs_mark 142.0} {current 1.0}}}