1*textprop.txt* For Vim version 8.2. Last change: 2021 Aug 16 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Displaying text with properties attached. *textprop* *text-properties* 8 9 101. Introduction |text-prop-intro| 112. Functions |text-prop-functions| 123. When text changes |text-prop-changes| 13 14 15{not able to use text properties when the |+textprop| feature was 16disabled at compile time} 17 18============================================================================== 191. Introduction *text-prop-intro* 20 21Text properties can be attached to text in a buffer. They will move with the 22text: If lines are deleted or inserted the properties move with the text they 23are attached to. Also when inserting/deleting text in the line before the 24text property. And when inserting/deleting text inside the text property, it 25will increase/decrease in size. 26 27The main use for text properties is to highlight text. This can be seen as a 28replacement for syntax highlighting. Instead of defining patterns to match 29the text, the highlighting is set by a script, possibly using the output of an 30external parser. This only needs to be done once, not every time when 31redrawing the screen, thus can be much faster, after the initial cost of 32attaching the text properties. 33 34Text properties can also be used for other purposes to identify text. For 35example, add a text property on a function name, so that a search can be 36defined to jump to the next/previous function. 37 38A text property is attached at a specific line and column, and has a specified 39length. The property can span multiple lines. 40 41A text property has these fields: 42 "id" a number to be used as desired 43 "type" the name of a property type 44 45 46Property Types ~ 47 *E971* 48A text property normally has the name of a property type, which defines 49how 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 63Example ~ 64 65Suppose line 11 in a buffer has this text (excluding the indent): 66 67 The number 123 is smaller than 4567. 68 69To 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 74Try inserting or deleting lines above the text, you will see that the text 75properties stick to the text, thus the line number is adjusted as needed. 76 77Setting "start_incl" and "end_incl" is useful when white space surrounds the 78text, e.g. for a function name. Using false is useful when the text starts 79and/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 87Nevertheless, when text is inserted or deleted the text may need to be parsed 88and the text properties updated. But this can be done asynchronously. 89 90 91Internal error *E967* 92 93If you see E967, please report the bug. You can do this at Github: 94https://github.com/vim/vim/issues/new 95 96============================================================================== 972. Functions *text-prop-functions* 98 99Manipulating text property types: 100 101prop_type_add({name}, {props}) define a new property type 102prop_type_change({name}, {props}) change an existing property type 103prop_type_delete({name} [, {props}]) delete a property type 104prop_type_get({name} [, {props}]) get property type values 105prop_type_list([{props}]) get list of property types 106 107 108Manipulating text properties: 109 110prop_add({lnum}, {col}, {props}) add a text property 111prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) 112 add a text property at multiple 113 positions. 114prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) 115 remove all text properties 116prop_find({props} [, {direction}]) search for a text property 117prop_list({lnum} [, {props}]) text properties in {lnum} 118prop_remove({props} [, {lnum} [, {lnum-end}]]) 119 remove a text property 120 121 *prop_add()* *E965* 122prop_add({lnum}, {col}, {props}) 123 Attach a text property at position {lnum}, {col}. {col} is 124 counted in bytes, use one for the first column. 125 If {lnum} is invalid an error is given. *E966* 126 If {col} is invalid an error is given. *E964* 127 128 {props} is a dictionary with these fields: 129 length length of text in bytes, can only be used 130 for a property that does not continue in 131 another line; can be zero 132 end_lnum line number for the end of text (inclusive) 133 end_col column just after the text; not used when 134 "length" is present; when {col} and "end_col" 135 are equal, and "end_lnum" is omitted or equal 136 to {lnum}, this is a zero-width text property 137 bufnr buffer to add the property to; when omitted 138 the current buffer is used 139 id user defined ID for the property; must be a 140 number; when omitted zero is used 141 type name of the text property type 142 All fields except "type" are optional. 143 144 It is an error when both "length" and "end_lnum" or "end_col" 145 are given. Either use "length" or "end_col" for a property 146 within one line, or use "end_lnum" and "end_col" for a 147 property that spans more than one line. 148 When neither "length" nor "end_col" are given the property 149 will be zero-width. That means it will move with the text, as 150 a kind of mark. One character will be highlighted, if the 151 type specifies highlighting. 152 The property can end exactly at the last character of the 153 text, or just after it. In the last case, if text is appended 154 to the line, the text property size will increase, also when 155 the property type does not have "end_incl" set. 156 157 "type" will first be looked up in the buffer the property is 158 added to. When not found, the global property types are used. 159 If not found an error is given. 160 161 Can also be used as a |method|: > 162 GetLnum()->prop_add(col, props) 163< 164 *prop_add_list()* 165prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) 166 Similar to prop_add(), but attaches a text property at 167 multiple positions in a buffer. 168 169 {props} is a dictionary with these fields: 170 bufnr buffer to add the property to; when omitted 171 the current buffer is used 172 id user defined ID for the property; must be a 173 number; when omitted zero is used 174 type name of the text property type 175 All fields except "type" are optional. 176 177 The second argument is a List of Lists where each list 178 specifies the starting and ending position of the text. The 179 first two items {lnum} and {col} specify the starting position 180 of the text where the property will be attached and the last 181 two items {end-lnum} and {end-col} specify the position just 182 after the text. 183 184 Example: 185 call prop_add_list(#{type: 'MyProp', id: 2}, 186 \ [[1, 4, 1, 7], 187 \ [1, 15, 1, 20], 188 \ [2, 30, 3, 30]] 189 190 Can also be used as a |method|: > 191 GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) 192 193 194prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* 195 Remove all text properties from line {lnum}. 196 When {lnum-end} is given, remove all text properties from line 197 {lnum} to {lnum-end} (inclusive). 198 199 When {props} contains a "bufnr" item use this buffer, 200 otherwise use the current buffer. 201 202 Can also be used as a |method|: > 203 GetLnum()->prop_clear() 204< 205 *prop_find()* 206prop_find({props} [, {direction}]) 207 Search for a text property as specified with {props}: 208 id property with this ID 209 type property with this type name 210 both "id" and "type" must both match 211 bufnr buffer to search in; when present a 212 start position with "lnum" and "col" 213 must be given; when omitted the 214 current buffer is used 215 lnum start in this line (when omitted start 216 at the cursor) 217 col start at this column (when omitted 218 and "lnum" is given: use column 1, 219 otherwise start at the cursor) 220 skipstart do not look for a match at the start 221 position 222 223 A property matches when either "id" or "type" matches. 224 {direction} can be "f" for forward and "b" for backward. When 225 omitted forward search is performed. 226 227 If a match is found then a Dict is returned with the entries 228 as with prop_list(), and additionally an "lnum" entry. 229 If no match is found then an empty Dict is returned. 230 231 232prop_list({lnum} [, {props}]) *prop_list()* 233 Return a List with all text properties in line {lnum}. 234 235 When {props} contains a "bufnr" item, use this buffer instead 236 of the current buffer. 237 238 The properties are ordered by starting column and priority. 239 Each property is a Dict with these entries: 240 col starting column 241 length length in bytes, one more if line break is 242 included 243 id property ID 244 type name of the property type, omitted if 245 the type was deleted 246 type_bufnr buffer number for which this type was defined; 247 0 if the type is global 248 start when TRUE property starts in this line 249 end when TRUE property ends in this line 250 251 When "start" is zero the property started in a previous line, 252 the current one is a continuation. 253 When "end" is zero the property continues in the next line. 254 The line break after this line is included. 255 256 Can also be used as a |method|: > 257 GetLnum()->prop_list() 258< 259 *prop_remove()* *E968* *E860* 260prop_remove({props} [, {lnum} [, {lnum-end}]]) 261 Remove a matching text property from line {lnum}. When 262 {lnum-end} is given, remove matching text properties from line 263 {lnum} to {lnum-end} (inclusive). 264 When {lnum} is omitted remove matching text properties from 265 all lines (this requires going over all lines, thus will be a 266 bit slow for a buffer with many lines). 267 268 {props} is a dictionary with these fields: 269 id remove text properties with this ID 270 type remove text properties with this type name 271 both "id" and "type" must both match 272 bufnr use this buffer instead of the current one 273 all when TRUE remove all matching text properties, 274 not just the first one 275 A property matches when either "id" or "type" matches. 276 If buffer "bufnr" does not exist you get an error message. 277 If buffer "bufnr" is not loaded then nothing happens. 278 279 Returns the number of properties that were removed. 280 281 Can also be used as a |method|: > 282 GetProps()->prop_remove() 283 284 285prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* 286 Add a text property type {name}. If a property type with this 287 name already exists an error is given. Nothing is returned. 288 {props} is a dictionary with these optional fields: 289 bufnr define the property only for this buffer; this 290 avoids name collisions and automatically 291 clears the property types when the buffer is 292 deleted. 293 highlight name of highlight group to use 294 priority when a character has multiple text 295 properties the one with the highest priority 296 will be used; negative values can be used, the 297 default priority is zero 298 combine when omitted or TRUE combine the highlight 299 with any syntax highlight; when FALSE syntax 300 highlight will not be used 301 start_incl when TRUE inserts at the start position will 302 be included in the text property 303 end_incl when TRUE inserts at the end position will be 304 included in the text property 305 306 Can also be used as a |method|: > 307 GetPropName()->prop_type_add(props) 308 309prop_type_change({name}, {props}) *prop_type_change()* 310 Change properties of an existing text property type. If a 311 property with this name does not exist an error is given. 312 The {props} argument is just like |prop_type_add()|. 313 314 Can also be used as a |method|: > 315 GetPropName()->prop_type_change(props) 316 317prop_type_delete({name} [, {props}]) *prop_type_delete()* 318 Remove the text property type {name}. When text properties 319 using the type {name} are still in place, they will not have 320 an effect and can no longer be removed by name. 321 322 {props} can contain a "bufnr" item. When it is given, delete 323 a property type from this buffer instead of from the global 324 property types. 325 326 When text property type {name} is not found there is no error. 327 328 Can also be used as a |method|: > 329 GetPropName()->prop_type_delete() 330 331prop_type_get({name} [, {props}]) *prop_type_get()* 332 Returns the properties of property type {name}. This is a 333 dictionary with the same fields as was given to 334 prop_type_add(). 335 When the property type {name} does not exist, an empty 336 dictionary is returned. 337 338 {props} can contain a "bufnr" item. When it is given, use 339 this buffer instead of the global property types. 340 341 Can also be used as a |method|: > 342 GetPropName()->prop_type_get() 343 344prop_type_list([{props}]) *prop_type_list()* 345 Returns a list with all property type names. 346 347 {props} can contain a "bufnr" item. When it is given, use 348 this buffer instead of the global property types. 349 350 351============================================================================== 3523. When text changes *text-prop-changes* 353 354Vim will do its best to keep the text properties on the text where it was 355attached. When inserting or deleting text the properties after the change 356will move accordingly. 357 358When text is deleted and a text property no longer includes any text, it is 359deleted. However, a text property that was defined as zero-width will remain, 360unless the whole line is deleted. 361 *E275* 362When a buffer is unloaded, all the text properties are gone. There is no way 363to store the properties in a file. You can only re-create them. When a 364buffer is hidden the text is preserved and so are the text properties. It is 365not possible to add text properties to an unloaded buffer. 366 367When using replace mode, the text properties stay on the same character 368positions, even though the characters themselves change. 369 370To update text properties after the text was changed, install a callback with 371`listener_add()`. E.g, if your plugin does spell checking, you can have the 372callback update spelling mistakes in the changed text. Vim will move the 373properties below the changed text, so that they still highlight the same text, 374thus you don't need to update these. 375 376 377Text property columns are not updated or copied: ~ 378 379- When setting the line with |setline()| or through an interface, such as Lua, 380 Tcl or Python. Vim does not know what text got inserted or deleted. 381- With a command like `:move`, which takes a line of text out of context. 382 383 384 vim:tw=78:ts=8:noet:ft=help:norl: 385