Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "TEXT 1" | |
132 | .TH TEXT 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::Text \- Create and manipulate Text widgets | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\fBtext\fR \f(CW$text\fR ?\fIoptions\fR? | |
138 | .PP | |
139 | \&\fB\-background\fR \fB\-highlightbackground\fR \fB\-insertontime\fR \fB\-selectborderwidth\fR | |
140 | \&\fB\-borderwidth\fR \fB\-highlightcolor\fR \fB\-insertwidth\fR \fB\-selectforeground\fR | |
141 | \&\fB\-cursor\fR \fB\-highlightthickness\fR \fB\-padx\fR \fB\-setgrid\fR | |
142 | \&\fB\-exportselection\fR \fB\-insertbackground\fR \fB\-pady\fR \fB\-takefocus\fR | |
143 | \&\fB\-font\fR \fB\-insertborderwidth\fR \fB\-relief\fR \fB\-xscrollcommand\fR | |
144 | \&\fB\-foreground\fR \fB\-insertofftime\fR \fB\-selectbackground\fR \fB\-yscrollcommand\fR | |
145 | .SH "WIDGET-SPECIFIC OPTIONS" | |
146 | .IX Header "WIDGET-SPECIFIC OPTIONS" | |
147 | .IP "Name: \fBheight\fR" 4 | |
148 | .IX Item "Name: height" | |
149 | .PD 0 | |
150 | .IP "Class: \fBHeight\fR" 4 | |
151 | .IX Item "Class: Height" | |
152 | .IP "Switch: \fB\-height\fR" 4 | |
153 | .IX Item "Switch: -height" | |
154 | .PD | |
155 | Specifies the desired height for the window, in units of characters | |
156 | in the font given by the \fB\-font\fR option. | |
157 | Must be at least one. | |
158 | .IP "Name: \fBspacing1\fR" 4 | |
159 | .IX Item "Name: spacing1" | |
160 | .PD 0 | |
161 | .IP "Class: \fBSpacing1\fR" 4 | |
162 | .IX Item "Class: Spacing1" | |
163 | .IP "Switch: \fB\-spacing1\fR" 4 | |
164 | .IX Item "Switch: -spacing1" | |
165 | .PD | |
166 | Requests additional space above each text line in the widget, | |
167 | using any of the standard forms for screen distances. | |
168 | If a line wraps, this option only applies to the first line | |
169 | on the display. | |
170 | This option may be overriden with \fB\-spacing1\fR options in | |
171 | tags. | |
172 | .IP "Name: \fBspacing2\fR" 4 | |
173 | .IX Item "Name: spacing2" | |
174 | .PD 0 | |
175 | .IP "Class: \fBSpacing2\fR" 4 | |
176 | .IX Item "Class: Spacing2" | |
177 | .IP "Switch: \fB\-spacing2\fR" 4 | |
178 | .IX Item "Switch: -spacing2" | |
179 | .PD | |
180 | For lines that wrap (so that they cover more than one line on the | |
181 | display) this option specifies additional space to provide between | |
182 | the display lines that represent a single line of text. | |
183 | The value may have any of the standard forms for screen distances. | |
184 | This option may be overriden with \fB\-spacing2\fR options in | |
185 | tags. | |
186 | .IP "Name: \fBspacing3\fR" 4 | |
187 | .IX Item "Name: spacing3" | |
188 | .PD 0 | |
189 | .IP "Class: \fBSpacing3\fR" 4 | |
190 | .IX Item "Class: Spacing3" | |
191 | .IP "Switch: \fB\-spacing3\fR" 4 | |
192 | .IX Item "Switch: -spacing3" | |
193 | .PD | |
194 | Requests additional space below each text line in the widget, | |
195 | using any of the standard forms for screen distances. | |
196 | If a line wraps, this option only applies to the last line | |
197 | on the display. | |
198 | This option may be overriden with \fB\-spacing3\fR options in | |
199 | tags. | |
200 | .IP "Name: \fBstate\fR" 4 | |
201 | .IX Item "Name: state" | |
202 | .PD 0 | |
203 | .IP "Class: \fBState\fR" 4 | |
204 | .IX Item "Class: State" | |
205 | .IP "Switch: \fB\-state\fR" 4 | |
206 | .IX Item "Switch: -state" | |
207 | .PD | |
208 | Specifies one of two states for the text: \fBnormal\fR or \fBdisabled\fR. | |
209 | If the text is disabled then characters may not be inserted or deleted | |
210 | and no insertion cursor will be displayed, even if the input focus is | |
211 | in the widget. | |
212 | .IP "Name: \fBtabs\fR" 4 | |
213 | .IX Item "Name: tabs" | |
214 | .PD 0 | |
215 | .IP "Class: \fBTabs\fR" 4 | |
216 | .IX Item "Class: Tabs" | |
217 | .IP "Switch: \fB\-tabs\fR" 4 | |
218 | .IX Item "Switch: -tabs" | |
219 | .PD | |
220 | Specifies a set of tab stops for the window. The option's value consists | |
221 | of a list of screen distances giving the positions of the tab stops. Each | |
222 | position may optionally be followed in the next list element | |
223 | by one of the keywords \fBleft\fR, \fBright\fR, \fBcenter\fR, | |
224 | or \fBnumeric\fR, which specifies how to justify | |
225 | text relative to the tab stop. \fBLeft\fR is the default; it causes | |
226 | the text following the tab character to be positioned with its left edge | |
227 | at the tab position. \fBRight\fR means that the right edge of the text | |
228 | following the tab character is positioned at the tab position, and | |
229 | \&\fBcenter\fR means that the text is centered at the tab position. | |
230 | \&\fBNumeric\fR means that the decimal point in the text is positioned | |
231 | at the tab position; if there is no decimal point then the least | |
232 | significant digit of the number is positioned just to the left of the | |
233 | tab position; if there is no number in the text then the text is | |
234 | right-justified at the tab position. | |
235 | For example, \fB\-tabs => [qw/2c left 4c 6c center/]\fR creates three | |
236 | tab stops at two-centimeter intervals; the first two use left | |
237 | justification and the third uses center justification. | |
238 | If the list of tab stops does not have enough elements to cover all | |
239 | of the tabs in a text line, then Tk extrapolates new tab stops using | |
240 | the spacing and alignment from the last tab stop in the list. | |
241 | The value of the \fBtabs\fR option may be overridden by \fB\-tabs\fR | |
242 | options in tags. | |
243 | If no \fB\-tabs\fR option is specified, or if it is specified as | |
244 | an empty list, then Tk uses default tabs spaced every eight | |
245 | (average size) characters. | |
246 | .IP "Name: \fBwidth\fR" 4 | |
247 | .IX Item "Name: width" | |
248 | .PD 0 | |
249 | .IP "Class: \fBWidth\fR" 4 | |
250 | .IX Item "Class: Width" | |
251 | .IP "Switch: \fB\-width\fR" 4 | |
252 | .IX Item "Switch: -width" | |
253 | .PD | |
254 | Specifies the desired width for the window in units of characters | |
255 | in the font given by the \fB\-font\fR option. | |
256 | If the font doesn't have a uniform width then the width of the | |
257 | character ``0'' is used in translating from character units to | |
258 | screen units. | |
259 | .IP "Name: \fBwrap\fR" 4 | |
260 | .IX Item "Name: wrap" | |
261 | .PD 0 | |
262 | .IP "Class: \fBWrap\fR" 4 | |
263 | .IX Item "Class: Wrap" | |
264 | .IP "Switch: \fB\-wrap\fR" 4 | |
265 | .IX Item "Switch: -wrap" | |
266 | .PD | |
267 | Specifies how to handle lines in the text that are too long to be | |
268 | displayed in a single line of the text's window. | |
269 | The value must be \fBnone\fR or \fBchar\fR or \fBword\fR. | |
270 | A wrap mode of \fBnone\fR means that each line of text appears as | |
271 | exactly one line on the screen; extra characters that don't fit | |
272 | on the screen are not displayed. | |
273 | In the other modes each line of text will be broken up into several | |
274 | screen lines if necessary to keep all the characters visible. | |
275 | In \fBchar\fR mode a screen line break may occur after any character; | |
276 | in \fBword\fR mode a line break will only be made at word boundaries. | |
277 | .SH "DESCRIPTION" | |
278 | .IX Header "DESCRIPTION" | |
279 | The \fBText\fR method creates a new window (given by the | |
280 | \&\f(CW$text\fR argument) and makes it into a text widget. | |
281 | Additional | |
282 | options, described above, may be specified on the command line | |
283 | or in the option database | |
284 | to configure aspects of the text such as its default background color | |
285 | and relief. The \fBtext\fR command returns the | |
286 | path name of the new window. | |
287 | .PP | |
288 | A text widget displays one or more lines of text and allows that | |
289 | text to be edited. | |
290 | Text widgets support four different kinds of annotations on the | |
291 | text, called tags, marks, embedded windows or embedded images. | |
292 | Tags allow different portions of the text | |
293 | to be displayed with different fonts and colors. | |
294 | In addition, perl/Tk callbacks can be associated with tags so | |
295 | that scripts are invoked when particular actions such as keystrokes | |
296 | and mouse button presses occur in particular ranges of the text. | |
297 | See \*(L"\s-1TAGS\s0\*(R" below for more details. | |
298 | .PP | |
299 | The second form of annotation consists of marks, which are floating | |
300 | markers in the text. | |
301 | Marks are used to keep track of various interesting positions in the | |
302 | text as it is edited. | |
303 | See \*(L"\s-1MARKS\s0\*(R" below for more details. | |
304 | .PP | |
305 | The third form of annotation allows arbitrary windows to be | |
306 | embedded in a text widget. | |
307 | See \*(L"\s-1EMBEDDED\s0 \s-1WINDOWS\s0\*(R" below for more details. | |
308 | .PP | |
309 | The fourth form of annotation allows Tk images to be embedded in a text | |
310 | widget. | |
311 | See \*(L"\s-1EMBEDDED\s0 \s-1IMAGES\s0\*(R" below for more details. | |
312 | .SH "INDICES" | |
313 | .IX Header "INDICES" | |
314 | Many of the methods for texts take one or more indices | |
315 | as arguments. | |
316 | An index is a string used to indicate a particular place within | |
317 | a text, such as a place to insert characters or one endpoint of a | |
318 | range of characters to delete. | |
319 | Indices have the syntax | |
320 | .PP | |
321 | .Vb 1 | |
322 | \& base modifier modifier modifier ... | |
323 | .Ve | |
324 | .PP | |
325 | Where \fIbase\fR gives a starting point and the \fImodifier\fRs | |
326 | adjust the index from the starting point (e.g. move forward or | |
327 | backward one character). Every index must contain a \fIbase\fR, | |
328 | but the \fImodifier\fRs are optional. | |
329 | .PP | |
330 | The \fIbase\fR for an index must have one of the following forms: | |
331 | .IP "\fIline\fR\fB.\fR\fIchar\fR" 4 | |
332 | .IX Item "line.char" | |
333 | Indicates \fIchar\fR'th character on line \fIline\fR. | |
334 | Lines are numbered from 1 for consistency with other \s-1UNIX\s0 programs | |
335 | that use this numbering scheme. | |
336 | Within a line, characters are numbered from 0. | |
337 | If \fIchar\fR is \fBend\fR then it refers to the newline character | |
338 | that ends the line. | |
339 | .IP "\fB@\fR\fIx\fR\fB,\fR\fIy\fR" 4 | |
340 | .IX Item "@x,y" | |
341 | Indicates the character that covers the pixel whose x and y coordinates | |
342 | within the text's window are \fIx\fR and \fIy\fR. | |
343 | .IP "\fBend\fR" 4 | |
344 | .IX Item "end" | |
345 | Indicates the end of the text (the character just after the last | |
346 | newline). | |
347 | .IP "\fImark\fR" 4 | |
348 | .IX Item "mark" | |
349 | Indicates the character just after the mark whose name is \fImark\fR. | |
350 | .IP "\fItag\fR\fB.first\fR" 4 | |
351 | .IX Item "tag.first" | |
352 | Indicates the first character in the text that has been tagged with | |
353 | \&\fItag\fR. | |
354 | This form generates an error if no characters are currently tagged | |
355 | with \fItag\fR. | |
356 | .IP "\fItag\fR\fB.last\fR" 4 | |
357 | .IX Item "tag.last" | |
358 | Indicates the character just after the last one in the text that has | |
359 | been tagged with \fItag\fR. | |
360 | This form generates an error if no characters are currently tagged | |
361 | with \fItag\fR. | |
362 | .IP "\fI$widget\fR" 4 | |
363 | .IX Item "$widget" | |
364 | Indicates the position of the embedded window referenced by \fI$widget\fR. | |
365 | This form generates an error if \fI$widget\fR does not reference to an | |
366 | embedded window. | |
367 | .IP "\fIimageName\fR" 4 | |
368 | .IX Item "imageName" | |
369 | Indicates the position of the embedded image whose name is | |
370 | \&\fIimageName\fR. | |
371 | This form generates an error if there is no embedded image | |
372 | by the given name. | |
373 | .Sp | |
374 | If the \fIbase\fR could match more than one of the above forms, such | |
375 | as a \fImark\fR and \fIimageName\fR both having the same value, then | |
376 | the form earlier in the above list takes precedence. | |
377 | If modifiers follow the base index, each one of them must have one | |
378 | of the forms listed below. Keywords such as \fBchars\fR and \fBwordend\fR | |
379 | may be abbreviated as long as the abbreviation is unambiguous. | |
380 | .IP "\fB+ \fR\fIcount\fR\fB chars\fR" 4 | |
381 | .IX Item "+ count chars" | |
382 | Adjust the index forward by \fIcount\fR characters, moving to later | |
383 | lines in the text if necessary. If there are fewer than \fIcount\fR | |
384 | characters in the text after the current index, then set the index | |
385 | to the last character in the text. | |
386 | Spaces on either side of \fIcount\fR are optional. | |
387 | .IP "\fB\- \fR\fIcount\fR\fB chars\fR" 4 | |
388 | .IX Item "- count chars" | |
389 | Adjust the index backward by \fIcount\fR characters, moving to earlier | |
390 | lines in the text if necessary. If there are fewer than \fIcount\fR | |
391 | characters in the text before the current index, then set the index | |
392 | to the first character in the text. | |
393 | Spaces on either side of \fIcount\fR are optional. | |
394 | .IP "\fB+ \fR\fIcount\fR\fB lines\fR" 4 | |
395 | .IX Item "+ count lines" | |
396 | Adjust the index forward by \fIcount\fR lines, retaining the same | |
397 | character position within the line. If there are fewer than \fIcount\fR | |
398 | lines after the line containing the current index, then set the index | |
399 | to refer to the same character position on the last line of the text. | |
400 | Then, if the line is not long enough to contain a character at the indicated | |
401 | character position, adjust the character position to refer to the last | |
402 | character of the line (the newline). | |
403 | Spaces on either side of \fIcount\fR are optional. | |
404 | .IP "\fB\- \fR\fIcount\fR\fB lines\fR" 4 | |
405 | .IX Item "- count lines" | |
406 | Adjust the index backward by \fIcount\fR lines, retaining the same | |
407 | character position within the line. If there are fewer than \fIcount\fR | |
408 | lines before the line containing the current index, then set the index | |
409 | to refer to the same character position on the first line of the text. | |
410 | Then, if the line is not long enough to contain a character at the indicated | |
411 | character position, adjust the character position to refer to the last | |
412 | character of the line (the newline). | |
413 | Spaces on either side of \fIcount\fR are optional. | |
414 | .IP "\fBlinestart\fR" 4 | |
415 | .IX Item "linestart" | |
416 | Adjust the index to refer to the first character on the line. | |
417 | .IP "\fBlineend\fR" 4 | |
418 | .IX Item "lineend" | |
419 | Adjust the index to refer to the last character on the line (the newline). | |
420 | .IP "\fBwordstart\fR" 4 | |
421 | .IX Item "wordstart" | |
422 | Adjust the index to refer to the first character of the word containing | |
423 | the current index. A word consists of any number of adjacent characters | |
424 | that are letters, digits, or underscores, or a single character that | |
425 | is not one of these. | |
426 | .IP "\fBwordend\fR" 4 | |
427 | .IX Item "wordend" | |
428 | Adjust the index to refer to the character just after the last one of the | |
429 | word containing the current index. If the current index refers to the last | |
430 | character of the text then it is not modified. | |
431 | .Sp | |
432 | If more than one modifier is present then they are applied in | |
433 | left-to-right order. For example, the index ``\fBend \- 1 chars\fR'' | |
434 | refers to the next-to-last character in the text and | |
435 | ``\fBinsert wordstart \- 1 c\fR'' refers to the character just before | |
436 | the first one in the word containing the insertion cursor. | |
437 | .SH "TAGS" | |
438 | .IX Header "TAGS" | |
439 | The first form of annotation in text widgets is a tag. | |
440 | A tag is a textual string that is associated with some of the characters | |
441 | in a text. | |
442 | Tags may contain arbitrary characters, but it is probably best to | |
443 | avoid using the the characters `` '' (space), \fB+\fR, or \fB\-\fR: | |
444 | these characters have special meaning in indices, so tags containing | |
445 | them can't be used as indices. | |
446 | There may be any number of tags associated with characters in a | |
447 | text. | |
448 | Each tag may refer to a single character, a range of characters, or | |
449 | several ranges of characters. | |
450 | An individual character may have any number of tags associated with it. | |
451 | .PP | |
452 | A priority order is defined among tags, and this order is used in | |
453 | implementing some of the tag-related functions described below. | |
454 | When a tag is defined (by associating it with characters or setting | |
455 | its display options or binding callbacks to it), it is given | |
456 | a priority higher than any existing tag. | |
457 | The priority order of tags may be redefined using the | |
458 | ``\fI$text\fR\->\fBtagRaise\fR'' and ``\fI$text\fR\->\fBtagLower\fR'' | |
459 | methods. | |
460 | .PP | |
461 | Tags serve three purposes in text widgets. | |
462 | First, they control the way information is displayed on the screen. | |
463 | By default, characters are displayed as determined by the | |
464 | \&\fBbackground\fR, \fBfont\fR, and \fBforeground\fR options for the | |
465 | text widget. | |
466 | However, display options may be associated with individual tags | |
467 | using the ``\fI$text\fR\->\fBtagConfigure\fR'' method. | |
468 | If a character has been tagged, then the display options associated | |
469 | with the tag override the default display style. | |
470 | The following options are currently supported for tags: | |
471 | .IP "\fB\-background\fR => \fIcolor\fR" 4 | |
472 | .IX Item "-background => color" | |
473 | \&\fIColor\fR specifies the background color to use for characters | |
474 | associated with the tag. | |
475 | It may have any of the forms accepted by \fBTk_GetColor\fR. | |
476 | .IP "\fB\-bgstipple\fR => \fIbitmap\fR" 4 | |
477 | .IX Item "-bgstipple => bitmap" | |
478 | \&\fIBitmap\fR specifies a bitmap that is used as a stipple pattern | |
479 | for the background. | |
480 | It may have any of the forms accepted by \fBTk_GetBitmap\fR. | |
481 | If \fIbitmap\fR hasn't been specified, or if it is specified | |
482 | as an empty string, then a solid fill will be used for the | |
483 | background. | |
484 | .IP "\fB\-borderwidth\fR => \fIpixels\fR" 4 | |
485 | .IX Item "-borderwidth => pixels" | |
486 | \&\fIPixels\fR specifies the width of a 3\-D border to draw around | |
487 | the background. | |
488 | It may have any of the forms accepted by \fBTk_GetPixels\fR. | |
489 | This option is used in conjunction with the \fB\-relief\fR | |
490 | option to give a 3\-D appearance to the background for characters; | |
491 | it is ignored unless the \fB\-background\fR option | |
492 | has been set for the tag. | |
493 | .IP "\fB\-fgstipple\fR => \fIbitmap\fR" 4 | |
494 | .IX Item "-fgstipple => bitmap" | |
495 | \&\fIBitmap\fR specifies a bitmap that is used as a stipple pattern | |
496 | when drawing text and other foreground information such as | |
497 | underlines. | |
498 | It may have any of the forms accepted by \fBTk_GetBitmap\fR. | |
499 | If \fIbitmap\fR hasn't been specified, or if it is specified | |
500 | as an empty string, then a solid fill will be used. | |
501 | .IP "\fB\-font\fR => \fIfontName\fR" 4 | |
502 | .IX Item "-font => fontName" | |
503 | \&\fIFontName\fR is the name of a font to use for drawing characters. | |
504 | It may have any of the forms accepted by \fBTk_GetFontStruct\fR. | |
505 | .IP "\fB\-foreground\fR => \fIcolor\fR" 4 | |
506 | .IX Item "-foreground => color" | |
507 | \&\fIColor\fR specifies the color to use when drawing text and other | |
508 | foreground information such as underlines. | |
509 | It may have any of the forms accepted by \fBTk_GetColor\fR. | |
510 | .IP "\fB\-justify\fR => \fIjustify\fR" 4 | |
511 | .IX Item "-justify => justify" | |
512 | If the first character of a display line has a tag for which this | |
513 | option has been specified, then \fIjustify\fR determines how to | |
514 | justify the line. | |
515 | It must be one of \fBleft\fR, \fBright\fR, or \fBcenter\fR. | |
516 | If a line wraps, then the justification for each line on the | |
517 | display is determined by the first character of that display line. | |
518 | .IP "\fB\-lmargin1\fR => \fIpixels\fR" 4 | |
519 | .IX Item "-lmargin1 => pixels" | |
520 | If the first character of a text line has a tag for which this | |
521 | option has been specified, then \fIpixels\fR specifies how | |
522 | much the line should be indented from the left edge of the | |
523 | window. | |
524 | \&\fIPixels\fR may have any of the standard forms for screen | |
525 | distances. | |
526 | If a line of text wraps, this option only applies to the | |
527 | first line on the display; the \fB\-lmargin2\fR option controls | |
528 | the indentation for subsequent lines. | |
529 | .IP "\fB\-lmargin2\fR => \fIpixels\fR" 4 | |
530 | .IX Item "-lmargin2 => pixels" | |
531 | If the first character of a display line has a tag for which this | |
532 | option has been specified, and if the display line is not the | |
533 | first for its text line (i.e., the text line has wrapped), then | |
534 | \&\fIpixels\fR specifies how much the line should be indented from | |
535 | the left edge of the window. | |
536 | \&\fIPixels\fR may have any of the standard forms for screen | |
537 | distances. | |
538 | This option is only used when wrapping is enabled, and it only | |
539 | applies to the second and later display lines for a text line. | |
540 | .IP "\fB\-offset\fR => \fIpixels\fR" 4 | |
541 | .IX Item "-offset => pixels" | |
542 | \&\fIPixels\fR specifies an amount by which the text's baseline | |
543 | should be offset vertically from the baseline of the overall | |
544 | line, in pixels. | |
545 | For example, a positive offset can be used for superscripts | |
546 | and a negative offset can be used for subscripts. | |
547 | \&\fIPixels\fR may have any of the standard forms for screen | |
548 | distances. | |
549 | .IP "\fB\-overstrike\fR => \fIboolean\fR" 4 | |
550 | .IX Item "-overstrike => boolean" | |
551 | Specifies whether or not to draw a horizontal rule through | |
552 | the middle of characters. | |
553 | \&\fIBoolean\fR may have any of the forms accepted by \fBTk_GetBoolean\fR. | |
554 | .IP "\fB\-relief\fR => \fIrelief\fR" 4 | |
555 | .IX Item "-relief => relief" | |
556 | \&\fIRelief\fR specifies the 3\-D relief to use for drawing backgrounds, | |
557 | in any of the forms accepted by \fBTk_GetRelief\fR. | |
558 | This option is used in conjunction with the \fB\-borderwidth\fR | |
559 | option to give a 3\-D appearance to the background for characters; | |
560 | it is ignored unless the \fB\-background\fR option | |
561 | has been set for the tag. | |
562 | .IP "\fB\-rmargin\fR => \fIpixels\fR" 4 | |
563 | .IX Item "-rmargin => pixels" | |
564 | If the first character of a display line has a tag for which this | |
565 | option has been specified, then \fIpixels\fR specifies how wide | |
566 | a margin to leave between the end of the line and the right | |
567 | edge of the window. | |
568 | \&\fIPixels\fR may have any of the standard forms for screen | |
569 | distances. | |
570 | This option is only used when wrapping is enabled. | |
571 | If a text line wraps, the right margin for each line on the | |
572 | display is determined by the first character of that display | |
573 | line. | |
574 | .IP "\fB\-spacing1\fR => \fIpixels\fR" 4 | |
575 | .IX Item "-spacing1 => pixels" | |
576 | \&\fIPixels\fR specifies how much additional space should be | |
577 | left above each text line, using any of the standard forms for | |
578 | screen distances. | |
579 | If a line wraps, this option only applies to the first | |
580 | line on the display. | |
581 | .IP "\fB\-spacing2\fR => \fIpixels\fR" 4 | |
582 | .IX Item "-spacing2 => pixels" | |
583 | For lines that wrap, this option specifies how much additional | |
584 | space to leave between the display lines for a single text line. | |
585 | \&\fIPixels\fR may have any of the standard forms for screen | |
586 | distances. | |
587 | .IP "\fB\-spacing3\fR => \fIpixels\fR" 4 | |
588 | .IX Item "-spacing3 => pixels" | |
589 | \&\fIPixels\fR specifies how much additional space should be | |
590 | left below each text line, using any of the standard forms for | |
591 | screen distances. | |
592 | If a line wraps, this option only applies to the last | |
593 | line on the display. | |
594 | .IP "\fB\-state\fR => \fIstate\fR" 4 | |
595 | .IX Item "-state => state" | |
596 | \&\fIState\fR specifies if the text is \fIhidden\fR or \fInormal\fR. | |
597 | Hidden text is not displayed and takes no space on screen, but further | |
598 | on behaves just as normal text. | |
599 | .IP "\fB\-tabs\fR => \fItabList\fR" 4 | |
600 | .IX Item "-tabs => tabList" | |
601 | \&\fITabList\fR specifies a set of tab stops in the same form | |
602 | as for the \fB\-tabs\fR option for the text widget. This | |
603 | option only applies to a display line if it applies to the | |
604 | first character on that display line. | |
605 | If this option is specified as an empty string, it cancels | |
606 | the option, leaving it unspecified for the tag (the default). | |
607 | If the option is specified as a non-empty string that is | |
608 | an empty list, such as \fB\-tabs =\fR \*(L" \*(R">, then it requests | |
609 | default 8\-character tabs as described for the \fBtabs\fR | |
610 | widget option. | |
611 | .IP "\fB\-underline\fR => \fIboolean\fR" 4 | |
612 | .IX Item "-underline => boolean" | |
613 | \&\fIBoolean\fR specifies whether or not to draw an underline underneath | |
614 | characters. | |
615 | It may have any of the forms accepted by \fBTk_GetBoolean\fR. | |
616 | .IP "\fB\-wrap\fR => \fImode\fR" 4 | |
617 | .IX Item "-wrap => mode" | |
618 | \&\fIMode\fR specifies how to handle lines that are wider than the | |
619 | text's window. | |
620 | It has the same legal values as the \fB\-wrap\fR option | |
621 | for the text widget: \fBnone\fR, \fBchar\fR, or \fBword\fR. | |
622 | If this tag option is specified, it overrides the \fB\-wrap\fR option | |
623 | for the text widget. | |
624 | .IP "\fB\-elide\fR => \fIvalue\fR" 4 | |
625 | .IX Item "-elide => value" | |
626 | If value is true then text covered by the tag is not displayed. | |
627 | .IP "\fB\-data\fR => \fIvalue\fR" 4 | |
628 | .IX Item "-data => value" | |
629 | Allows an arbitrary perl scalar \fIvalue\fR to be associated with the tag. | |
630 | .PP | |
631 | If a character has several tags associated with it, and if their | |
632 | display options conflict, then the options of the highest priority | |
633 | tag are used. | |
634 | If a particular display option hasn't been specified for a | |
635 | particular tag, or if it is specified as an empty string, then | |
636 | that option will never be used; the next-highest-priority | |
637 | tag's option will used instead. | |
638 | If no tag specifies a particular display option, then the default | |
639 | style for the widget will be used. | |
640 | .PP | |
641 | The second purpose for tags is event bindings. | |
642 | You can associate bindings with a tag in much the same way you can | |
643 | associate bindings with a widget class: whenever particular X | |
644 | events occur on characters with the given tag, a given | |
645 | <perl/Tk callback|Tk::callbacks> will be executed. | |
646 | Tag bindings can be used to give behaviors to ranges of characters; | |
647 | among other things, this allows hypertext-like | |
648 | features to be implemented. | |
649 | For details, see the description of the \fBtagBind\fR widget | |
650 | method below. | |
651 | .PP | |
652 | The third use for tags is in managing the selection. | |
653 | See \*(L"\s-1THE\s0 \s-1SELECTION\s0\*(R" below. | |
654 | .SH "MARKS" | |
655 | .IX Header "MARKS" | |
656 | The second form of annotation in text widgets is a mark. | |
657 | Marks are used for remembering particular places in a text. | |
658 | They are something like tags, in that they have names and | |
659 | they refer to places in the file, but a mark isn't associated | |
660 | with particular characters. | |
661 | Instead, a mark is associated with the gap between two characters. | |
662 | Only a single position may be associated with a mark at any given | |
663 | time. | |
664 | If the characters around a mark are deleted the mark will still | |
665 | remain; it will just have new neighbor characters. | |
666 | In contrast, if the characters containing a tag are deleted then | |
667 | the tag will no longer have an association with characters in | |
668 | the file. | |
669 | Marks may be manipulated with the ``\fI$text\fR\->\fBmark\fR'' text widget | |
670 | method, and their current locations may be determined by using the | |
671 | mark name as an index in methods. | |
672 | .PP | |
673 | Each mark also has a \fIgravity\fR, which is either \fBleft\fR or | |
674 | \&\fBright\fR. | |
675 | The gravity for a mark specifies what happens to the mark when | |
676 | text is inserted at the point of the mark. | |
677 | If a mark has left gravity, then the mark is treated as if it | |
678 | were attached to the character on its left, so the mark will | |
679 | remain to the left of any text inserted at the mark position. | |
680 | If the mark has right gravity, new text inserted at the mark | |
681 | position will appear to the right of the mark. The gravity | |
682 | for a mark defaults to \fBright\fR. | |
683 | .PP | |
684 | The name space for marks is different from that for tags: the | |
685 | same name may be used for both a mark and a tag, but they will refer | |
686 | to different things. | |
687 | .PP | |
688 | Two marks have special significance. | |
689 | First, the mark \fBinsert\fR is associated with the insertion cursor, | |
690 | as described under \*(L"\s-1THE\s0 \s-1INSERTION\s0 \s-1CURSOR\s0\*(R" below. | |
691 | Second, the mark \fBcurrent\fR is associated with the character | |
692 | closest to the mouse and is adjusted automatically to track the | |
693 | mouse position and any changes to the text in the widget (one | |
694 | exception: \fBcurrent\fR is not updated in response to mouse | |
695 | motions if a mouse button is down; the update will be deferred | |
696 | until all mouse buttons have been released). | |
697 | Neither of these special marks may be deleted. | |
698 | .SH "EMBEDDED WINDOWS" | |
699 | .IX Header "EMBEDDED WINDOWS" | |
700 | The third form of annotation in text widgets is an embedded window. | |
701 | Each embedded window annotation causes a window to be displayed | |
702 | at a particular point in the text. | |
703 | There may be any number of embedded windows in a text widget, | |
704 | and any widget may be used as an embedded window (subject to the | |
705 | usual rules for geometry management, which require the text window | |
706 | to be the parent of the embedded window or a descendant of its | |
707 | parent). | |
708 | The embedded window's position on the screen will be updated as the | |
709 | text is modified or scrolled, and it will be mapped and unmapped as | |
710 | it moves into and out of the visible area of the text widget. | |
711 | Each embedded window occupies one character's worth of index space | |
712 | in the text widget, and it may be referred to either by the name | |
713 | of its embedded window or by its position in the widget's | |
714 | index space. | |
715 | If the range of text containing the embedded window is deleted then | |
716 | the window is destroyed. | |
717 | .PP | |
718 | When an embedded window is added to a text widget with the | |
719 | \&\fBwidgetCreate\fR method, several configuration | |
720 | options may be associated with it. | |
721 | These options may be modified later with the \fBwidgetConfigure\fR | |
722 | method. | |
723 | The following options are currently supported: | |
724 | .IP "\fB\-align\fR => \fIwhere\fR" 4 | |
725 | .IX Item "-align => where" | |
726 | If the window is not as tall as the line in which it is displayed, | |
727 | this option determines where the window is displayed in the line. | |
728 | \&\fIWhere\fR must have one of the values \fBtop\fR (align the top of the window | |
729 | with the top of the line), \fBcenter\fR (center the window | |
730 | within the range of the line), \fBbottom\fR (align the bottom of the | |
731 | window with the bottom of the line's area), | |
732 | or \fBbaseline\fR (align the bottom of the window with the baseline | |
733 | of the line). | |
734 | .IP "\fB\-create\fR => \fIcallback\fR" 4 | |
735 | .IX Item "-create => callback" | |
736 | Specifies a callback that may be evaluated to create the window | |
737 | for the annotation. | |
738 | If no \fB\-window\fR option has been specified for the annotation | |
739 | this \fIcallback\fR will be evaluated when the annotation is about to | |
740 | be displayed on the screen. | |
741 | \&\fICallback\fR must create a window for the annotation and return | |
742 | the name of that window as its result. | |
743 | If the annotation's window should ever be deleted, \fIcallback\fR | |
744 | will be evaluated again the next time the annotation is displayed. | |
745 | .IP "\fB\-padx\fR => \fIpixels\fR" 4 | |
746 | .IX Item "-padx => pixels" | |
747 | \&\fIPixels\fR specifies the amount of extra space to leave on | |
748 | each side of the embedded window. | |
749 | It may have any of the usual forms defined for a screen distance | |
750 | (see \fBTk_GetPixels\fR). | |
751 | .IP "\fB\-pady\fR => \fIpixels\fR" 4 | |
752 | .IX Item "-pady => pixels" | |
753 | \&\fIPixels\fR specifies the amount of extra space to leave on | |
754 | the top and on the bottom of the embedded window. | |
755 | It may have any of the usual forms defined for a screen distance | |
756 | (see \fBTk_GetPixels\fR). | |
757 | .IP "\fB\-stretch\fR => \fIboolean\fR" 4 | |
758 | .IX Item "-stretch => boolean" | |
759 | If the requested height of the embedded window is less than the | |
760 | height of the line in which it is displayed, this option can be | |
761 | used to specify whether the window should be stretched vertically | |
762 | to fill its line. | |
763 | If the \fB\-pady\fR option has been specified as well, then the | |
764 | requested padding will be retained even if the window is | |
765 | stretched. | |
766 | .IP "\fB\-window\fR => \fI$widget\fR" 4 | |
767 | .IX Item "-window => $widget" | |
768 | Specifies the name of a window to display in the annotation. | |
769 | .SH "EMBEDDED IMAGES" | |
770 | .IX Header "EMBEDDED IMAGES" | |
771 | The final form of annotation in text widgets is an embedded image. | |
772 | Each embedded image annotation causes an image to be displayed | |
773 | at a particular point in the text. | |
774 | There may be any number of embedded images in a text widget, | |
775 | and a particular image may be embedded in multiple places in the same | |
776 | text widget. | |
777 | The embedded image's position on the screen will be updated as the | |
778 | text is modified or scrolled. | |
779 | Each embedded image occupies one character's worth of index space | |
780 | in the text widget, and it may be referred to either by | |
781 | its position in the widget's index space, or the name it is assigned | |
782 | when the image is inserted into the text widget with \fBimageCreate\fR. | |
783 | If the range of text containing the embedded image is deleted then | |
784 | that copy of the image is removed from the screen. | |
785 | .PP | |
786 | When an embedded image is added to a text widget with the \fBimage\fR | |
787 | create method, a name unique to this instance of the image | |
788 | is returned. This name may then be used to refer to this image | |
789 | instance. The name is taken to be the value of the \fB\-name\fR option | |
790 | (described below). If the \fB\-name\fR option is not provided, the | |
791 | \&\fB\-image\fR name is used instead. If the \fIimageName\fR is already | |
792 | in use in the text widget, then \fB#\fR\fInn\fR is added to the end of the | |
793 | \&\fIimageName\fR, where \fInn\fR is an arbitrary integer. This insures | |
794 | the \fIimageName\fR is unique. | |
795 | Once this name is assigned to this instance of the image, it does not | |
796 | change, even though the \fB\-image\fR or \fB\-name\fR values can be changed | |
797 | with \fBimage configure\fR. | |
798 | .PP | |
799 | When an embedded image is added to a text widget with the | |
800 | \&\fBimageCreate\fR method, several configuration | |
801 | options may be associated with it. | |
802 | These options may be modified later with the \fBimage configure\fR | |
803 | method. | |
804 | The following options are currently supported: | |
805 | .IP "\fB\-align\fR => \fIwhere\fR" 4 | |
806 | .IX Item "-align => where" | |
807 | If the image is not as tall as the line in which it is displayed, | |
808 | this option determines where the image is displayed in the line. | |
809 | \&\fIWhere\fR must have one of the values \fBtop\fR (align the top of the image | |
810 | with the top of the line), \fBcenter\fR (center the image | |
811 | within the range of the line), \fBbottom\fR (align the bottom of the | |
812 | image with the bottom of the line's area), | |
813 | or \fBbaseline\fR (align the bottom of the image with the baseline | |
814 | of the line). | |
815 | .IP "\fB\-image\fR => \fIimage\fR" 4 | |
816 | .IX Item "-image => image" | |
817 | Specifies the name of the Tk image to display in the annotation. | |
818 | If \fIimage\fR is not a valid Tk image, then an error is returned. | |
819 | .IP "\fB\-name\fR => \fIImageName\fR" 4 | |
820 | .IX Item "-name => ImageName" | |
821 | Specifies the name by which this image instance may be referenced in | |
822 | the text widget. If \fIImageName\fR is not supplied, then the | |
823 | name of the Tk image is used instead. | |
824 | If the \fIimageName\fR is already in use, \fI#nn\fR is appended to | |
825 | the end of the name as described above. | |
826 | .IP "\fB\-padx\fR => \fIpixels\fR" 4 | |
827 | .IX Item "-padx => pixels" | |
828 | \&\fIPixels\fR specifies the amount of extra space to leave on | |
829 | each side of the embedded image. | |
830 | It may have any of the usual forms defined for a screen distance. | |
831 | .IP "\fB\-pady\fR => \fIpixels\fR" 4 | |
832 | .IX Item "-pady => pixels" | |
833 | \&\fIPixels\fR specifies the amount of extra space to leave on | |
834 | the top and on the bottom of the embedded image. | |
835 | It may have any of the usual forms defined for a screen distance. | |
836 | .SH "THE SELECTION" | |
837 | .IX Header "THE SELECTION" | |
838 | Selection support is implemented via tags. | |
839 | If the \fBexportSelection\fR option for the text widget is true | |
840 | then the \fBsel\fR tag will be associated with the selection: | |
841 | .IP "[1]" 4 | |
842 | .IX Item "[1]" | |
843 | Whenever characters are tagged with \fBsel\fR the text widget | |
844 | will claim ownership of the selection. | |
845 | .IP "[2]" 4 | |
846 | .IX Item "[2]" | |
847 | Attempts to retrieve the | |
848 | selection will be serviced by the text widget, returning all the | |
849 | characters with the \fBsel\fR tag. | |
850 | .IP "[3]" 4 | |
851 | .IX Item "[3]" | |
852 | If the selection is claimed away by another application or by another | |
853 | window within this application, then the \fBsel\fR tag will be removed | |
854 | from all characters in the text. | |
855 | .Sp | |
856 | The \fBsel\fR tag is automatically defined when a text widget is | |
857 | created, and it may not be deleted with the ``\fI$text\fR\->\fBtagDelete\fR'' | |
858 | method. Furthermore, the \fBselectBackground\fR, | |
859 | \&\fBselectBorderWidth\fR, and \fBselectForeground\fR options for | |
860 | the text widget are tied to the \fB\-background\fR, | |
861 | \&\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR | |
862 | tag: changes in either will automatically be reflected in the | |
863 | other. | |
864 | .SH "THE INSERTION CURSOR" | |
865 | .IX Header "THE INSERTION CURSOR" | |
866 | The mark named \fBinsert\fR has special significance in text widgets. | |
867 | It is defined automatically when a text widget is created and it | |
868 | may not be unset with the ``\fI$text\fR\->\fBmarkUnset\fR'' widget | |
869 | command. | |
870 | The \fBinsert\fR mark represents the position of the insertion | |
871 | cursor, and the insertion cursor will automatically be drawn at | |
872 | this point whenever the text widget has the input focus. | |
873 | .SH "WIDGET METHODS" | |
874 | .IX Header "WIDGET METHODS" | |
875 | The \fBText\fR method creates a widget object. | |
876 | This object supports the \fBconfigure\fR and \fBcget\fR methods | |
877 | described in Tk::options which can be used to enquire and | |
878 | modify the options described above. | |
879 | The widget also inherits all the methods provided by the generic | |
880 | Tk::Widget class. | |
881 | .PP | |
882 | The following additional methods are available for text widgets: | |
883 | .IP "\fI$text\fR\->\fBbbox\fR(\fIindex\fR)" 4 | |
884 | .IX Item "$text->bbox(index)" | |
885 | Returns a list of four elements describing the screen area | |
886 | of the character given by \fIindex\fR. | |
887 | The first two elements of the list give the x and y coordinates | |
888 | of the upper-left corner of the area occupied by the | |
889 | character, and the last two elements give the width and height | |
890 | of the area. | |
891 | If the character is only partially visible on the screen, then | |
892 | the return value reflects just the visible part. | |
893 | If the character is not visible on the screen then the return | |
894 | value is an empty list. | |
895 | .IP "\fI$text\fR\->\fBcompare\fR(\fIindex1, op, index2\fR)" 4 | |
896 | .IX Item "$text->compare(index1, op, index2)" | |
897 | Compares the indices given by \fIindex1\fR and \fIindex2\fR according | |
898 | to the relational operator given by \fIop\fR, and returns 1 if | |
899 | the relationship is satisfied and 0 if it isn't. | |
900 | \&\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=. | |
901 | If \fIop\fR is == then 1 is returned if the two indices refer to | |
902 | the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR | |
903 | refers to an earlier character in the text than \fIindex2\fR, and | |
904 | so on. | |
905 | .IP "\fI$text\fR\->\fBdebug\fR(?\fIboolean\fR?)" 4 | |
906 | .IX Item "$text->debug(?boolean?)" | |
907 | If \fIboolean\fR is specified, then it must have one of the true or | |
908 | false values accepted by Tcl_GetBoolean. | |
909 | If the value is a true one then internal consistency checks will be | |
910 | turned on in the B\-tree code associated with text widgets. | |
911 | If \fIboolean\fR has a false value then the debugging checks will | |
912 | be turned off. | |
913 | In either case the command returns an empty string. | |
914 | If \fIboolean\fR is not specified then the command returns \fBon\fR | |
915 | or \fBoff\fR to indicate whether or not debugging is turned on. | |
916 | There is a single debugging switch shared by all text widgets: turning | |
917 | debugging on or off in any widget turns it on or off for all widgets. | |
918 | For widgets with large amounts of text, the consistency checks may | |
919 | cause a noticeable slow\-down. | |
920 | .IP "\fI$text\fR\->\fBdelete\fR(\fIindex1, \fR?\fIindex2\fR?)" 4 | |
921 | .IX Item "$text->delete(index1, ?index2?)" | |
922 | Delete a range of characters from the text. | |
923 | If both \fIindex1\fR and \fIindex2\fR are specified, then delete | |
924 | all the characters starting with the one given by \fIindex1\fR | |
925 | and stopping just before \fIindex2\fR (i.e. the character at | |
926 | \&\fIindex2\fR is not deleted). | |
927 | If \fIindex2\fR doesn't specify a position later in the text | |
928 | than \fIindex1\fR then no characters are deleted. | |
929 | If \fIindex2\fR isn't specified then the single character at | |
930 | \&\fIindex1\fR is deleted. | |
931 | It is not allowable to delete characters in a way that would leave | |
932 | the text without a newline as the last character. | |
933 | The command returns an empty string. | |
934 | .IP "\fI$text\fR\->\fBdlineinfo\fR(\fIindex\fR)" 4 | |
935 | .IX Item "$text->dlineinfo(index)" | |
936 | Returns a list with five elements describing the area occupied | |
937 | by the display line containing \fIindex\fR. | |
938 | The first two elements of the list give the x and y coordinates | |
939 | of the upper-left corner of the area occupied by the | |
940 | line, the third and fourth elements give the width and height | |
941 | of the area, and the fifth element gives the position of the baseline | |
942 | for the line, measured down from the top of the area. | |
943 | All of this information is measured in pixels. | |
944 | If the current wrap mode is \fBnone\fR and the line extends beyond | |
945 | the boundaries of the window, | |
946 | the area returned reflects the entire area of the line, including the | |
947 | portions that are out of the window. | |
948 | If the line is shorter than the full width of the window then the | |
949 | area returned reflects just the portion of the line that is occupied | |
950 | by characters and embedded windows. | |
951 | If the display line containing \fIindex\fR is not visible on | |
952 | the screen then the return value is an empty list. | |
953 | .IP "\fI$text\fR\->\fBdump\fR(?\fIswitches\fR?, \fIindex1, \fR?\fIindex2\fR?)" 4 | |
954 | .IX Item "$text->dump(?switches?, index1, ?index2?)" | |
955 | Return the contents of the text widget from \fIindex1\fR up to, | |
956 | but not including \fIindex2\fR, | |
957 | including the text and | |
958 | information about marks, tags, and embedded windows. | |
959 | If \fIindex2\fR is not specified, then it defaults to | |
960 | one character past \fIindex1\fR. The information is returned | |
961 | in the following format: | |
962 | .Sp | |
963 | \&\fIkey1 value1 index1 key2 value2 index2\fR ... | |
964 | .PP | |
965 | The possible \fIkey\fR values are \fBtext\fR, \fBmark\fR, | |
966 | \&\fBtagon\fR, \fBtagoff\fR, and \fI$text\fR. The corresponding | |
967 | \&\fIvalue\fR is the text, mark name, tag name, or window name. | |
968 | The \fIindex\fR information is the index of the | |
969 | start of the text, the mark, the tag transition, or the window. | |
970 | One or more of the following switches (or abbreviations thereof) | |
971 | may be specified to control the dump: | |
972 | .IP "\fB\-all\fR" 4 | |
973 | .IX Item "-all" | |
974 | Return information about all elements: text, marks, tags, and windows. | |
975 | This is the default. | |
976 | .IP "\fB\-command\fR => \fIcallback\fR" 4 | |
977 | .IX Item "-command => callback" | |
978 | Instead of returning the information as the result of the dump operation, | |
979 | invoke the \fIcallback\fR on each element of the text widget within the range. | |
980 | The callback has three arguments appended to it before it is evaluated: | |
981 | the \fIkey\fR, \fIvalue\fR, and \fIindex\fR. | |
982 | .IP "\fB\-mark\fR" 4 | |
983 | .IX Item "-mark" | |
984 | Include information about marks in the dump results. | |
985 | .IP "\fB\-tag\fR" 4 | |
986 | .IX Item "-tag" | |
987 | Include information about tag transitions in the dump results. Tag information is | |
988 | returned as \fBtagon\fR and \fBtagoff\fR elements that indicate the | |
989 | begin and end of each range of each tag, respectively. | |
990 | .IP "\fB\-text\fR" 4 | |
991 | .IX Item "-text" | |
992 | Include information about text in the dump results. The value is the | |
993 | text up to the next element or the end of range indicated by \fIindex2\fR. | |
994 | A text element does not span newlines. A multi-line block of text that | |
995 | contains no marks or tag transitions will still be dumped as a set | |
996 | of text seqments that each end with a newline. The newline is part | |
997 | of the value. | |
998 | .IP "\fB\-window\fR" 4 | |
999 | .IX Item "-window" | |
1000 | Include information about embedded windows in the dump results. | |
1001 | The value of a window is its Tk pathname, unless the window | |
1002 | has not been created yet. (It must have a create script.) | |
1003 | In this case an empty string is returned, and you must query the | |
1004 | window by its index position to get more information. | |
1005 | .IP "\fI$text\fR\->\fBget\fR(\fIindex1, \fR?\fIindex2\fR?)" 4 | |
1006 | .IX Item "$text->get(index1, ?index2?)" | |
1007 | Return a range of characters from the text. | |
1008 | The return value will be all the characters in the text starting | |
1009 | with the one whose index is \fIindex1\fR and ending just before | |
1010 | the one whose index is \fIindex2\fR (the character at \fIindex2\fR | |
1011 | will not be returned). | |
1012 | If \fIindex2\fR is omitted then the single character at \fIindex1\fR | |
1013 | is returned. | |
1014 | If there are no characters in the specified range (e.g. \fIindex1\fR | |
1015 | is past the end of the file or \fIindex2\fR is less than or equal | |
1016 | to \fIindex1\fR) then an empty string is returned. | |
1017 | If the specified range contains embedded windows, no information | |
1018 | about them is included in the returned string. | |
1019 | .IP "\fI$text\fR\->\fBimage\fR(\fIoption\fR, ?\fIarg, arg, ...\fR?)" 4 | |
1020 | .IX Item "$text->image(option, ?arg, arg, ...?)" | |
1021 | .PD 0 | |
1022 | .IP "\fI$text\fR\->\fBimage\fR\fIOption\fR(?\fIarg, arg, ...\fR?)" 4 | |
1023 | .IX Item "$text->imageOption(?arg, arg, ...?)" | |
1024 | .PD | |
1025 | This method is used to manipulate embedded images. | |
1026 | The behavior of the method depends on the \fIoption\fR argument | |
1027 | that follows the \fBimage\fR prefix. | |
1028 | The following forms of the methods are currently supported: | |
1029 | .RS 4 | |
1030 | .IP "\fI$text\fR\->\fBimageCget\fR(\fIindex, option\fR)" 8 | |
1031 | .IX Item "$text->imageCget(index, option)" | |
1032 | Returns the value of a configuration option for an embedded image. | |
1033 | \&\fIIndex\fR identifies the embedded image, and \fIoption\fR | |
1034 | specifies a particular configuration option, which must be one of | |
1035 | the ones listed in \*(L"\s-1EMBEDDED\s0 \s-1IMAGES\s0\*(R". | |
1036 | .IP "\fI$text\fR\->\fBimageConfigure\fR(\fIindex, \fR?\fIoption, value, ...\fR?)" 8 | |
1037 | .IX Item "$text->imageConfigure(index, ?option, value, ...?)" | |
1038 | Query or modify the configuration options for an embedded image. | |
1039 | If no \fIoption\fR is specified, returns a list describing all of | |
1040 | the available options for the embedded image at \fIindex\fR | |
1041 | (see Tk::options for information on the format of this list). | |
1042 | If \fIoption\fR is specified with no \fIvalue\fR, then the command | |
1043 | returns a list describing the one named option (this list will be | |
1044 | identical to the corresponding sublist of the value returned if no | |
1045 | \&\fIoption\fR is specified). | |
1046 | If one or more \fIoption-value\fR pairs are specified, then the command | |
1047 | modifies the given option(s) to have the given value(s); in | |
1048 | this case the command returns an empty string. | |
1049 | See \*(L"\s-1EMBEDDED\s0 \s-1IMAGES\s0\*(R" for information on the options that | |
1050 | are supported. | |
1051 | .IP "\fI$text\fR\->\fBimageCreate\fR(\fIindex, \fR?\fIoption, value, ...\fR?)" 8 | |
1052 | .IX Item "$text->imageCreate(index, ?option, value, ...?)" | |
1053 | This command creates a new image annotation, which will appear | |
1054 | in the text at the position given by \fIindex\fR. | |
1055 | Any number of \fIoption-value\fR pairs may be specified to | |
1056 | configure the annotation. | |
1057 | Returns a unique identifier that may be used as an index to refer to | |
1058 | this image. | |
1059 | See \*(L"\s-1EMBEDDED\s0 \s-1IMAGES\s0\*(R" for information on the options that | |
1060 | are supported, and a description of the identifier returned. | |
1061 | .IP "\fI$text\fR\->\fBimageNames\fR" 8 | |
1062 | .IX Item "$text->imageNames" | |
1063 | Returns a list whose elements are the names of all image instances currently | |
1064 | embedded in \f(CW$text\fR. | |
1065 | .RE | |
1066 | .RS 4 | |
1067 | .RE | |
1068 | .IP "\fI$text\fR\->\fBindex\fR(\fIindex\fR)" 4 | |
1069 | .IX Item "$text->index(index)" | |
1070 | Returns the position corresponding to \fIindex\fR in the form | |
1071 | \&\fIline.char\fR where \fIline\fR is the line number and \fIchar\fR | |
1072 | is the character number. | |
1073 | \&\fIIndex\fR may have any of the forms described under \*(L"\s-1INDICES\s0\*(R" above. | |
1074 | .IP "\fI$text\fR\->\fBinsert\fR(\fIindex, chars, \fR?\fItagList, chars, tagList, ...\fR?)" 4 | |
1075 | .IX Item "$text->insert(index, chars, ?tagList, chars, tagList, ...?)" | |
1076 | Inserts all of the \fIchars\fR arguments just before the character at | |
1077 | \&\fIindex\fR. | |
1078 | If \fIindex\fR refers to the end of the text (the character after | |
1079 | the last newline) then the new text is inserted just before the | |
1080 | last newline instead. | |
1081 | If there is a single \fIchars\fR argument and no \fItagList\fR, then | |
1082 | the new text will receive any tags that are present on both the | |
1083 | character before and the character after the insertion point; if a tag | |
1084 | is present on only one of these characters then it will not be | |
1085 | applied to the new text. | |
1086 | If \fItagList\fR is specified then it consists of a list of | |
1087 | tag names; the new characters will receive all of the tags in | |
1088 | this list and no others, regardless of the tags present around | |
1089 | the insertion point. | |
1090 | If multiple \fIchars\fR\-\fItagList\fR argument pairs are present, | |
1091 | they produce the same effect as if a separate \fBinsert\fR widget | |
1092 | command had been issued for each pair, in order. | |
1093 | The last \fItagList\fR argument may be omitted. | |
1094 | .IP "\fI$text\fR\->\fBmark\fR(\fIoption, \fR?\fIarg, arg, ...\fR?)" 4 | |
1095 | .IX Item "$text->mark(option, ?arg, arg, ...?)" | |
1096 | This command is used to manipulate marks. The exact behavior of | |
1097 | the command depends on the \fIoption\fR argument that follows | |
1098 | the \fBmark\fR argument. The following forms of the command | |
1099 | are currently supported: | |
1100 | .RS 4 | |
1101 | .IP "\fI$text\fR\->\fBmarkGravity\fR(\fImarkName, \fR?\fIdirection\fR?)" 8 | |
1102 | .IX Item "$text->markGravity(markName, ?direction?)" | |
1103 | If \fIdirection\fR is not specified, returns \fBleft\fR or \fBright\fR | |
1104 | to indicate which of its adjacent characters \fImarkName\fR is attached | |
1105 | to. | |
1106 | If \fIdirection\fR is specified, it must be \fBleft\fR or \fBright\fR; | |
1107 | the gravity of \fImarkName\fR is set to the given value. | |
1108 | .IP "\fI$text\fR\->\fBmarkNames\fR" 8 | |
1109 | .IX Item "$text->markNames" | |
1110 | Returns a list whose elements are the names of all the marks that | |
1111 | are currently set. | |
1112 | .IP "\fI$text\fR\->\fBmarkNext\fR(\fIindex\fR)" 8 | |
1113 | .IX Item "$text->markNext(index)" | |
1114 | Returns the name of the next mark at or after \fIindex\fR. | |
1115 | If \fIindex\fR is specified in numerical form, then the search for | |
1116 | the next mark begins at that index. | |
1117 | If \fIindex\fR is the name of a mark, then the search for | |
1118 | the next mark begins immediately after that mark. | |
1119 | This can still return a mark at the same position if | |
1120 | there are multiple marks at the same index. | |
1121 | These semantics mean that the \fBmark next\fR operation can be used to | |
1122 | step through all the marks in a text widget in the same order | |
1123 | as the mark information returned by the \fBdump\fR operation. | |
1124 | If a mark has been set to the special \fBend\fR index, | |
1125 | then it appears to be \fIafter\fR \fBend\fR with respect to the \fBmark next\fR operation. | |
1126 | An empty string is returned if there are no marks after \fIindex\fR. | |
1127 | .IP "\fI$text\fR\->\fBmarkPrevious\fR(\fIindex\fR)" 8 | |
1128 | .IX Item "$text->markPrevious(index)" | |
1129 | Returns the name of the mark at or before \fIindex\fR. | |
1130 | If \fIindex\fR is specified in numerical form, then the search for | |
1131 | the previous mark begins with the character just before that index. | |
1132 | If \fIindex\fR is the name of a mark, then the search for | |
1133 | the next mark begins immediately before that mark. | |
1134 | This can still return a mark at the same position if | |
1135 | there are multiple marks at the same index. | |
1136 | These semantics mean that the \fBmark previous\fR operation can be used to | |
1137 | step through all the marks in a text widget in the reverse order | |
1138 | as the mark information returned by the \fBdump\fR operation. | |
1139 | An empty string is returned if there are no marks before \fIindex\fR. | |
1140 | .IP "\fI$text\fR\->\fBmarkSet\fR(\fImarkName, index\fR)" 8 | |
1141 | .IX Item "$text->markSet(markName, index)" | |
1142 | Sets the mark named \fImarkName\fR to a position just before the | |
1143 | character at \fIindex\fR. | |
1144 | If \fImarkName\fR already exists, it is moved from its old position; | |
1145 | if it doesn't exist, a new mark is created. | |
1146 | This command returns an empty string. | |
1147 | .IP "\fI$text\fR\->\fBmarkUnset\fR(\fImarkName\fR?, \fImarkName, markName, ...\fR?)" 8 | |
1148 | .IX Item "$text->markUnset(markName?, markName, markName, ...?)" | |
1149 | Remove the mark corresponding to each of the \fImarkName\fR arguments. | |
1150 | The removed marks will not be usable in indices and will not be | |
1151 | returned by future calls to ``\fI$text\fR\->\fBmarkNames\fR''. | |
1152 | This command returns an empty string. | |
1153 | .RE | |
1154 | .RS 4 | |
1155 | .RE | |
1156 | .IP "\fI$text\fR\->\fBscan\fR(\fIoption\fR, \fIargs\fR) or" 4 | |
1157 | .IX Item "$text->scan(option, args) or" | |
1158 | .PD 0 | |
1159 | .IP "\fI$text\fR\->\fBscan\fR\fIoption\fR(\fIargs\fR)" 4 | |
1160 | .IX Item "$text->scanoption(args)" | |
1161 | .PD | |
1162 | This method is used to implement scanning on texts. It has | |
1163 | two forms, depending on \fIoption\fR: | |
1164 | .RS 4 | |
1165 | .IP "\fI$text\fR\->\fBscanMark\fR(\fIx, y\fR)" 8 | |
1166 | .IX Item "$text->scanMark(x, y)" | |
1167 | Records \fIx\fR and \fIy\fR and the current view in the text window, | |
1168 | for use in conjunction with later \fBscanDragto\fR method. | |
1169 | Typically this method is associated with a mouse button press in | |
1170 | the widget. It returns an empty string. | |
1171 | .IP "\fI$text\fR\->\fBscanDragto\fR(\fIx, y\fR)" 8 | |
1172 | .IX Item "$text->scanDragto(x, y)" | |
1173 | This command computes the difference between its \fIx\fR and \fIy\fR | |
1174 | arguments and the \fIx\fR and \fIy\fR arguments to the last | |
1175 | \&\fBscanMark\fR method for the widget. | |
1176 | It then adjusts the view by 10 times the difference in coordinates. | |
1177 | This command is typically associated | |
1178 | with mouse motion events in the widget, to produce the effect of | |
1179 | dragging the text at high speed through the window. The return | |
1180 | value is an empty string. | |
1181 | .RE | |
1182 | .RS 4 | |
1183 | .RE | |
1184 | .IP "\fI$text\fR\->\fBsearch\fR(?\fIswitches\fR,? \fIpattern, index, \fR?\fIstopIndex\fR?)" 4 | |
1185 | .IX Item "$text->search(?switches,? pattern, index, ?stopIndex?)" | |
1186 | Searches the text in \fI$text\fR starting at \fIindex\fR for a range | |
1187 | of characters that matches \fIpattern\fR. | |
1188 | If a match is found, the index of the first character in the match is | |
1189 | returned as result; otherwise an empty string is returned. | |
1190 | One or more of the following switches (or abbreviations thereof) | |
1191 | may be specified to control the search: | |
1192 | .RS 4 | |
1193 | .IP "\fB\-forwards\fR" 8 | |
1194 | .IX Item "-forwards" | |
1195 | The search will proceed forward through the text, finding the first | |
1196 | matching range starting at or after the position given by \fIindex\fR. | |
1197 | This is the default. | |
1198 | .IP "\fB\-backwards\fR" 8 | |
1199 | .IX Item "-backwards" | |
1200 | The search will proceed backward through the text, finding the | |
1201 | matching range closest to \fIindex\fR whose first character | |
1202 | is before \fIindex\fR. | |
1203 | .IP "\fB\-exact\fR" 8 | |
1204 | .IX Item "-exact" | |
1205 | Use exact matching: the characters in the matching range must be | |
1206 | identical to those in \fIpattern\fR. | |
1207 | This is the default. | |
1208 | .IP "\fB\-regexp\fR" 8 | |
1209 | .IX Item "-regexp" | |
1210 | Treat \fIpattern\fR as a regular expression and match it against | |
1211 | the text using the rules for regular expressions (see the \fBregexp\fR | |
1212 | command for details). | |
1213 | .IP "\fB\-nocase\fR" 8 | |
1214 | .IX Item "-nocase" | |
1215 | Ignore case differences between the pattern and the text. | |
1216 | .IP "\fB\-count\fR\fI varName\fR" 8 | |
1217 | .IX Item "-count varName" | |
1218 | The argument following \fB\-count\fR gives the name of a variable; | |
1219 | if a match is found, the number of characters in the matching | |
1220 | range will be stored in the variable. | |
1221 | .IP "\fB\-hidden\fR" 8 | |
1222 | .IX Item "-hidden" | |
1223 | Find hidden text as well. By default only displayed text is found. | |
1224 | .IP "\fB\-\-\fR" 8 | |
1225 | .IX Item "--" | |
1226 | This switch has no effect except to terminate the list of switches: | |
1227 | the next argument will be treated as \fIpattern\fR even if it starts | |
1228 | with \fB\-\fR. | |
1229 | .RE | |
1230 | .RS 4 | |
1231 | .RE | |
1232 | .PP | |
1233 | The matching range must be entirely within a single line of text. | |
1234 | For regular expression matching the newlines are removed from the ends | |
1235 | of the lines before matching: use the \fB$\fR feature in regular | |
1236 | expressions to match the end of a line. | |
1237 | For exact matching the newlines are retained. | |
1238 | If \fIstopIndex\fR is specified, the search stops at that index: | |
1239 | for forward searches, no match at or after \fIstopIndex\fR will | |
1240 | be considered; for backward searches, no match earlier in the | |
1241 | text than \fIstopIndex\fR will be considered. | |
1242 | If \fIstopIndex\fR is omitted, the entire text will be searched: | |
1243 | when the beginning or end of the text is reached, the search | |
1244 | continues at the other end until the starting location is reached | |
1245 | again; if \fIstopIndex\fR is specified, no wrap-around will occur. | |
1246 | .IP "\fI$text\fR\->\fBsee\fR(\fIindex\fR)" 4 | |
1247 | .IX Item "$text->see(index)" | |
1248 | Adjusts the view in the window so that the character given by \fIindex\fR | |
1249 | is completely visible. | |
1250 | If \fIindex\fR is already visible then the command does nothing. | |
1251 | If \fIindex\fR is a short distance out of view, the command | |
1252 | adjusts the view just enough to make \fIindex\fR visible at the | |
1253 | edge of the window. | |
1254 | If \fIindex\fR is far out of view, then the command centers | |
1255 | \&\fIindex\fR in the window. | |
1256 | .IP "\fI$text\fR\->\fBtag\fR(\fIoption, \fR?\fIarg, arg, ...\fR?)" 4 | |
1257 | .IX Item "$text->tag(option, ?arg, arg, ...?)" | |
1258 | This command is used to manipulate tags. The exact behavior of the | |
1259 | command depends on the \fIoption\fR argument that follows the | |
1260 | \&\fBtag\fR argument. The following forms of the command are currently | |
1261 | supported: | |
1262 | .RS 4 | |
1263 | .IP "\fI$text\fR\->\fBtagAdd\fR(\fItagName, index1, \fR?\fIindex2, index1, index2, ...\fR?)" 8 | |
1264 | .IX Item "$text->tagAdd(tagName, index1, ?index2, index1, index2, ...?)" | |
1265 | Associate the tag \fItagName\fR with all of the characters starting | |
1266 | with \fIindex1\fR and ending just before | |
1267 | \&\fIindex2\fR (the character at \fIindex2\fR isn't tagged). | |
1268 | A single command may contain any number of \fIindex1\fR\-\fIindex2\fR | |
1269 | pairs. | |
1270 | If the last \fIindex2\fR is omitted then the single character at | |
1271 | \&\fIindex1\fR is tagged. | |
1272 | If there are no characters in the specified range (e.g. \fIindex1\fR | |
1273 | is past the end of the file or \fIindex2\fR is less than or equal | |
1274 | to \fIindex1\fR) then the command has no effect. | |
1275 | .IP "\fI$text\fR\->\fBtagBind\fR(\fItagName, \fR?\fIsequence\fR?, ?\fIscript\fR?)" 8 | |
1276 | .IX Item "$text->tagBind(tagName, ?sequence?, ?script?)" | |
1277 | This command associates \fIscript\fR with the tag given by | |
1278 | \&\fItagName\fR. | |
1279 | Whenever the event sequence given by \fIsequence\fR occurs for a | |
1280 | character that has been tagged with \fItagName\fR, | |
1281 | the script will be invoked. | |
1282 | This method is similar to the \fBbind\fR command except that | |
1283 | it operates on characters in a text rather than entire widgets. | |
1284 | See the Tk::bind documentation for complete details | |
1285 | on the syntax of \fIsequence\fR and the substitutions performed | |
1286 | on \fIscript\fR before invoking it. | |
1287 | If all arguments are specified then a new binding is created, replacing | |
1288 | any existing binding for the same \fIsequence\fR and \fItagName\fR | |
1289 | (if the first character of \fIscript\fR is ``+'' then \fIscript\fR | |
1290 | augments an existing binding rather than replacing it). | |
1291 | In this case the return value is an empty string. | |
1292 | If \fIscript\fR is omitted then the command returns the \fIscript\fR | |
1293 | associated with \fItagName\fR and \fIsequence\fR (an error occurs | |
1294 | if there is no such binding). | |
1295 | If both \fIscript\fR and \fIsequence\fR are omitted then the command | |
1296 | returns a list of all the sequences for which bindings have been | |
1297 | defined for \fItagName\fR. | |
1298 | .Sp | |
1299 | The only events for which bindings may be specified are those related | |
1300 | to the mouse and keyboard (such as \fBEnter\fR, \fBLeave\fR, | |
1301 | \&\fBButtonPress\fR, \fBMotion\fR, and \fBKeyPress\fR) or virtual events. | |
1302 | Event bindings for a text widget use the \fBcurrent\fR mark described | |
1303 | under \*(L"\s-1MARKS\s0\*(R" above. An \fBEnter\fR event triggers for a tag when the tag | |
1304 | first becomes present on the current character, and a \fBLeave\fR event | |
1305 | triggers for a tag when it ceases to be present on the current character. | |
1306 | \&\fBEnter\fR and \fBLeave\fR events can happen either because the | |
1307 | \&\fBcurrent\fR mark moved or because the character at that position | |
1308 | changed. Note that these events are different than \fBEnter\fR and | |
1309 | \&\fBLeave\fR events for windows. Mouse and keyboard events are directed | |
1310 | to the current character. If a virtual event is used in a binding, that | |
1311 | binding can trigger only if the virtual event is defined by an underlying | |
1312 | mouse-related or keyboard-related event. | |
1313 | .Sp | |
1314 | It is possible for the current character to have multiple tags, | |
1315 | and for each of them to have a binding for a particular event | |
1316 | sequence. | |
1317 | When this occurs, one binding is invoked for each tag, in order | |
1318 | from lowest-priority to highest priority. | |
1319 | If there are multiple matching bindings for a single tag, then | |
1320 | the most specific binding is chosen (see the the documentation for | |
1321 | the \fBbind\fR command for details). | |
1322 | \&\fBcontinue\fR and \fBbreak\fR commands within binding scripts | |
1323 | are processed in the same way as for bindings created with | |
1324 | the \fBbind\fR command. | |
1325 | .Sp | |
1326 | If bindings are created for the widget as a whole using the | |
1327 | \&\fBbind\fR command, then those bindings will supplement the | |
1328 | tag bindings. | |
1329 | The tag bindings will be invoked first, followed by bindings | |
1330 | for the window as a whole. | |
1331 | .IP "\fI$text\fR\->\fBtagCget\fR(\fItagName, option\fR)" 8 | |
1332 | .IX Item "$text->tagCget(tagName, option)" | |
1333 | This command returns the current value of the option named \fIoption\fR | |
1334 | associated with the tag given by \fItagName\fR. | |
1335 | \&\fIOption\fR may have any of the values accepted by the \fBtag configure\fR | |
1336 | method. | |
1337 | .IP "\fI$text\fR\->\fBtagConfigure\fR(\fItagName, \fR?\fIoption\fR?, ?\fIvalue\fR?, ?\fIoption, value, ...\fR?)" 8 | |
1338 | .IX Item "$text->tagConfigure(tagName, ?option?, ?value?, ?option, value, ...?)" | |
1339 | This command is similar to the \fBconfigure\fR method except | |
1340 | that it modifies options associated with the tag given by \fItagName\fR | |
1341 | instead of modifying options for the overall text widget. | |
1342 | If no \fIoption\fR is specified, the command returns a list describing | |
1343 | all of the available options for \fItagName\fR | |
1344 | (see Tk::options for information on the format of this list). | |
1345 | If \fIoption\fR is specified with no \fIvalue\fR, then the command returns | |
1346 | a list describing the one named option (this list will be identical to | |
1347 | the corresponding sublist of the value returned if no \fIoption\fR | |
1348 | is specified). | |
1349 | If one or more \fIoption-value\fR pairs are specified, then the command | |
1350 | modifies the given option(s) to have the given value(s) in \fItagName\fR; | |
1351 | in this case the command returns an empty string. | |
1352 | See \*(L"\s-1TAGS\s0\*(R" above for details on the options available for tags. | |
1353 | .IP "\fI$text\fR\->\fBtagDelete\fR(\fItagName, \fR?\fItagName, ...\fR?)" 8 | |
1354 | .IX Item "$text->tagDelete(tagName, ?tagName, ...?)" | |
1355 | Deletes all tag information for each of the \fItagName\fR | |
1356 | arguments. | |
1357 | The command removes the tags from all characters in the file | |
1358 | and also deletes any other information associated with the tags, | |
1359 | such as bindings and display information. | |
1360 | The command returns an empty string. | |
1361 | .IP "\fI$text\fR\->\fBtagLower\fR(\fItagName\fR?, \fIbelowThis\fR?)" 8 | |
1362 | .IX Item "$text->tagLower(tagName?, belowThis?)" | |
1363 | Changes the priority of tag \fItagName\fR so that it is just lower | |
1364 | in priority than the tag whose name is \fIbelowThis\fR. | |
1365 | If \fIbelowThis\fR is omitted, then \fItagName\fR's priority | |
1366 | is changed to make it lowest priority of all tags. | |
1367 | .IP "\fI$text\fR\->\fBtagNames\fR(?\fIindex\fR?)" 8 | |
1368 | .IX Item "$text->tagNames(?index?)" | |
1369 | Returns a list whose elements are the names of all the tags that | |
1370 | are active at the character position given by \fIindex\fR. | |
1371 | If \fIindex\fR is omitted, then the return value will describe | |
1372 | all of the tags that exist for the text (this includes all tags | |
1373 | that have been named in a ``\fI$text\fR\->\fBtag\fR'' widget | |
1374 | command but haven't been deleted by a ``\fI$text\fR\->\fBtagDelete\fR'' | |
1375 | method, even if no characters are currently marked with | |
1376 | the tag). | |
1377 | The list will be sorted in order from lowest priority to highest | |
1378 | priority. | |
1379 | .IP "\fI$text\fR\->\fBtagNextrange\fR(\fItagName, index1, \fR?\fIindex2\fR?)" 8 | |
1380 | .IX Item "$text->tagNextrange(tagName, index1, ?index2?)" | |
1381 | This command searches the text for a range of characters tagged | |
1382 | with \fItagName\fR where the first character of the range is | |
1383 | no earlier than the character at \fIindex1\fR and no later than | |
1384 | the character just before \fIindex2\fR (a range starting at | |
1385 | \&\fIindex2\fR will not be considered). | |
1386 | If several matching ranges exist, the first one is chosen. | |
1387 | The command's return value is a list containing | |
1388 | two elements, which are the index of the first character of the | |
1389 | range and the index of the character just after the last one in | |
1390 | the range. | |
1391 | If no matching range is found then the return value is an | |
1392 | empty string. | |
1393 | If \fIindex2\fR is not given then it defaults to the end of the text. | |
1394 | .IP "\fI$text\fR\->\fBtagPrevrange\fR(\fItagName, index1, \fR?\fIindex2\fR?)" 8 | |
1395 | .IX Item "$text->tagPrevrange(tagName, index1, ?index2?)" | |
1396 | This command searches the text for a range of characters tagged | |
1397 | with \fItagName\fR where the first character of the range is | |
1398 | before the character at \fIindex1\fR and no earlier than | |
1399 | the character at \fIindex2\fR (a range starting at | |
1400 | \&\fIindex2\fR will be considered). | |
1401 | If several matching ranges exist, the one closest to \fIindex1\fR is chosen. | |
1402 | The command's return value is a list containing | |
1403 | two elements, which are the index of the first character of the | |
1404 | range and the index of the character just after the last one in | |
1405 | the range. | |
1406 | If no matching range is found then the return value is an | |
1407 | empty string. | |
1408 | If \fIindex2\fR is not given then it defaults to the beginning of the text. | |
1409 | .IP "\fI$text\fR\->\fBtagRaise\fR(\fItagName, \fR?\fIaboveThis\fR?)" 8 | |
1410 | .IX Item "$text->tagRaise(tagName, ?aboveThis?)" | |
1411 | Changes the priority of tag \fItagName\fR so that it is just higher | |
1412 | in priority than the tag whose name is \fIaboveThis\fR. | |
1413 | If \fIaboveThis\fR is omitted, then \fItagName\fR's priority | |
1414 | is changed to make it highest priority of all tags. | |
1415 | .IP "\fI$text\fR\->\fBtagRanges\fR(\fItagName\fR)" 8 | |
1416 | .IX Item "$text->tagRanges(tagName)" | |
1417 | Returns a list describing all of the ranges of text that have been | |
1418 | tagged with \fItagName\fR. | |
1419 | The first two elements of the list describe the first tagged range | |
1420 | in the text, the next two elements describe the second range, and | |
1421 | so on. | |
1422 | The first element of each pair contains the index of the first | |
1423 | character of the range, and the second element of the pair contains | |
1424 | the index of the character just after the last one in the | |
1425 | range. | |
1426 | If there are no characters tagged with \fItag\fR then an | |
1427 | empty string is returned. | |
1428 | .IP "\fI$text\fR\->\fBtagRemove\fR(\fItagName, index1, \fR?\fIindex2, index1, index2, ...\fR?)" 8 | |
1429 | .IX Item "$text->tagRemove(tagName, index1, ?index2, index1, index2, ...?)" | |
1430 | Remove the tag \fItagName\fR from all of the characters starting | |
1431 | at \fIindex1\fR and ending just before | |
1432 | \&\fIindex2\fR (the character at \fIindex2\fR isn't affected). | |
1433 | A single command may contain any number of \fIindex1\fR\-\fIindex2\fR | |
1434 | pairs. | |
1435 | If the last \fIindex2\fR is omitted then the single character at | |
1436 | \&\fIindex1\fR is tagged. | |
1437 | If there are no characters in the specified range (e.g. \fIindex1\fR | |
1438 | is past the end of the file or \fIindex2\fR is less than or equal | |
1439 | to \fIindex1\fR) then the command has no effect. | |
1440 | This command returns an empty string. | |
1441 | .RE | |
1442 | .RS 4 | |
1443 | .RE | |
1444 | .IP "\fI$text\fR\->\fBwidget\fR(\fIoption?, arg, arg, ...\fR?)" 4 | |
1445 | .IX Item "$text->widget(option?, arg, arg, ...?)" | |
1446 | .PD 0 | |
1447 | .IP "\fI$text\fR\->\fBwidget\fR\fIOption\fR(?\fIarg, arg, ...\fR?)" 4 | |
1448 | .IX Item "$text->widgetOption(?arg, arg, ...?)" | |
1449 | .PD | |
1450 | This method is used to manipulate embedded windows. | |
1451 | The behavior of the method depends on the \fIoption\fR argument | |
1452 | that follows the \fBwindow\fR argument. | |
1453 | The following forms of the method are currently supported: | |
1454 | .RS 4 | |
1455 | .IP "\fI$text\fR\->\fBwindowCget\fR(\fIindex, option\fR)" 8 | |
1456 | .IX Item "$text->windowCget(index, option)" | |
1457 | Returns the value of a configuration option for an embedded window. | |
1458 | \&\fIIndex\fR identifies the embedded window, and \fIoption\fR | |
1459 | specifies a particular configuration option, which must be one of | |
1460 | the ones listed in \*(L"\s-1EMBEDDED\s0 \s-1WINDOWS\s0\*(R" above. | |
1461 | .IP "\fI$text\fR\->\fBwindowConfigure\fR(\fIindex\fR?, \fIoption, value, ...\fR?)" 8 | |
1462 | .IX Item "$text->windowConfigure(index?, option, value, ...?)" | |
1463 | Query or modify the configuration options for an embedded window. | |
1464 | If no \fIoption\fR is specified, returns a list describing all of | |
1465 | the available options for the embedded window at \fIindex\fR | |
1466 | (see Tk::options for information on the format of this list). | |
1467 | If \fIoption\fR is specified with no \fIvalue\fR, then the command | |
1468 | returns a list describing the one named option (this list will be | |
1469 | identical to the corresponding sublist of the value returned if no | |
1470 | \&\fIoption\fR is specified). | |
1471 | If one or more \fIoption-value\fR pairs are specified, then the command | |
1472 | modifies the given option(s) to have the given value(s); in | |
1473 | this case the command returns an empty string. | |
1474 | See \*(L"\s-1EMBEDDED\s0 \s-1WINDOWS\s0\*(R" above for information on the options that | |
1475 | are supported. | |
1476 | .IP "\fI$text\fR\->\fBwindowCreate\fR(\fIindex\fR?, \fIoption, value, ...\fR?)" 8 | |
1477 | .IX Item "$text->windowCreate(index?, option, value, ...?)" | |
1478 | This command creates a new window annotation, which will appear | |
1479 | in the text at the position given by \fIindex\fR. | |
1480 | Any number of \fIoption-value\fR pairs may be specified to | |
1481 | configure the annotation. | |
1482 | See \*(L"\s-1EMBEDDED\s0 \s-1WINDOWS\s0\*(R" above for information on the options that | |
1483 | are supported. | |
1484 | Returns an empty string. | |
1485 | .IP "\fI$text\fR\->\fBwindowNames\fR" 8 | |
1486 | .IX Item "$text->windowNames" | |
1487 | Returns a list whose elements are the names of all windows currently | |
1488 | embedded in \f(CW$text\fR. | |
1489 | .RE | |
1490 | .RS 4 | |
1491 | .RE | |
1492 | .IP "\fI$text\fR\->\fBxview\fR(\fIoption, args\fR)" 4 | |
1493 | .IX Item "$text->xview(option, args)" | |
1494 | This command is used to query and change the horizontal position of the | |
1495 | text in the widget's window. It can take any of the following | |
1496 | forms: | |
1497 | .RS 4 | |
1498 | .IP "\fI$text\fR\->\fBxview\fR" 8 | |
1499 | .IX Item "$text->xview" | |
1500 | Returns a list containing two elements. | |
1501 | Each element is a real fraction between 0 and 1; together they describe | |
1502 | the portion of the document's horizontal span that is visible in | |
1503 | the window. | |
1504 | For example, if the first element is .2 and the second element is .6, | |
1505 | 20% of the text is off-screen to the left, the middle 40% is visible | |
1506 | in the window, and 40% of the text is off-screen to the right. | |
1507 | The fractions refer only to the lines that are actually visible in the | |
1508 | window: if the lines in the window are all very short, so that they | |
1509 | are entirely visible, the returned fractions will be 0 and 1, | |
1510 | even if there are other lines in the text that are | |
1511 | much wider than the window. | |
1512 | These are the same values passed to scrollbars via the \fB\-xscrollcommand\fR | |
1513 | option. | |
1514 | .IP "\fI$text\fR\->\fBxviewMoveto\fR(\fIfraction\fR)" 8 | |
1515 | .IX Item "$text->xviewMoveto(fraction)" | |
1516 | Adjusts the view in the window so that \fIfraction\fR of the horizontal | |
1517 | span of the text is off-screen to the left. | |
1518 | \&\fIFraction\fR is a fraction between 0 and 1. | |
1519 | .IP "\fI$text\fR\->\fBxviewScroll\fR(\fInumber, what\fR)" 8 | |
1520 | .IX Item "$text->xviewScroll(number, what)" | |
1521 | This command shifts the view in the window left or right according to | |
1522 | \&\fInumber\fR and \fIwhat\fR. | |
1523 | \&\fINumber\fR must be an integer. | |
1524 | \&\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an abbreviation | |
1525 | of one of these. | |
1526 | If \fIwhat\fR is \fBunits\fR, the view adjusts left or right by | |
1527 | \&\fInumber\fR average-width characters on the display; if it is | |
1528 | \&\fBpages\fR then the view adjusts by \fInumber\fR screenfuls. | |
1529 | If \fInumber\fR is negative then characters farther to the left | |
1530 | become visible; if it is positive then characters farther to the right | |
1531 | become visible. | |
1532 | .RE | |
1533 | .RS 4 | |
1534 | .RE | |
1535 | .IP "\fI$text\fR\->\fByview\fR(\fI?args\fR?)" 4 | |
1536 | .IX Item "$text->yview(?args?)" | |
1537 | This command is used to query and change the vertical position of the | |
1538 | text in the widget's window. | |
1539 | It can take any of the following forms: | |
1540 | .RS 4 | |
1541 | .IP "\fI$text\fR\->\fByview\fR" 8 | |
1542 | .IX Item "$text->yview" | |
1543 | Returns a list containing two elements, both of which are real fractions | |
1544 | between 0 and 1. | |
1545 | The first element gives the position of the first character in the | |
1546 | top line in the window, relative to the text as a whole (0.5 means | |
1547 | it is halfway through the text, for example). | |
1548 | The second element gives the position of the character just after | |
1549 | the last one in the bottom line of the window, | |
1550 | relative to the text as a whole. | |
1551 | These are the same values passed to scrollbars via the \fB\-yscrollcommand\fR | |
1552 | option. | |
1553 | .IP "\fI$text\fR\->\fByviewMoveto\fR(\fIfraction\fR)" 8 | |
1554 | .IX Item "$text->yviewMoveto(fraction)" | |
1555 | Adjusts the view in the window so that the character given by \fIfraction\fR | |
1556 | appears on the top line of the window. | |
1557 | \&\fIFraction\fR is a fraction between 0 and 1; 0 indicates the first | |
1558 | character in the text, 0.33 indicates the character one-third the | |
1559 | way through the text, and so on. | |
1560 | .IP "\fI$text\fR\->\fByviewScroll\fR(\fInumber, what\fR)" 8 | |
1561 | .IX Item "$text->yviewScroll(number, what)" | |
1562 | This command adjust the view in the window up or down according to | |
1563 | \&\fInumber\fR and \fIwhat\fR. | |
1564 | \&\fINumber\fR must be an integer. | |
1565 | \&\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. | |
1566 | If \fIwhat\fR is \fBunits\fR, the view adjusts up or down by | |
1567 | \&\fInumber\fR lines on the display; if it is \fBpages\fR then | |
1568 | the view adjusts by \fInumber\fR screenfuls. | |
1569 | If \fInumber\fR is negative then earlier positions in the text | |
1570 | become visible; if it is positive then later positions in the text | |
1571 | become visible. | |
1572 | .IP "\fI$text\fR\->\fByview\fR(?\fB\-pickplace\fR,? \fIindex\fR)" 8 | |
1573 | .IX Item "$text->yview(?-pickplace,? index)" | |
1574 | Changes the view in the \fI$text\fR's window to make \fIindex\fR visible. | |
1575 | If the \fB\-pickplace\fR option isn't specified then \fIindex\fR will | |
1576 | appear at the top of the window. | |
1577 | If \fB\-pickplace\fR is specified then the widget chooses where | |
1578 | \&\fIindex\fR appears in the window: | |
1579 | .RS 8 | |
1580 | .IP "[1]" 12 | |
1581 | .IX Item "[1]" | |
1582 | If \fIindex\fR is already visible somewhere in the window then the | |
1583 | command does nothing. | |
1584 | .IP "[2]" 12 | |
1585 | .IX Item "[2]" | |
1586 | If \fIindex\fR is only a few lines off-screen above the window then | |
1587 | it will be positioned at the top of the window. | |
1588 | .IP "[3]" 12 | |
1589 | .IX Item "[3]" | |
1590 | If \fIindex\fR is only a few lines off-screen below the window then | |
1591 | it will be positioned at the bottom of the window. | |
1592 | .IP "[4]" 12 | |
1593 | .IX Item "[4]" | |
1594 | Otherwise, \fIindex\fR will be centered in the window. | |
1595 | .RE | |
1596 | .RS 8 | |
1597 | .RE | |
1598 | .RE | |
1599 | .RS 4 | |
1600 | .RE | |
1601 | .PP | |
1602 | The \fB\-pickplace\fR option has been obsoleted by the \fBsee\fR widget | |
1603 | command (\fBsee\fR handles both x\- and y\-motion to make a location | |
1604 | visible, whereas \fB\-pickplace\fR only handles motion in y). | |
1605 | .IP "\fI$text\fR\->\fByview\fR(\fInumber\fR)" 4 | |
1606 | .IX Item "$text->yview(number)" | |
1607 | This command makes the first character on the line after | |
1608 | the one given by \fInumber\fR visible at the top of the window. | |
1609 | \&\fINumber\fR must be an integer. | |
1610 | This command used to be used for scrolling, but now it is obsolete. | |
1611 | .SH "BINDINGS" | |
1612 | .IX Header "BINDINGS" | |
1613 | Tk automatically creates class bindings for texts that give them | |
1614 | the following default behavior. | |
1615 | In the descriptions below, ``word'' refers to a contiguous group | |
1616 | of letters, digits, or ``_'' characters, or any single character | |
1617 | other than these. | |
1618 | .IP "[1]" 4 | |
1619 | .IX Item "[1]" | |
1620 | Clicking mouse button 1 positions the insertion cursor | |
1621 | just before the character underneath the mouse cursor, sets the | |
1622 | input focus to this widget, and clears any selection in the widget. | |
1623 | Dragging with mouse button 1 strokes out a selection between | |
1624 | the insertion cursor and the character under the mouse. | |
1625 | .IP "[2]" 4 | |
1626 | .IX Item "[2]" | |
1627 | Double-clicking with mouse button 1 selects the word under the mouse | |
1628 | and positions the insertion cursor at the beginning of the word. | |
1629 | Dragging after a double click will stroke out a selection consisting | |
1630 | of whole words. | |
1631 | .IP "[3]" 4 | |
1632 | .IX Item "[3]" | |
1633 | Triple-clicking with mouse button 1 selects the line under the mouse | |
1634 | and positions the insertion cursor at the beginning of the line. | |
1635 | Dragging after a triple click will stroke out a selection consisting | |
1636 | of whole lines. | |
1637 | .IP "[4]" 4 | |
1638 | .IX Item "[4]" | |
1639 | The ends of the selection can be adjusted by dragging with mouse | |
1640 | button 1 while the Shift key is down; this will adjust the end | |
1641 | of the selection that was nearest to the mouse cursor when button | |
1642 | 1 was pressed. | |
1643 | If the button is double-clicked before dragging then the selection | |
1644 | will be adjusted in units of whole words; if it is triple-clicked | |
1645 | then the selection will be adjusted in units of whole lines. | |
1646 | .IP "[5]" 4 | |
1647 | .IX Item "[5]" | |
1648 | Clicking mouse button 1 with the Control key down will reposition the | |
1649 | insertion cursor without affecting the selection. | |
1650 | .IP "[6]" 4 | |
1651 | .IX Item "[6]" | |
1652 | If any normal printing characters are typed, they are | |
1653 | inserted at the point of the insertion cursor. | |
1654 | .IP "[7]" 4 | |
1655 | .IX Item "[7]" | |
1656 | The view in the widget can be adjusted by dragging with mouse button 2. | |
1657 | If mouse button 2 is clicked without moving the mouse, the selection | |
1658 | is copied into the text at the position of the mouse cursor. | |
1659 | The Insert key also inserts the selection, but at the position of | |
1660 | the insertion cursor. | |
1661 | .IP "[8]" 4 | |
1662 | .IX Item "[8]" | |
1663 | If the mouse is dragged out of the widget | |
1664 | while button 1 is pressed, the entry will automatically scroll to | |
1665 | make more text visible (if there is more text off-screen on the side | |
1666 | where the mouse left the window). | |
1667 | .IP "[9]" 4 | |
1668 | .IX Item "[9]" | |
1669 | The Left and Right keys move the insertion cursor one character to the | |
1670 | left or right; they also clear any selection in the text. | |
1671 | If Left or Right is typed with the Shift key down, then the insertion | |
1672 | cursor moves and the selection is extended to include the new character. | |
1673 | Control-Left and Control-Right move the insertion cursor by words, and | |
1674 | Control-Shift-Left and Control-Shift-Right move the insertion cursor | |
1675 | by words and also extend the selection. | |
1676 | Control-b and Control-f behave the same as Left and Right, respectively. | |
1677 | Meta-b and Meta-f behave the same as Control-Left and Control\-Right, | |
1678 | respectively. | |
1679 | .IP "[10]" 4 | |
1680 | .IX Item "[10]" | |
1681 | The Up and Down keys move the insertion cursor one line up or | |
1682 | down and clear any selection in the text. | |
1683 | If Up or Right is typed with the Shift key down, then the insertion | |
1684 | cursor moves and the selection is extended to include the new character. | |
1685 | Control-Up and Control-Down move the insertion cursor by paragraphs (groups | |
1686 | of lines separated by blank lines), and | |
1687 | Control-Shift-Up and Control-Shift-Down move the insertion cursor | |
1688 | by paragraphs and also extend the selection. | |
1689 | Control-p and Control-n behave the same as Up and Down, respectively. | |
1690 | .IP "[11]" 4 | |
1691 | .IX Item "[11]" | |
1692 | The Next and Prior keys move the insertion cursor forward or backwards | |
1693 | by one screenful and clear any selection in the text. | |
1694 | If the Shift key is held down while Next or Prior is typed, then | |
1695 | the selection is extended to include the new character. | |
1696 | Control-v moves the view down one screenful without moving the | |
1697 | insertion cursor or adjusting the selection. | |
1698 | .IP "[12]" 4 | |
1699 | .IX Item "[12]" | |
1700 | Control-Next and Control-Prior scroll the view right or left by one page | |
1701 | without moving the insertion cursor or affecting the selection. | |
1702 | .IP "[13]" 4 | |
1703 | .IX Item "[13]" | |
1704 | Home and Control-a move the insertion cursor to the | |
1705 | beginning of its line and clear any selection in the widget. | |
1706 | Shift-Home moves the insertion cursor to the beginning of the line | |
1707 | and also extends the selection to that point. | |
1708 | .IP "[14]" 4 | |
1709 | .IX Item "[14]" | |
1710 | End and Control-e move the insertion cursor to the | |
1711 | end of the line and clear any selection in the widget. | |
1712 | Shift-End moves the cursor to the end of the line and extends the selection | |
1713 | to that point. | |
1714 | .IP "[15]" 4 | |
1715 | .IX Item "[15]" | |
1716 | Control-Home and Meta\-< move the insertion cursor to the beginning of | |
1717 | the text and clear any selection in the widget. | |
1718 | Control-Shift-Home moves the insertion cursor to the beginning of the text | |
1719 | and also extends the selection to that point. | |
1720 | .IP "[16]" 4 | |
1721 | .IX Item "[16]" | |
1722 | Control-End and Meta\-> move the insertion cursor to the end of the | |
1723 | text and clear any selection in the widget. | |
1724 | Control-Shift-End moves the cursor to the end of the text and extends | |
1725 | the selection to that point. | |
1726 | .IP "[17]" 4 | |
1727 | .IX Item "[17]" | |
1728 | The Select key and Control-Space set the selection anchor to the position | |
1729 | of the insertion cursor. They don't affect the current selection. | |
1730 | Shift-Select and Control-Shift-Space adjust the selection to the | |
1731 | current position of the insertion cursor, selecting from the anchor | |
1732 | to the insertion cursor if there was not any selection previously. | |
1733 | .IP "[18]" 4 | |
1734 | .IX Item "[18]" | |
1735 | Control\-/ selects the entire contents of the widget. | |
1736 | .IP "[19]" 4 | |
1737 | .IX Item "[19]" | |
1738 | Control\-\e clears any selection in the widget. | |
1739 | .IP "[20]" 4 | |
1740 | .IX Item "[20]" | |
1741 | The F16 key (labelled Copy on many Sun workstations) or Meta-w | |
1742 | copies the selection in the widget to the clipboard, if there is a selection. | |
1743 | .IP "[21]" 4 | |
1744 | .IX Item "[21]" | |
1745 | The F20 key (labelled Cut on many Sun workstations) or Control-w | |
1746 | copies the selection in the widget to the clipboard and deletes | |
1747 | the selection. | |
1748 | If there is no selection in the widget then these keys have no effect. | |
1749 | .IP "[22]" 4 | |
1750 | .IX Item "[22]" | |
1751 | The F18 key (labelled Paste on many Sun workstations) or Control-y | |
1752 | inserts the contents of the clipboard at the position of the | |
1753 | insertion cursor. | |
1754 | .IP "[23]" 4 | |
1755 | .IX Item "[23]" | |
1756 | The Delete key deletes the selection, if there is one in the widget. | |
1757 | If there is no selection, it deletes the character to the right of | |
1758 | the insertion cursor. | |
1759 | .IP "[24]" 4 | |
1760 | .IX Item "[24]" | |
1761 | Backspace and Control-h delete the selection, if there is one | |
1762 | in the widget. | |
1763 | If there is no selection, they delete the character to the left of | |
1764 | the insertion cursor. | |
1765 | .IP "[25]" 4 | |
1766 | .IX Item "[25]" | |
1767 | Control-d deletes the character to the right of the insertion cursor. | |
1768 | .IP "[26]" 4 | |
1769 | .IX Item "[26]" | |
1770 | Meta-d deletes the word to the right of the insertion cursor. | |
1771 | .IP "[27]" 4 | |
1772 | .IX Item "[27]" | |
1773 | Control-k deletes from the insertion cursor to the end of its line; | |
1774 | if the insertion cursor is already at the end of a line, then | |
1775 | Control-k deletes the newline character. | |
1776 | .IP "[28]" 4 | |
1777 | .IX Item "[28]" | |
1778 | Control-o opens a new line by inserting a newline character in | |
1779 | front of the insertion cursor without moving the insertion cursor. | |
1780 | .IP "[29]" 4 | |
1781 | .IX Item "[29]" | |
1782 | Meta-backspace and Meta-Delete delete the word to the left of the | |
1783 | insertion cursor. | |
1784 | .IP "[30]" 4 | |
1785 | .IX Item "[30]" | |
1786 | Control-x deletes whatever is selected in the text widget. | |
1787 | .IP "[31]" 4 | |
1788 | .IX Item "[31]" | |
1789 | Control-t reverses the order of the two characters to the right of | |
1790 | the insertion cursor. | |
1791 | .Sp | |
1792 | If the widget is disabled using the \fB\-state\fR option, then its | |
1793 | view can still be adjusted and text can still be selected, | |
1794 | but no insertion cursor will be displayed and no text modifications will | |
1795 | take place. | |
1796 | .Sp | |
1797 | The behavior of texts can be changed by defining new bindings for | |
1798 | individual widgets or by redefining the class bindings. | |
1799 | .SH "PERFORMANCE ISSUES" | |
1800 | .IX Header "PERFORMANCE ISSUES" | |
1801 | Text widgets should run efficiently under a variety | |
1802 | of conditions. The text widget uses about 2\-3 bytes of | |
1803 | main memory for each byte of text, so texts containing a megabyte | |
1804 | or more should be practical on most workstations. | |
1805 | Text is represented internally with a modified B\-tree structure | |
1806 | that makes operations relatively efficient even with large texts. | |
1807 | Tags are included in the B\-tree structure in a way that allows | |
1808 | tags to span large ranges or have many disjoint smaller ranges | |
1809 | without loss of efficiency. | |
1810 | Marks are also implemented in a way that allows large numbers of | |
1811 | marks. | |
1812 | In most cases it is fine to have large numbers of unique tags, | |
1813 | or a tag that has many distinct ranges. | |
1814 | .PP | |
1815 | One performance problem can arise if you have hundreds or thousands | |
1816 | of different tags that all have the following characteristics: | |
1817 | the first and last ranges of each tag are near the beginning and | |
1818 | end of the text, respectively, | |
1819 | or a single tag range covers most of the text widget. | |
1820 | The cost of adding and deleting tags like this is proportional | |
1821 | to the number of other tags with the same properties. | |
1822 | In contrast, there is no problem with having thousands of distinct | |
1823 | tags if their overall ranges are localized and spread uniformly throughout | |
1824 | the text. | |
1825 | .PP | |
1826 | Very long text lines can be expensive, | |
1827 | especially if they have many marks and tags within them. | |
1828 | .PP | |
1829 | The display line with the insert cursor is redrawn each time the | |
1830 | cursor blinks, which causes a steady stream of graphics traffic. | |
1831 | Set the \fB\-insertofftime\fR option to 0 avoid this. | |
1832 | .SH "SEE ALSO" | |
1833 | .IX Header "SEE ALSO" | |
1834 | Tk::ROText | |
1835 | Tk::TextUndo | |
1836 | .SH "KEYWORDS" | |
1837 | .IX Header "KEYWORDS" | |
1838 | text, widget |