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