1*textprop.txt* For Vim version 8.1. Last change: 2019 Jan 08 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Displaying text with properties attached. *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- callbacks when text properties are outdated 16 17 181. Introduction |text-prop-intro| 192. Functions |text-prop-functions| 203. When text changes |text-prop-changes| 21 22 23{Vi does not have text properties} 24{not able to use text properties when the |+textprop| feature was 25disabled at compile time} 26 27============================================================================== 281. Introduction *text-prop-intro* 29 30Text properties can be attached to text in a buffer. They will move with the 31text: If lines are deleted or inserted the properties move with the text they 32are attached to. Also when inserting/deleting text in the line before the 33text property. And when inserting/deleting text inside the text property, it 34will increase/decrease in size. 35 36The main use for text properties is to highlight text. This can be seen as a 37replacement for syntax highlighting. Instead of defining patterns to match 38the text, the highlighting is set by a script, possibly using the output of an 39external parser. This only needs to be done once, not every time when 40redrawing the screen, thus can be much faster, after the initial cost of 41attaching the text properties. 42 43Text properties can also be used for other purposes to identify text. For 44example, add a text property on a function name, so that a search can be 45defined to jump to the next/previous function. 46 47A text property is attached at a specific line and column, and has a specified 48length. The property can span multiple lines. 49 50A text property has these fields: 51 "id" a number to be used as desired 52 "type" the name of a property type 53 54 55Property Types ~ 56 *E971* 57A text property normally has the name of a property type, which defines 58how to highlight the text. The property type can have these entries: 59 "highlight" name of the highlight group to use 60 "priority" when properties overlap, the one with the highest 61 priority will be used. 62 "start_incl" when TRUE inserts at the start position will be 63 included in the text property 64 "end_incl" when TRUE inserts at the end position will be 65 included in the text property 66 67 68Example ~ 69 70Suppose line 11 in a buffer has this text (excluding the indent): 71 72 The number 123 is smaller than 4567. 73 74To highlight the numbers in this text: > 75 call prop_type_add('number', {'highlight': 'Constant'}) 76 call prop_add(11, 12, {'length': 3, 'type': 'number'}) 77 call prop_add(11, 32, {'length': 4, 'type': 'number'}) 78 79Try inserting or deleting lines above the text, you will see that the text 80properties stick to the text, thus the line number is adjusted as needed. 81 82Setting "start_incl" and "end_incl" is useful when white space surrounds the 83text, e.g. for a function name. Using false is useful when the text starts 84and/or ends with a specific character, such as the quote surrounding a string. 85 86 func FuncName(arg) ~ 87 ^^^^^^^^ property with start_incl and end_incl set 88 89 var = "text"; ~ 90 ^^^^^^ property with start_incl and end_incl not set 91 92Nevertheless, when text is inserted or deleted the text may need to be parsed 93and the text properties updated. But this can be done asynchronously. 94 95============================================================================== 962. Functions *text-prop-functions* 97 98Manipulating text property types: 99 100prop_type_add({name}, {props}) define a new property type 101prop_type_change({name}, {props}) change an existing property type 102prop_type_delete({name} [, {props}]) delete a property type 103prop_type_get([{name} [, {props}]) get property type values 104prop_type_list([{props}]) get list of property types 105 106 107Manipulating text properties: 108 109prop_add({lnum}, {col}, {props}) add a text property 110prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) 111 remove all text properties 112prop_find({props} [, {direction}]) search for a text property 113prop_list({lnum} [, {props}) text properties in {lnum} 114prop_remove({props} [, {lnum} [, {lnum-end}]]) 115 remove a text property 116 117============================================================================== 1183. When text changes *text-prop-changes* 119 120Vim will do its best to keep the text properties on the text where it was 121attached. When inserting or deleting text the properties after the change 122will move accordingly. 123 124When text is deleted and a text property no longer includes any text, it is 125deleted. However, a text property that was defined as zero-width will remain, 126unless the whole line is deleted. 127 128When using replace mode, the text properties stay on the same character 129positions, even though the characters themselves change. 130 131 132When text property columns are not updated ~ 133 134- When setting the line with |setline()| or through an interface, such as Lua, 135 Tcl or Python. 136 137 138 vim:tw=78:ts=8:noet:ft=help:norl: 139