1*textprop.txt* For Vim version 8.1. Last change: 2019 Dec 07 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_clear({lnum} [, {lnum-end} [, {bufnr}]]) 112 remove all text properties 113prop_find({props} [, {direction}]) search for a text property 114prop_list({lnum} [, {props}) text properties in {lnum} 115prop_remove({props} [, {lnum} [, {lnum-end}]]) 116 remove a text property 117 118 *prop_add()* *E965* 119prop_add({lnum}, {col}, {props}) 120 Attach a text property at position {lnum}, {col}. {col} is 121 counted in bytes, use one for the first column. 122 If {lnum} is invalid an error is given. *E966* 123 If {col} is invalid an error is given. *E964* 124 125 {props} is a dictionary with these fields: 126 length length of text in bytes, can only be used 127 for a property that does not continue in 128 another line; can be zero 129 end_lnum line number for the end of text 130 end_col column just after the text; not used when 131 "length" is present; when {col} and "end_col" 132 are equal, and "end_lnum" is omitted or equal 133 to {lnum}, this is a zero-width text property 134 bufnr buffer to add the property to; when omitted 135 the current buffer is used 136 id user defined ID for the property; when omitted 137 zero is used 138 type name of the text property type 139 All fields except "type" are optional. 140 141 It is an error when both "length" and "end_lnum" or "end_col" 142 are given. Either use "length" or "end_col" for a property 143 within one line, or use "end_lnum" and "end_col" for a 144 property that spans more than one line. 145 When neither "length" nor "end_col" are given the property 146 will be zero-width. That means it will not be highlighted but 147 will move with the text, as a kind of mark. 148 The property can end exactly at the last character of the 149 text, or just after it. In the last case, if text is appended 150 to the line, the text property size will increase, also when 151 the property type does not have "end_incl" set. 152 153 "type" will first be looked up in the buffer the property is 154 added to. When not found, the global property types are used. 155 If not found an error is given. 156 157 See |text-properties| for information about text properties. 158 159 Can also be used as a |method|: > 160 GetLnum()->prop_add(col, props) 161 162 163prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()* 164 Remove all text properties from line {lnum}. 165 When {lnum-end} is given, remove all text properties from line 166 {lnum} to {lnum-end} (inclusive). 167 168 When {props} contains a "bufnr" item use this buffer, 169 otherwise use the current buffer. 170 171 See |text-properties| for information about text properties. 172 173 Can also be used as a |method|: > 174 GetLnum()->prop_clear() 175< 176 *prop_find()* 177prop_find({props} [, {direction}]) 178 {not implemented yet} 179 Search for a text property as specified with {props}: 180 id property with this ID 181 type property with this type name 182 bufnr buffer to search in; when present a 183 start position with "lnum" and "col" 184 must be given; when omitted the 185 current buffer is used 186 lnum start in this line (when omitted start 187 at the cursor) 188 col start at this column (when omitted 189 and "lnum" is given: use column 1, 190 otherwise start at the cursor) 191 skipstart do not look for a match at the start 192 position 193 194 {direction} can be "f" for forward and "b" for backward. When 195 omitted forward search is performed. 196 197 If a match is found then a Dict is returned with the entries 198 as with prop_list(), and additionally an "lnum" entry. 199 If no match is found then an empty Dict is returned. 200 201 See |text-properties| for information about text properties. 202 203 204prop_list({lnum} [, {props}]) *prop_list()* 205 Return a List with all text properties in line {lnum}. 206 207 When {props} contains a "bufnr" item, use this buffer instead 208 of the current buffer. 209 210 The properties are ordered by starting column and priority. 211 Each property is a Dict with these entries: 212 col starting column 213 length length in bytes, one more if line break is 214 included 215 id property ID 216 type name of the property type, omitted if 217 the type was deleted 218 start when TRUE property starts in this line 219 end when TRUE property ends in this line 220 221 When "start" is zero the property started in a previous line, 222 the current one is a continuation. 223 When "end" is zero the property continues in the next line. 224 The line break after this line is included. 225 226 See |text-properties| for information about text properties. 227 228 Can also be used as a |method|: > 229 GetLnum()->prop_list() 230< 231 *prop_remove()* *E968* 232prop_remove({props} [, {lnum} [, {lnum-end}]]) 233 Remove a matching text property from line {lnum}. When 234 {lnum-end} is given, remove matching text properties from line 235 {lnum} to {lnum-end} (inclusive). 236 When {lnum} is omitted remove matching text properties from 237 all lines. 238 239 {props} is a dictionary with these fields: 240 id remove text properties with this ID 241 type remove text properties with this type name 242 bufnr use this buffer instead of the current one 243 all when TRUE remove all matching text properties, 244 not just the first one 245 A property matches when either "id" or "type" matches. 246 If buffer "bufnr" does not exist you get an error message. 247 If buffer "bufnr" is not loaded then nothing happens. 248 249 Returns the number of properties that were removed. 250 251 See |text-properties| for information about text properties. 252 253 Can also be used as a |method|: > 254 GetProps()->prop_remove() 255 256 257prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* 258 Add a text property type {name}. If a property type with this 259 name already exists an error is given. Nothing is returned. 260 {props} is a dictionary with these optional fields: 261 bufnr define the property only for this buffer; this 262 avoids name collisions and automatically 263 clears the property types when the buffer is 264 deleted. 265 highlight name of highlight group to use 266 priority when a character has multiple text 267 properties the one with the highest priority 268 will be used; negative values can be used, the 269 default priority is zero 270 combine when TRUE combine the highlight with any 271 syntax highlight; when omitted or FALSE syntax 272 highlight will not be used 273 start_incl when TRUE inserts at the start position will 274 be included in the text property 275 end_incl when TRUE inserts at the end position will be 276 included in the text property 277 278 See |text-properties| for information about text properties. 279 280 Can also be used as a |method|: > 281 GetPropName()->prop_type_add(props) 282 283prop_type_change({name}, {props}) *prop_type_change()* 284 Change properties of an existing text property type. If a 285 property with this name does not exist an error is given. 286 The {props} argument is just like |prop_type_add()|. 287 288 See |text-properties| for information about text properties. 289 290 Can also be used as a |method|: > 291 GetPropName()->prop_type_change(props) 292 293prop_type_delete({name} [, {props}]) *prop_type_delete()* 294 Remove the text property type {name}. When text properties 295 using the type {name} are still in place, they will not have 296 an effect and can no longer be removed by name. 297 298 {props} can contain a "bufnr" item. When it is given, delete 299 a property type from this buffer instead of from the global 300 property types. 301 302 When text property type {name} is not found there is no error. 303 304 See |text-properties| for information about text properties. 305 306 Can also be used as a |method|: > 307 GetPropName()->prop_type_delete() 308 309prop_type_get([{name} [, {props}]) *prop_type_get()* 310 Returns the properties of property type {name}. This is a 311 dictionary with the same fields as was given to 312 prop_type_add(). 313 When the property type {name} does not exist, an empty 314 dictionary is returned. 315 316 {props} can contain a "bufnr" item. When it is given, use 317 this buffer instead of the global property types. 318 319 See |text-properties| for information about text properties. 320 321 Can also be used as a |method|: > 322 GetPropName()->prop_type_get() 323 324prop_type_list([{props}]) *prop_type_list()* 325 Returns a list with all property type names. 326 327 {props} can contain a "bufnr" item. When it is given, use 328 this buffer instead of the global property types. 329 330 See |text-properties| for information about text properties. 331 332 333============================================================================== 3343. When text changes *text-prop-changes* 335 336Vim will do its best to keep the text properties on the text where it was 337attached. When inserting or deleting text the properties after the change 338will move accordingly. 339 340When text is deleted and a text property no longer includes any text, it is 341deleted. However, a text property that was defined as zero-width will remain, 342unless the whole line is deleted. 343 *E275* 344When a buffer is unloaded, all the text properties are gone. There is no way 345to store the properties in a file. You can only re-create them. When a 346buffer is hidden the text is preserved and so are the text properties. It is 347not possible to add text properties to an unloaded buffer. 348 349When using replace mode, the text properties stay on the same character 350positions, even though the characters themselves change. 351 352To update text properties after the text was changed, install a callback with 353`listener_add()`. E.g, if your plugin does spell checking, you can have the 354callback update spelling mistakes in the changed text. Vim will move the 355properties below the changed text, so that they still highlight the same text, 356thus you don't need to update these. 357 358 359Text property columns are not updated: ~ 360 361- When setting the line with |setline()| or through an interface, such as Lua, 362 Tcl or Python. Vim does not know what text got inserted or deleted. 363 364 365 vim:tw=78:ts=8:noet:ft=help:norl: 366