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