textprop.txt (20834B)
1 *textprop.txt* For Vim version 9.2. Last change: 2026 May 31 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Displaying text with properties attached. *textprop* *text-properties* 8 9 10 1. Introduction |text-prop-intro| 11 2. Functions |text-prop-functions| 12 3. When text changes |text-prop-changes| 13 14 15 {not able to use text properties when the |+textprop| feature was 16 disabled at compile time} 17 18 ============================================================================== 19 1. Introduction *text-prop-intro* 20 21 Text properties can be attached to text in a buffer. They will move with the 22 text: If lines are deleted or inserted the properties move with the text they 23 are attached to. Also when inserting/deleting text in the line before the 24 text property. And when inserting/deleting text inside the text property, it 25 will increase/decrease in size. 26 27 The main use for text properties is to highlight text. This can be seen as a 28 replacement for syntax highlighting. Instead of defining patterns to match 29 the text, the highlighting is set by a script, possibly using the output of an 30 external parser. This only needs to be done once, not every time when 31 redrawing the screen, thus can be much faster, after the initial cost of 32 attaching the text properties. 33 34 Text properties can also be used for other purposes to identify text. For 35 example, add a text property on a function name, so that a search can be 36 defined to jump to the next/previous function. 37 38 A text property is attached at a specific line and column, and has a specified 39 length. The property can span multiple lines. 40 41 A text property has these fields: 42 "id" a number to be used as desired 43 "type" the name of a property type 44 45 46 Property Types ~ 47 *E971* 48 A text property normally has the name of a property type, which defines 49 how to highlight the text. The property type can have these entries: 50 "highlight" name of the highlight group to use 51 "combine" when omitted or TRUE the text property highlighting is 52 combined with any syntax highlighting; when FALSE the 53 text property highlighting replaces the syntax 54 highlighting 55 "priority" when properties overlap, the one with the highest 56 priority will be used. 57 "start_incl" when TRUE inserts at the start position will be 58 included in the text property 59 "end_incl" when TRUE inserts at the end position will be 60 included in the text property 61 62 63 Example ~ 64 65 Suppose line 11 in a buffer has this text (excluding the indent): 66 67 The number 123 is smaller than 4567. 68 69 To highlight the numbers in this text: > 70 call prop_type_add('number', {'highlight': 'Constant'}) 71 call prop_add(11, 12, {'length': 3, 'type': 'number'}) 72 call prop_add(11, 32, {'length': 4, 'type': 'number'}) 73 74 Try inserting or deleting lines above the text, you will see that the text 75 properties stick to the text, thus the line number is adjusted as needed. 76 77 Setting "start_incl" and "end_incl" is useful when white space surrounds the 78 text, e.g. for a function name. Using false is useful when the text starts 79 and/or ends with a specific character, such as the quote surrounding a string. 80 81 func FuncName(arg) ~ 82 ^^^^^^^^ property with start_incl and end_incl set 83 84 var = "text"; ~ 85 ^^^^^^ property with start_incl and end_incl not set 86 87 Nevertheless, when text is inserted or deleted the text may need to be parsed 88 and the text properties updated. But this can be done asynchronously. 89 90 91 Internal error *E967* 92 93 If you see E967, please report the bug. You can do this at Github: 94 https://github.com/vim/vim/issues/new 95 96 ============================================================================== 97 2. Functions *text-prop-functions* 98 99 Manipulating text property types: 100 101 prop_type_add({name}, {props}) define a new property type 102 prop_type_change({name}, {props}) change an existing property type 103 prop_type_delete({name} [, {props}]) delete a property type 104 prop_type_get({name} [, {props}]) get property type values 105 prop_type_list([{props}]) get list of property types 106 107 108 Manipulating text properties: 109 110 prop_add({lnum}, {col}, {props}) add a text property 111 prop_add_list({props}, [{item}, ...]) 112 add a text property at multiple 113 positions. 114 prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) 115 remove all text properties 116 prop_find({props} [, {direction}]) search for a text property 117 prop_list({lnum} [, {props}]) text properties in {lnum} 118 prop_remove({props} [, {lnum} [, {lnum-end}]]) 119 remove a text property 120 121 *text-prop-functions-details* 122 123 *prop_add()* *E965* 124 prop_add({lnum}, {col}, {props}) 125 Attach a text property at position {lnum}, {col}. {col} is 126 counted in bytes, use one for the first column. 127 If {lnum} is invalid an error is given. *E966* 128 If {col} is invalid an error is given. *E964* 129 130 {props} is a dictionary with these fields: 131 type name of the text property type 132 length length of text in bytes, can only be used 133 for a property that does not continue in 134 another line; can be zero 135 end_lnum line number for the end of text (inclusive) 136 end_col column just after the text; not used when 137 "length" is present; when {col} and "end_col" 138 are equal, and "end_lnum" is omitted or equal 139 to {lnum}, this is a zero-width text property 140 bufnr buffer to add the property to; when omitted 141 the current buffer is used 142 id user defined ID for the property; must be a 143 number, should be positive |E1510|; 144 when using "text" then any "id" value is 145 ignored and a negative number is assigned 146 automatically; otherwise zero is used 147 *E1305* 148 text text to be displayed before {col}, or 149 above/below the line if {col} is zero; prepend 150 and/or append spaces for padding with 151 highlighting; cannot be used with "length", 152 "end_lnum" and "end_col" 153 See |virtual-text| for more information. 154 *E1294* 155 text_align when "text" is present and {col} is zero; 156 specifies where to display the text: 157 after after the end of the line 158 right right aligned in the window (unless 159 the text wraps to the next screen 160 line) 161 below in the next screen line 162 above just above the line 163 When omitted "after" is used. Only one 164 "right" property can fit in each line, if 165 there are two or more these will go in a 166 separate line (still right aligned). 167 text_padding_left *E1296* 168 used when "text" is present and {col} is zero; 169 padding between the end of the text line 170 (leftmost column for "above" and "below") and 171 the virtual text, not highlighted 172 text_wrap when "text" is present and {col} is zero, 173 specifies what happens if the text doesn't 174 fit: 175 wrap wrap the text to the next line 176 truncate truncate the text to make it fit 177 When omitted "truncate" is used. 178 Note that this applies to the individual text 179 property, the 'wrap' option sets the overall 180 behavior. "wrap" only takes effect when the 181 'wrap' option is set; with 'nowrap' the text 182 is truncated at the right edge of the window. 183 All fields except "type" are optional. 184 185 It is an error when both "length" and "end_lnum" or "end_col" 186 are given. Either use "length" or "end_col" for a property 187 within one line, or use "end_lnum" and "end_col" for a 188 property that spans more than one line. 189 When neither "length" nor "end_col" are given the property 190 will be zero-width. That means it will move with the text, as 191 a kind of mark. One character will be highlighted, if the 192 type specifies highlighting. 193 The property can end exactly at the last character of the 194 text, or just after it. In the last case, if text is appended 195 to the line, the text property size will increase, also when 196 the property type does not have "end_incl" set. 197 198 "type" will first be looked up in the buffer the property is 199 added to. When not found, the global property types are used. 200 If not found an error is given. 201 *virtual-text* 202 When "text" is used and the column is non-zero then this text 203 will be displayed at the specified start location of the text 204 property. The text of the buffer line will be shifted to make 205 room. This is called "virtual text". 206 When the column is zero the virtual text will appear above, 207 after or below the buffer text. The "text_align" and 208 "text_wrap" arguments determine how it is displayed. 209 To separate the virtual text from the buffer text prepend 210 and/or append spaces to the "text" field or use the 211 "text_padding_left" value. 212 213 Make sure to use a highlight that makes clear to the user that 214 this is virtual text, otherwise it will be very confusing that 215 the text cannot be edited. When using "above" you need to 216 make clear this text belongs to the text line below it, when 217 using "below" you need to make sure it belongs to the text 218 line above it. 219 220 The text will be displayed but it is not part of the actual 221 buffer line, the cursor cannot be placed on it. A mouse click 222 in the text will move the cursor to the first character after 223 the text, or the last character of the line. 224 Any Tab and other control character in the text will be 225 changed to a space (Rationale: otherwise the size of the text 226 is difficult to compute). 227 A negative "id" will be chosen and is returned. 228 229 Negative "id"s are reserved for text properties with "text" 230 and cannot be used otherwise. Using a negative "id" results 231 in *E1293* . 232 233 Can also be used as a |method|: > 234 GetLnum()->prop_add(col, props) 235 < 236 Return type: |Number| 237 238 239 prop_add_list({props}, [{item}, ...]) *prop_add_list()* 240 Similar to prop_add(), but attaches a text property at 241 multiple positions in a buffer. 242 243 {props} is a dictionary with these fields: 244 bufnr buffer to add the property to; when omitted 245 the current buffer is used 246 id user defined ID for the property; must be a 247 number; when omitted zero is used 248 type name of the text property type 249 All fields except "type" are optional. 250 251 The second argument is a List of items, where each {item} is a 252 list that specifies the starting and ending position of the 253 text: [{lnum}, {col}, {end-lnum}, {end-col}] 254 or: [{lnum}, {col}, {end-lnum}, {end-col}, {id}] 255 256 The first two items {lnum} and {col} specify the starting 257 position of the text where the property will be attached. 258 The next two items {end-lnum} and {end-col} specify the 259 position just after the text. 260 An optional fifth item {id} can be used to give a different ID 261 to a property. When omitted the ID from {props} is used, 262 falling back to zero if none are present. 263 264 It is not possible to add a text property with a "text" field 265 here. 266 267 Example: > 268 call prop_add_list(#{type: 'MyProp', id: 2}, 269 \ [[1, 4, 1, 7], 270 \ [1, 15, 1, 20], 271 \ [2, 30, 3, 30]]) 272 < 273 Can also be used as a |method|: > 274 GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) 275 < 276 Return type: void 277 278 279 prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* 280 Remove all text properties from line {lnum}. 281 When {lnum-end} is given, remove all text properties from line 282 {lnum} to {lnum-end} (inclusive). 283 284 When {props} contains a "bufnr" item use this buffer, 285 otherwise use the current buffer. 286 287 Can also be used as a |method|: > 288 GetLnum()->prop_clear() 289 < 290 Return type: void 291 292 293 prop_find({props} [, {direction}]) *prop_find()* 294 Search for a text property as specified with {props}: 295 id property with this ID 296 type property with this type name 297 both "id" and "type" must both match 298 bufnr buffer to search in; when present a 299 start position with "lnum" and "col" 300 must be given; when omitted the 301 current buffer is used 302 lnum start in this line (when omitted start 303 at the cursor) 304 col start at this column (when omitted 305 and "lnum" is given: use column 1, 306 otherwise start at the cursor) 307 skipstart do not look for a match at the start 308 position 309 310 A property matches when either "id" or "type" matches. 311 {direction} can be "f" for forward and "b" for backward. When 312 omitted forward search is performed. 313 314 If a match is found then a Dict is returned with the entries 315 as with prop_list(), and additionally an "lnum" entry. 316 If no match is found then an empty Dict is returned. 317 318 Return type: dict<any> 319 320 321 prop_list({lnum} [, {props}]) *prop_list()* 322 Returns a List with all the text properties in line {lnum}. 323 324 The following optional items are supported in {props}: 325 bufnr use this buffer instead of the current buffer 326 end_lnum return text properties in all the lines 327 between {lnum} and {end_lnum} (inclusive). 328 A negative value is used as an offset from the 329 last buffer line; -1 refers to the last buffer 330 line. 331 types List of property type names. Return only text 332 properties that match one of the type names. 333 ids List of property identifiers. Return only 334 text properties with one of these identifiers. 335 336 The properties are ordered by starting column and priority. 337 Each property is a Dict with these entries: 338 lnum starting line number. Present only when 339 returning text properties between {lnum} and 340 {end_lnum}. 341 col starting column 342 length length in bytes, one more if line break is 343 included 344 id property ID 345 text text to be displayed before {col}. Only 346 present for |virtual-text| properties. 347 text_align alignment property of |virtual-text|. 348 text_padding_left 349 left padding used for virtual text. 350 text_wrap specifies whether |virtual-text| is wrapped. 351 type name of the property type, omitted if 352 the type was deleted 353 type_bufnr buffer number for which this type was defined; 354 0 if the type is global 355 start when TRUE property starts in this line 356 end when TRUE property ends in this line 357 358 When "start" is zero the property started in a previous line, 359 the current one is a continuation. 360 When "end" is zero the property continues in the next line. 361 The line break after this line is included. 362 363 Returns an empty list on error. 364 365 Examples: > 366 " get text properties placed in line 5 367 echo prop_list(5) 368 " get text properties placed in line 20 in buffer 4 369 echo prop_list(20, {'bufnr': 4}) 370 " get all the text properties between line 1 and 20 371 echo prop_list(1, {'end_lnum': 20}) 372 " get all the text properties of type 'myprop' 373 echo prop_list(1, {'types': ['myprop'], 374 \ 'end_lnum': -1}) 375 " get all the text properties of type 'prop1' or 'prop2' 376 echo prop_list(1, {'types': ['prop1', 'prop2'], 377 \ 'end_lnum': -1}) 378 " get all the text properties with ID 8 379 echo prop_list(1, {'ids': [8], 'end_lnum': line('$')}) 380 " get all the text properties with ID 10 and 20 381 echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1}) 382 " get text properties with type 'myprop' and ID 100 383 " in buffer 4. 384 echo prop_list(1, {'bufnr': 4, 'types': ['myprop'], 385 \ 'ids': [100], 'end_lnum': -1}) 386 < 387 Can also be used as a |method|: > 388 GetLnum()->prop_list() 389 < 390 Return type: list<dict<any>> or list<any> 391 392 *prop_remove()* *E968* *E860* 393 prop_remove({props} [, {lnum} [, {lnum-end}]]) 394 Remove a matching text property from line {lnum}. When 395 {lnum-end} is given, remove matching text properties from line 396 {lnum} to {lnum-end} (inclusive). 397 When {lnum} is omitted remove matching text properties from 398 all lines (this requires going over all lines, thus will be a 399 bit slow for a buffer with many lines). 400 401 {props} is a dictionary with these fields: 402 id remove text properties with this ID 403 type remove text properties with this type name 404 types remove text properties with type names in this 405 List 406 both "id" and "type"/"types" must both match 407 bufnr use this buffer instead of the current one 408 all when TRUE remove all matching text properties, 409 not just the first one 410 Only one of "type" and "types" may be supplied. *E1295* 411 412 A property matches when either "id" or one of the supplied 413 types matches. 414 If buffer "bufnr" does not exist you get an error message. 415 If buffer "bufnr" is not loaded then nothing happens. 416 417 Returns the number of properties that were removed. 418 419 Can also be used as a |method|: > 420 GetProps()->prop_remove() 421 < 422 Return type: |Number| 423 424 425 prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* 426 Add a text property type {name}. If a property type with this 427 name already exists an error is given. Nothing is returned. 428 {props} is a dictionary with these optional fields: 429 bufnr define the property only for this buffer; this 430 avoids name collisions and automatically 431 clears the property types when the buffer is 432 deleted. 433 highlight name of highlight group to use 434 priority when a character has multiple text 435 properties the one with the highest priority 436 will be used; negative values can be used, the 437 default priority is zero 438 combine when omitted or TRUE combine the highlight 439 with any syntax highlight; when FALSE syntax 440 highlight will not be used 441 override when TRUE the highlight overrides any other, 442 including 'cursorline' and Visual 443 start_incl when TRUE inserts at the start position will 444 be included in the text property 445 end_incl when TRUE inserts at the end position will be 446 included in the text property 447 448 Can also be used as a |method|: > 449 GetPropName()->prop_type_add(props) 450 < 451 Return type: void 452 453 454 prop_type_change({name}, {props}) *prop_type_change()* 455 Change properties of an existing text property type. If a 456 property with this name does not exist an error is given. 457 The {props} argument is just like |prop_type_add()|. 458 459 Can also be used as a |method|: > 460 GetPropName()->prop_type_change(props) 461 < 462 Return type: void 463 464 465 prop_type_delete({name} [, {props}]) *prop_type_delete()* 466 Remove the text property type {name}. When text properties 467 using the type {name} are still in place, they will not have 468 an effect and can no longer be removed by name. 469 470 {props} can contain a "bufnr" item. When it is given, delete 471 a property type from this buffer instead of from the global 472 property types. 473 474 When text property type {name} is not found there is no error. 475 476 Can also be used as a |method|: > 477 GetPropName()->prop_type_delete() 478 < 479 Return type: void 480 481 482 prop_type_get({name} [, {props}]) *prop_type_get()* 483 Returns the properties of property type {name}. This is a 484 dictionary with the same fields as was given to 485 prop_type_add(). 486 When the property type {name} does not exist, an empty 487 dictionary is returned. 488 489 {props} can contain a "bufnr" item. When it is given, use 490 this buffer instead of the global property types. 491 492 Can also be used as a |method|: > 493 GetPropName()->prop_type_get() 494 < 495 Return type: dict<any> 496 497 498 prop_type_list([{props}]) *prop_type_list()* 499 Returns a list with all property type names. 500 501 {props} can contain a "bufnr" item. When it is given, use 502 this buffer instead of the global property types. 503 504 Return type: list<string> or list<any> 505 506 507 ============================================================================== 508 3. When text changes *text-prop-changes* 509 510 Vim will do its best to keep the text properties on the text where it was 511 attached. When inserting or deleting text the properties after the change 512 will move accordingly. 513 514 When text is deleted and a text property no longer includes any text, it is 515 deleted. However, a text property that was defined as zero-width will remain, 516 unless the whole line is deleted. When lines are joined by a multi-line 517 substitute command, virtual text properties on the deleted lines are moved to 518 the resulting joined line. 519 *E275* 520 When a buffer is unloaded, all the text properties are gone. There is no way 521 to store the properties in a file. You can only re-create them. When a 522 buffer is hidden the text is preserved and so are the text properties. It is 523 not possible to add text properties to an unloaded buffer. 524 525 When using replace mode, the text properties stay on the same character 526 positions, even though the characters themselves change. 527 528 To update text properties after the text was changed, install a callback with 529 `listener_add()`. E.g, if your plugin does spell checking, you can have the 530 callback update spelling mistakes in the changed text. Vim will move the 531 properties below the changed text, so that they still highlight the same text, 532 thus you don't need to update these. 533 534 *text-prop-cleared* 535 Text property columns are not updated or copied: ~ 536 537 - When setting the line with |setline()| or through an interface, such as Lua, 538 Tcl or Python. Vim does not know what text got inserted or deleted. 539 - With a command like `:move`, which takes a line of text out of context. 540 541 542 vim:tw=78:ts=8:noet:ft=help:norl: