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