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