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