| 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 |