README
1# RCS: @(#) $Id: README,v 1.3 2005/04/07 02:33:30 andreas_kupries Exp $
2
3 o Author
4
5 George Peter Staplin
6
7 See also: Thanks (below)
8
9
10 o Licensing
11
12 BSD style see the LICENSE file
13
14
15 o Installation
16
17 Ctext requires only one file named ctext.tcl. You
18 can source this file or if you prefer to use
19 "package require ctext" you can use the install.tcl
20 script. The install script can be run like so:
21 wish8.4 install.tcl
22
23 If you are a developer I highly recommend that you
24 study the Usage section below. If you need an
25 example then see the test files (especialy
26 ctext_test_interactive.tcl).
27
28
29 o How it Works
30
31 Ctext overloads the text widget and provides
32 new commands, named highlight, copy, paste, cut,
33 append, and edit. It also provides several
34 commands that allow you to define classes.
35 Each class corresponds to a tag in the widget.
36
37
38 o Usage
39
40 Ctext can be used like so:
41 pack [ctext .t]
42 .t fastinsert end $data
43 .t highlight 1.0 end
44
45 The copy, paste, and cut widget commands are frontends
46 for tk_text*, but they don't require giving an argument
47 for the text widget window. I have also addded an
48 append command, which appends the current selection
49 to the existing clipboard text.
50
51 An edit modified command is available that keeps
52 track of whether or not data in the widget has been
53 modified. .t edit modified would return 0 if the
54 data hasn't been modified. To set the value after
55 inserting text you can use .t edit modified 0. It
56 will automatically be set to 1 during
57 insertion/deletion cut/paste etc.
58
59 During insertion and deletion of text in the widget
60 the tags and highlighting will be automatically
61 updated, unless you specify -highlight 0 during
62 creation or instance configuration of the widget.
63
64 All of the flags that the text widget supports work.
65 It also supports new flags. These new flags are:
66
67 -linemap creates a line number list on the left of
68 the widget.
69
70 -linemapfg changes the foreground of the linemap.
71 The default is the same color as the main text
72 widget.
73
74 -linemapbg changes the background of the linemap.
75 The default is the same color as the main text
76 widget.
77
78 -linemap_select_fg changes the selected
79 line foreground. The default is black.
80
81 -linemap_select_bg changes the selected line
82 background. The default is yellow.
83
84 -linemap_mark_command calls a procedure or command
85 with the path of the ctext window, the type which is
86 either marked or unmarked, and finally the line
87 number selected. The proc prototype is:
88 proc linemark_cmd {win type line}. See also
89 ctext_test_interactive.tcl
90
91 -highlight takes a boolean value which defines
92 whether or not to highlight text which is inserted
93 or deleted. The default is 1.
94
95 -linemap_markable takes a boolean value which
96 specifies whether or not lines in the linemap
97 are markable with the mouse. The default is 1.
98
99 Four highlighting procedures are available for adding
100 keywords. Each proc takes a class, color, keyword,
101 and window argument. The highlight widget command will
102 automatically use each class that you add with any of
103 the three functions. If you want to change the font
104 of a class or another attribute you can run a
105 command like this:
106 .t tag configure $className -font {Helvetica 16}
107
108 Note that the tag is created when you add a class.
109
110 Normal keywords:
111 ctext::addHighlightClass .t class color [list string1 string2 ...]
112
113 Strings that start with chars like $, for $var:
114 ctext::addHighlightClassWithOnlyCharStart .t class color "\$"
115
116 A series of characters in a string
117 ctext:addHighlightClassForSpecialChars .t class color {[]{}}
118
119 Comments, and other things that need regexp:
120 ctext::addHighlightClassForRegexp .t class color {#\[^\n\]*}
121
122 ctext::clearHighlightClasses clears all of the
123 highlight classes from the widget specified.
124 Example: ctext::clearHighlightClasses .t
125
126 To get a list of classes defined for a widget do
127 something like: ctext::getHighlightClasses .t
128
129 To delete a highlight class do something like:
130 ctext::deleteHighlightClass .t classNameToDelete
131
132 You can update a cursor while ctext highlights a large file
133 by overriding ctext::update. Simply source ctext.tcl then
134 create your ctext::update proc, and it will be called by
135 ctext. This allows you to have a progress dialog, or animated
136 cursor.
137
138 If you are using C and want C comments highlighted you can
139 use ctext::enableComments. You can modify the colors of
140 C comments by configuring the tag _cComment after enabling with
141 the afformentioned command. The C comment highlighting is
142 disabled by default.
143
144
145 I have personally tested it with Tcl/Tk 8.4.4 in NetBSD.
146 It should work with all Tcl platforms.
147
148 Please send comments and bugs to the tklib project at
149 tcllib.sf.net
150
151 o Thanks
152
153 Kevin Kenny, Neil Madden, Jeffrey Hobbs, Richard Suchenwirth,
154 Johan Bengtsson, Mac Cody, G�nther, Andreas Sievers, and
155 Michael Schlenker
156