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