blob: bda523038f86c285eacc5820719d935f436bb909 [file] [log] [blame]
Bram Moolenaar68e65602019-05-26 21:33:31 +02001*textprop.txt* For Vim version 8.1. Last change: 2019 May 12
Bram Moolenaar98aefe72018-12-13 22:20:09 +01002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaara6c27c42019-05-09 19:16:22 +02007Displaying text with properties attached. *textprop* *text-properties*
Bram Moolenaar98aefe72018-12-13 22:20:09 +01008
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()
Bram Moolenaar98aefe72018-12-13 22:20:09 +010015
16
171. Introduction |text-prop-intro|
182. Functions |text-prop-functions|
Bram Moolenaard09091d2019-01-17 16:07:22 +0100193. When text changes |text-prop-changes|
Bram Moolenaar98aefe72018-12-13 22:20:09 +010020
21
Bram Moolenaar98aefe72018-12-13 22:20:09 +010022{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
Bram Moolenaarde24a872019-05-05 15:48:00 +020058 "combine" when TRUE the text property highlighting is combined
59 with any syntax highligting, when omitted or FALSE the
60 text property highlighting replaces the syntax
61 highlighting
Bram Moolenaar98aefe72018-12-13 22:20:09 +010062 "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
Bram Moolenaar4c05fa02019-01-01 15:32:17 +010076To highlight the numbers in this text: >
Bram Moolenaar98aefe72018-12-13 22:20:09 +010077 call prop_type_add('number', {'highlight': 'Constant'})
Bram Moolenaar9d87a372018-12-18 21:41:50 +010078 call prop_add(11, 12, {'length': 3, 'type': 'number'})
79 call prop_add(11, 32, {'length': 4, 'type': 'number'})
Bram Moolenaar98aefe72018-12-13 22:20:09 +010080
Bram Moolenaar4c05fa02019-01-01 15:32:17 +010081Try 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
Bram Moolenaar98aefe72018-12-13 22:20:09 +010084Setting "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
Bram Moolenaar9d87a372018-12-18 21:41:50 +010095and the text properties updated. But this can be done asynchronously.
Bram Moolenaar98aefe72018-12-13 22:20:09 +010096
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
Bram Moolenaarc8c88492018-12-27 23:59:26 +0100112prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +0100113 remove all text properties
114prop_find({props} [, {direction}]) search for a text property
115prop_list({lnum} [, {props}) text properties in {lnum}
Bram Moolenaarc8c88492018-12-27 23:59:26 +0100116prop_remove({props} [, {lnum} [, {lnum-end}]])
Bram Moolenaar98aefe72018-12-13 22:20:09 +0100117 remove a text property
118
Bram Moolenaard09091d2019-01-17 16:07:22 +0100119==============================================================================
1203. When text changes *text-prop-changes*
121
122Vim will do its best to keep the text properties on the text where it was
123attached. When inserting or deleting text the properties after the change
124will move accordingly.
125
126When text is deleted and a text property no longer includes any text, it is
127deleted. However, a text property that was defined as zero-width will remain,
128unless the whole line is deleted.
129
130When using replace mode, the text properties stay on the same character
131positions, even though the characters themselves change.
132
Bram Moolenaar68e65602019-05-26 21:33:31 +0200133To update text properties after the text was changed, install a callback with
134`listener_add()`. E.g, if your plugin does spell checking, you can have the
135callback update spelling mistakes in the changed text. Vim will move the
136properties below the changed text, so that they still highlight the same text,
137thus you don't need to update these.
138
Bram Moolenaard09091d2019-01-17 16:07:22 +0100139
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200140Text property columns are not updated: ~
Bram Moolenaard09091d2019-01-17 16:07:22 +0100141
142- When setting the line with |setline()| or through an interface, such as Lua,
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200143 Tcl or Python. Vim does not know what text got inserted or deleted.
Bram Moolenaard09091d2019-01-17 16:07:22 +0100144
Bram Moolenaar98aefe72018-12-13 22:20:09 +0100145
146 vim:tw=78:ts=8:noet:ft=help:norl: