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