Mercurial > vim

annotate runtime/doc/textprop.txt @ 32669:448aef880252

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
normalize line endings
author Christian Brabandt <cb@256bit.org>
date Mon, 26 Jun 2023 09:54:34 +0200
parents 2a17771529af
children 695b50472e85
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
32669
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
1 *textprop.txt* For Vim version 9.0. Last change: 2023 Apr 23
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
2
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
3
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
4 VIM REFERENCE MANUAL by Bram Moolenaar
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
5
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
6
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
7 Displaying text with properties attached. *textprop* *text-properties*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
8
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
9
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
10 1. Introduction |text-prop-intro|
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
11 2. Functions |text-prop-functions|
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
12 3. When text changes |text-prop-changes|
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
13
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
14
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
15 {not able to use text properties when the |+textprop| feature was
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
16 disabled at compile time}
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
17
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
18 ==============================================================================
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
19 1. Introduction *text-prop-intro*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
20
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
21 Text properties can be attached to text in a buffer. They will move with the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
22 text: If lines are deleted or inserted the properties move with the text they
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
23 are attached to. Also when inserting/deleting text in the line before the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
24 text property. And when inserting/deleting text inside the text property, it
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
25 will increase/decrease in size.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
26
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
27 The main use for text properties is to highlight text. This can be seen as a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
28 replacement for syntax highlighting. Instead of defining patterns to match
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
29 the text, the highlighting is set by a script, possibly using the output of an
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
30 external parser. This only needs to be done once, not every time when
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
31 redrawing the screen, thus can be much faster, after the initial cost of
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
32 attaching the text properties.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
33
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
34 Text properties can also be used for other purposes to identify text. For
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
35 example, add a text property on a function name, so that a search can be
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
36 defined to jump to the next/previous function.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
37
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
38 A text property is attached at a specific line and column, and has a specified
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
39 length. The property can span multiple lines.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
40
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
41 A text property has these fields:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
42 "id" a number to be used as desired
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
43 "type" the name of a property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
44
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
45
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
46 Property Types ~
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
47 *E971*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
48 A text property normally has the name of a property type, which defines
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
49 how to highlight the text. The property type can have these entries:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
50 "highlight" name of the highlight group to use
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
51 "combine" when omitted or TRUE the text property highlighting is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
52 combined with any syntax highlighting; when FALSE the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
53 text property highlighting replaces the syntax
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
54 highlighting
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
55 "priority" when properties overlap, the one with the highest
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
56 priority will be used.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
57 "start_incl" when TRUE inserts at the start position will be
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
58 included in the text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
59 "end_incl" when TRUE inserts at the end position will be
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
60 included in the text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
61
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
62
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
63 Example ~
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
64
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
65 Suppose line 11 in a buffer has this text (excluding the indent):
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
66
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
67 The number 123 is smaller than 4567.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
68
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
69 To highlight the numbers in this text: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
70 call prop_type_add('number', {'highlight': 'Constant'})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
71 call prop_add(11, 12, {'length': 3, 'type': 'number'})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
72 call prop_add(11, 32, {'length': 4, 'type': 'number'})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
73
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
74 Try inserting or deleting lines above the text, you will see that the text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
75 properties stick to the text, thus the line number is adjusted as needed.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
76
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
77 Setting "start_incl" and "end_incl" is useful when white space surrounds the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
78 text, e.g. for a function name. Using false is useful when the text starts
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
79 and/or ends with a specific character, such as the quote surrounding a string.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
80
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
81 func FuncName(arg) ~
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
82 ^^^^^^^^ property with start_incl and end_incl set
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
83
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
84 var = "text"; ~
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
85 ^^^^^^ property with start_incl and end_incl not set
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
86
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
87 Nevertheless, when text is inserted or deleted the text may need to be parsed
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
88 and the text properties updated. But this can be done asynchronously.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
89
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
90
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
91 Internal error *E967*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
92
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
93 If you see E967, please report the bug. You can do this at Github:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
94 https://github.com/vim/vim/issues/new
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
95
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
96 ==============================================================================
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
97 2. Functions *text-prop-functions*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
98
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
99 Manipulating text property types:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
100
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
101 prop_type_add({name}, {props}) define a new property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
102 prop_type_change({name}, {props}) change an existing property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
103 prop_type_delete({name} [, {props}]) delete a property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
104 prop_type_get({name} [, {props}]) get property type values
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
105 prop_type_list([{props}]) get list of property types
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
106
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
107
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
108 Manipulating text properties:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
109
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
110 prop_add({lnum}, {col}, {props}) add a text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
111 prop_add_list({props}, [{item}, ...])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
112 add a text property at multiple
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
113 positions.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
114 prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
115 remove all text properties
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
116 prop_find({props} [, {direction}]) search for a text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
117 prop_list({lnum} [, {props}]) text properties in {lnum}
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
118 prop_remove({props} [, {lnum} [, {lnum-end}]])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
119 remove a text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
120
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
121 *prop_add()* *E965*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
122 prop_add({lnum}, {col}, {props})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
123 Attach a text property at position {lnum}, {col}. {col} is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
124 counted in bytes, use one for the first column.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
125 If {lnum} is invalid an error is given. *E966*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
126 If {col} is invalid an error is given. *E964*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
127
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
128 {props} is a dictionary with these fields:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
129 type name of the text property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
130 length length of text in bytes, can only be used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
131 for a property that does not continue in
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
132 another line; can be zero
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
133 end_lnum line number for the end of text (inclusive)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
134 end_col column just after the text; not used when
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
135 "length" is present; when {col} and "end_col"
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
136 are equal, and "end_lnum" is omitted or equal
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
137 to {lnum}, this is a zero-width text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
138 bufnr buffer to add the property to; when omitted
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
139 the current buffer is used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
140 id user defined ID for the property; must be a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
141 number, should be positive; when using "text"
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
142 then "id" must not be present and will be set
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
143 automatically to a negative number; otherwise
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
144 zero is used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
145 *E1305*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
146 text text to be displayed before {col}, or
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
147 above/below the line if {col} is zero; prepend
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
148 and/or append spaces for padding with
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
149 highlighting; cannot be used with "length",
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
150 "end_lnum" and "end_col"
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
151 See |virtual-text| for more information.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
152 *E1294*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
153 text_align when "text" is present and {col} is zero;
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
154 specifies where to display the text:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
155 after after the end of the line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
156 right right aligned in the window (unless
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
157 the text wraps to the next screen
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
158 line)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
159 below in the next screen line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
160 above just above the line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
161 When omitted "after" is used. Only one
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
162 "right" property can fit in each line, if
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
163 there are two or more these will go in a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
164 separate line (still right aligned).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
165 text_padding_left *E1296*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
166 used when "text" is present and {col} is zero;
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
167 padding between the end of the text line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
168 (leftmost column for "above" and "below") and
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
169 the virtual text, not highlighted
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
170 text_wrap when "text" is present and {col} is zero,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
171 specifies what happens if the text doesn't
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
172 fit:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
173 wrap wrap the text to the next line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
174 truncate truncate the text to make it fit
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
175 When omitted "truncate" is used.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
176 Note that this applies to the individual text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
177 property, the 'wrap' option sets the overall
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
178 behavior
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
179 All fields except "type" are optional.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
180
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
181 It is an error when both "length" and "end_lnum" or "end_col"
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
182 are given. Either use "length" or "end_col" for a property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
183 within one line, or use "end_lnum" and "end_col" for a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
184 property that spans more than one line.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
185 When neither "length" nor "end_col" are given the property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
186 will be zero-width. That means it will move with the text, as
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
187 a kind of mark. One character will be highlighted, if the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
188 type specifies highlighting.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
189 The property can end exactly at the last character of the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
190 text, or just after it. In the last case, if text is appended
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
191 to the line, the text property size will increase, also when
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
192 the property type does not have "end_incl" set.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
193
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
194 "type" will first be looked up in the buffer the property is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
195 added to. When not found, the global property types are used.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
196 If not found an error is given.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
197 *virtual-text*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
198 When "text" is used and the column is non-zero then this text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
199 will be displayed at the specified start location of the text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
200 property. The text of the buffer line will be shifted to make
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
201 room. This is called "virtual text".
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
202 When the column is zero the virtual text will appear above,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
203 after or below the buffer text. The "text_align" and
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
204 "text_wrap" arguments determine how it is displayed.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
205 To separate the virtual text from the buffer text prepend
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
206 and/or append spaces to the "text" field or use the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
207 "text_padding_left" value.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
208
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
209 Make sure to use a highlight that makes clear to the user that
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
210 this is virtual text, otherwise it will be very confusing that
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
211 the text cannot be edited. When using "above" you need to
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
212 make clear this text belongs to the text line below it, when
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
213 using "below" you need to make sure it belongs to the text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
214 line above it.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
215
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
216 The text will be displayed but it is not part of the actual
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
217 buffer line, the cursor cannot be placed on it. A mouse click
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
218 in the text will move the cursor to the first character after
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
219 the text, or the last character of the line.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
220 Any Tab and other control character in the text will be
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
221 changed to a space (Rationale: otherwise the size of the text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
222 is difficult to compute).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
223 A negative "id" will be chosen and is returned.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
224
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
225 Before text properties with text were supported it was
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
226 possible to use a negative "id", even though this was very
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
227 rare. Now that negative "id"s are reserved for text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
228 properties with text an error is given when using a negative
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
229 "id". When a text property with text already exists using a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
230 negative "id" results in *E1293* . If a negative "id" was
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
231 used and later a text property with text is added results in
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
232 *E1339* .
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
233
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
234 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
235 GetLnum()->prop_add(col, props)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
236 <
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
237 *prop_add_list()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
238 prop_add_list({props}, [{item}, ...])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
239 Similar to prop_add(), but attaches a text property at
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
240 multiple positions in a buffer.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
241
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
242 {props} is a dictionary with these fields:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
243 bufnr buffer to add the property to; when omitted
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
244 the current buffer is used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
245 id user defined ID for the property; must be a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
246 number; when omitted zero is used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
247 type name of the text property type
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
248 All fields except "type" are optional.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
249
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
250 The second argument is a List of items, where each {item} is a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
251 list that specifies the starting and ending position of the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
252 text: [{lnum}, {col}, {end-lnum}, {end-col}]
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
253 or: [{lnum}, {col}, {end-lnum}, {end-col}, {id}]
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
254
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
255 The first two items {lnum} and {col} specify the starting
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
256 position of the text where the property will be attached.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
257 The next two items {end-lnum} and {end-col} specify the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
258 position just after the text.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
259 An optional fifth item {id} can be used to give a different ID
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
260 to a property. When omitted the ID from {props} is used,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
261 falling back to zero if none are present.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
262
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
263 It is not possible to add a text property with a "text" field
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
264 here.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
265
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
266 Example: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
267 call prop_add_list(#{type: 'MyProp', id: 2},
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
268 \ [[1, 4, 1, 7],
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
269 \ [1, 15, 1, 20],
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
270 \ [2, 30, 3, 30]]
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
271 <
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
272 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
273 GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
274
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
275
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
276 prop_clear({lnum} [, {lnum-end} [, {props}]]) *prop_clear()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
277 Remove all text properties from line {lnum}.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
278 When {lnum-end} is given, remove all text properties from line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
279 {lnum} to {lnum-end} (inclusive).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
280
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
281 When {props} contains a "bufnr" item use this buffer,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
282 otherwise use the current buffer.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
283
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
284 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
285 GetLnum()->prop_clear()
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
286 <
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
287 *prop_find()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
288 prop_find({props} [, {direction}])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
289 Search for a text property as specified with {props}:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
290 id property with this ID
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
291 type property with this type name
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
292 both "id" and "type" must both match
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
293 bufnr buffer to search in; when present a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
294 start position with "lnum" and "col"
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
295 must be given; when omitted the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
296 current buffer is used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
297 lnum start in this line (when omitted start
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
298 at the cursor)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
299 col start at this column (when omitted
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
300 and "lnum" is given: use column 1,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
301 otherwise start at the cursor)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
302 skipstart do not look for a match at the start
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
303 position
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
304
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
305 A property matches when either "id" or "type" matches.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
306 {direction} can be "f" for forward and "b" for backward. When
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
307 omitted forward search is performed.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
308
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
309 If a match is found then a Dict is returned with the entries
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
310 as with prop_list(), and additionally an "lnum" entry.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
311 If no match is found then an empty Dict is returned.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
312
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
313
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
314 prop_list({lnum} [, {props}]) *prop_list()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
315 Returns a List with all the text properties in line {lnum}.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
316
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
317 The following optional items are supported in {props}:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
318 bufnr use this buffer instead of the current buffer
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
319 end_lnum return text properties in all the lines
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
320 between {lnum} and {end_lnum} (inclusive).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
321 A negative value is used as an offset from the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
322 last buffer line; -1 refers to the last buffer
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
323 line.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
324 types List of property type names. Return only text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
325 properties that match one of the type names.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
326 ids List of property identifiers. Return only text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
327 properties with one of these identifiers.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
328
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
329 The properties are ordered by starting column and priority.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
330 Each property is a Dict with these entries:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
331 lnum starting line number. Present only when
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
332 returning text properties between {lnum} and
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
333 {end_lnum}.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
334 col starting column
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
335 length length in bytes, one more if line break is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
336 included
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
337 id property ID
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
338 type name of the property type, omitted if
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
339 the type was deleted
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
340 type_bufnr buffer number for which this type was defined;
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
341 0 if the type is global
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
342 start when TRUE property starts in this line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
343 end when TRUE property ends in this line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
344
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
345 When "start" is zero the property started in a previous line,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
346 the current one is a continuation.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
347 When "end" is zero the property continues in the next line.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
348 The line break after this line is included.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
349
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
350 Returns an empty list on error.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
351
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
352 Examples:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
353 " get text properties placed in line 5
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
354 echo prop_list(5)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
355 " get text properties placed in line 20 in buffer 4
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
356 echo prop_list(20, {'bufnr': 4})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
357 " get all the text properties between line 1 and 20
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
358 echo prop_list(1, {'end_lnum': 20})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
359 " get all the text properties of type 'myprop'
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
360 echo prop_list(1, {'types': ['myprop'],
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
361 \ 'end_lnum': -1})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
362 " get all the text properties of type 'prop1' or 'prop2'
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
363 echo prop_list(1, {'types': ['prop1', 'prop2'],
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
364 \ 'end_lnum': -1})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
365 " get all the text properties with ID 8
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
366 echo prop_list(1, {'ids': [8], 'end_lnum': line('$')})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
367 " get all the text properties with ID 10 and 20
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
368 echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
369 " get text properties with type 'myprop' and ID 100
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
370 " in buffer 4.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
371 echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
372 \ 'ids': [100], 'end_lnum': -1})
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
373
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
374 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
375 GetLnum()->prop_list()
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
376 <
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
377 *prop_remove()* *E968* *E860*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
378 prop_remove({props} [, {lnum} [, {lnum-end}]])
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
379 Remove a matching text property from line {lnum}. When
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
380 {lnum-end} is given, remove matching text properties from line
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
381 {lnum} to {lnum-end} (inclusive).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
382 When {lnum} is omitted remove matching text properties from
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
383 all lines (this requires going over all lines, thus will be a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
384 bit slow for a buffer with many lines).
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
385
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
386 {props} is a dictionary with these fields:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
387 id remove text properties with this ID
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
388 type remove text properties with this type name
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
389 types remove text properties with type names in this
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
390 List
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
391 both "id" and "type"/"types" must both match
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
392 bufnr use this buffer instead of the current one
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
393 all when TRUE remove all matching text properties,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
394 not just the first one
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
395 Only one of "type" and "types" may be supplied. *E1295*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
396
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
397 A property matches when either "id" or one of the supplied
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
398 types matches.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
399 If buffer "bufnr" does not exist you get an error message.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
400 If buffer "bufnr" is not loaded then nothing happens.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
401
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
402 Returns the number of properties that were removed.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
403
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
404 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
405 GetProps()->prop_remove()
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
406
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
407
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
408 prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
409 Add a text property type {name}. If a property type with this
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
410 name already exists an error is given. Nothing is returned.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
411 {props} is a dictionary with these optional fields:
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
412 bufnr define the property only for this buffer; this
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
413 avoids name collisions and automatically
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
414 clears the property types when the buffer is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
415 deleted.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
416 highlight name of highlight group to use
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
417 priority when a character has multiple text
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
418 properties the one with the highest priority
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
419 will be used; negative values can be used, the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
420 default priority is zero
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
421 combine when omitted or TRUE combine the highlight
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
422 with any syntax highlight; when FALSE syntax
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
423 highlight will not be used
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
424 override when TRUE the highlight overrides any other,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
425 including 'cursorline' and Visual
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
426 start_incl when TRUE inserts at the start position will
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
427 be included in the text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
428 end_incl when TRUE inserts at the end position will be
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
429 included in the text property
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
430
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
431 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
432 GetPropName()->prop_type_add(props)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
433
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
434 prop_type_change({name}, {props}) *prop_type_change()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
435 Change properties of an existing text property type. If a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
436 property with this name does not exist an error is given.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
437 The {props} argument is just like |prop_type_add()|.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
438
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
439 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
440 GetPropName()->prop_type_change(props)
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
441
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
442 prop_type_delete({name} [, {props}]) *prop_type_delete()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
443 Remove the text property type {name}. When text properties
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
444 using the type {name} are still in place, they will not have
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
445 an effect and can no longer be removed by name.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
446
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
447 {props} can contain a "bufnr" item. When it is given, delete
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
448 a property type from this buffer instead of from the global
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
449 property types.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
450
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
451 When text property type {name} is not found there is no error.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
452
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
453 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
454 GetPropName()->prop_type_delete()
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
455
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
456 prop_type_get({name} [, {props}]) *prop_type_get()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
457 Returns the properties of property type {name}. This is a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
458 dictionary with the same fields as was given to
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
459 prop_type_add().
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
460 When the property type {name} does not exist, an empty
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
461 dictionary is returned.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
462
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
463 {props} can contain a "bufnr" item. When it is given, use
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
464 this buffer instead of the global property types.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
465
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
466 Can also be used as a |method|: >
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
467 GetPropName()->prop_type_get()
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
468
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
469 prop_type_list([{props}]) *prop_type_list()*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
470 Returns a list with all property type names.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
471
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
472 {props} can contain a "bufnr" item. When it is given, use
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
473 this buffer instead of the global property types.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
474
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
475
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
476 ==============================================================================
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
477 3. When text changes *text-prop-changes*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
478
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
479 Vim will do its best to keep the text properties on the text where it was
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
480 attached. When inserting or deleting text the properties after the change
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
481 will move accordingly.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
482
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
483 When text is deleted and a text property no longer includes any text, it is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
484 deleted. However, a text property that was defined as zero-width will remain,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
485 unless the whole line is deleted.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
486 *E275*
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
487 When a buffer is unloaded, all the text properties are gone. There is no way
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
488 to store the properties in a file. You can only re-create them. When a
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
489 buffer is hidden the text is preserved and so are the text properties. It is
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
490 not possible to add text properties to an unloaded buffer.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
491
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
492 When using replace mode, the text properties stay on the same character
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
493 positions, even though the characters themselves change.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
494
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
495 To update text properties after the text was changed, install a callback with
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
496 `listener_add()`. E.g, if your plugin does spell checking, you can have the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
497 callback update spelling mistakes in the changed text. Vim will move the
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
498 properties below the changed text, so that they still highlight the same text,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
499 thus you don't need to update these.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
500
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
501
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
502 Text property columns are not updated or copied: ~
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
503
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
504 - When setting the line with |setline()| or through an interface, such as Lua,
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
505 Tcl or Python. Vim does not know what text got inserted or deleted.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
506 - With a command like `:move`, which takes a line of text out of context.
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
507
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
508
448aef880252 normalize line endings
Christian Brabandt <cb@256bit.org>
parents: 32449
diff changeset
509 vim:tw=78:ts=8:noet:ft=help:norl: