Mercurial > vim

comparison runtime/doc/sign.txt @ 15209:3a99b2e6d136 v8.1.0614

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.0614: placing signs can be complicated commit https://github.com/vim/vim/commit/162b71479bd4dcdb3a2ef9198a1444f6f99e6843 Author: Bram Moolenaar <Bram@vim.org> Date: Fri Dec 21 15:17:36 2018 +0100 patch 8.1.0614: placing signs can be complicated Problem: Placing signs can be complicated. Solution: Add functions for defining and placing signs. Introduce a group name to avoid different plugins using the same signs. (Yegappan Lakshmanan, closes #3652)
author Bram Moolenaar <Bram@vim.org>
date Fri, 21 Dec 2018 15:30:07 +0100
parents 2f7e67dd088c
children 97b40b4c6911
comparison
equal deleted inserted replaced
15208:acf68008ca43 15209:3a99b2e6d136
1 *sign.txt* For Vim version 8.1. Last change: 2016 Aug 17 1 *sign.txt* For Vim version 8.1. Last change: 2018 Dec 21
2 2
3 3
4 VIM REFERENCE MANUAL by Gordon Prieur 4 VIM REFERENCE MANUAL by Gordon Prieur
5 and Bram Moolenaar 5 and Bram Moolenaar
6 6
49 49
50 The color of the column is set with the SignColumn group |hl-SignColumn|. 50 The color of the column is set with the SignColumn group |hl-SignColumn|.
51 Example to set the color: > 51 Example to set the color: >
52 52
53 :highlight SignColumn guibg=darkgrey 53 :highlight SignColumn guibg=darkgrey
54 <
55 *sign-group*
56 Each sign can be assigned to either the global group or a named group. When
57 placing a sign, if a group name is not supplied, or an empty string is used,
58 then the sign is placed in the global group. Otherwise the sign is placed in
59 the named group. The sign identifier is unique within a group. The sign group
60 allows Vim plugins to use unique signs without interfering with other plugins
61 using signs.
62
63 *sign-priority*
64 Each placed sign is assigned a priority value. When multiple signs are placed
65 on the same line, the attributes of the sign with the highest priority is used
66 independent of the sign group. The default priority for a sign is 10. The
67 priority is assigned at the time of placing a sign.
54 68
55 ============================================================================== 69 ==============================================================================
56 2. Commands *sign-commands* *:sig* *:sign* 70 2. Commands *sign-commands* *:sig* *:sign*
57 71
58 Here is an example that places a sign "piet", displayed with the text ">>", in 72 Here is an example that places a sign "piet", displayed with the text ">>", in
66 Note that the ":sign" command cannot be followed by another command or a 80 Note that the ":sign" command cannot be followed by another command or a
67 comment. If you do need that, use the |:execute| command. 81 comment. If you do need that, use the |:execute| command.
68 82
69 83
70 DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* 84 DEFINING A SIGN. *:sign-define* *E255* *E160* *E612*
85
86 See |sign_define()| for the equivalent Vim script function.
71 87
72 :sign define {name} {argument}... 88 :sign define {name} {argument}...
73 Define a new sign or set attributes for an existing sign. 89 Define a new sign or set attributes for an existing sign.
74 The {name} can either be a number (all digits) or a name 90 The {name} can either be a number (all digits) or a name
75 starting with a non-digit. Leading digits are ignored, thus 91 starting with a non-digit. Leading digits are ignored, thus
104 Highlighting group used for the text item. 120 Highlighting group used for the text item.
105 121
106 122
107 DELETING A SIGN *:sign-undefine* *E155* 123 DELETING A SIGN *:sign-undefine* *E155*
108 124
125 See |sign_undefine()| for the equivalent Vim script function.
126
109 :sign undefine {name} 127 :sign undefine {name}
110 Deletes a previously defined sign. If signs with this {name} 128 Deletes a previously defined sign. If signs with this {name}
111 are still placed this will cause trouble. 129 are still placed this will cause trouble.
112 130
113 131
132
114 LISTING SIGNS *:sign-list* *E156* 133 LISTING SIGNS *:sign-list* *E156*
134
135 See |sign_getdefined()| for the equivalent Vim script function.
115 136
116 :sign list Lists all defined signs and their attributes. 137 :sign list Lists all defined signs and their attributes.
117 138
118 :sign list {name} 139 :sign list {name}
119 Lists one defined sign and its attributes. 140 Lists one defined sign and its attributes.
120 141
121 142
122 PLACING SIGNS *:sign-place* *E158* 143 PLACING SIGNS *:sign-place* *E158*
144
145 See |sign_place()| for the equivalent Vim script function.
123 146
124 :sign place {id} line={lnum} name={name} file={fname} 147 :sign place {id} line={lnum} name={name} file={fname}
125 Place sign defined as {name} at line {lnum} in file {fname}. 148 Place sign defined as {name} at line {lnum} in file {fname}.
126 *:sign-fname* 149 *:sign-fname*
127 The file {fname} must already be loaded in a buffer. The 150 The file {fname} must already be loaded in a buffer. The
134 It's up to the user to make sure the {id} is used only once in 157 It's up to the user to make sure the {id} is used only once in
135 each file (if it's used several times unplacing will also have 158 each file (if it's used several times unplacing will also have
136 to be done several times and making changes may not work as 159 to be done several times and making changes may not work as
137 expected). 160 expected).
138 161
162 The following optional sign attributes can be specified before
163 "file=":
164 group={group} Place sign in sign group {group}
165 priority={prio} Assign priority {prio} to sign
166
167 By default, the sign is placed in the global sign group.
168
169 By default, the sign is assigned a default priority of 10. To
170 assign a different priority value, use "priority={prio}" to
171 specify a value. The priority is used to determine the
172 highlight group used when multiple signs are placed on the
173 same line.
174
175 Examples: >
176 :sign place 5 line=3 name=sign1 file=a.py
177 :sign place 6 group=g2 line=2 name=sign2 file=x.py
178 :sign place 9 group=g2 priority=50 line=5
179 \ name=sign1 file=a.py
180 <
139 :sign place {id} line={lnum} name={name} buffer={nr} 181 :sign place {id} line={lnum} name={name} buffer={nr}
140 Same, but use buffer {nr}. 182 Same, but use buffer {nr}.
141 183
142 *E885* 184 *E885*
143 :sign place {id} name={name} file={fname} 185 :sign place {id} name={name} file={fname}
144 Change the placed sign {id} in file {fname} to use the defined 186 Change the placed sign {id} in file {fname} to use the defined
145 sign {name}. See remark above about {fname} |:sign-fname|. 187 sign {name}. See remark above about {fname} |:sign-fname|.
146 This can be used to change the displayed sign without moving 188 This can be used to change the displayed sign without moving
147 it (e.g., when the debugger has stopped at a breakpoint). 189 it (e.g., when the debugger has stopped at a breakpoint).
148 190
191 The optional "group={group}" attribute can be used before
192 "file=" to select a sign in a particular group.
193
149 :sign place {id} name={name} buffer={nr} 194 :sign place {id} name={name} buffer={nr}
150 Same, but use buffer {nr}. 195 Same, but use buffer {nr}.
151 196
152 197
153 REMOVING SIGNS *:sign-unplace* *E159* 198 REMOVING SIGNS *:sign-unplace* *E159*
199
200 See |sign_unplace()| for the equivalent Vim script function.
154 201
155 :sign unplace {id} file={fname} 202 :sign unplace {id} file={fname}
156 Remove the previously placed sign {id} from file {fname}. 203 Remove the previously placed sign {id} from file {fname}.
157 See remark above about {fname} |:sign-fname|. 204 See remark above about {fname} |:sign-fname|.
158 205
206 :sign unplace {id} group={group} file={fname}
207 Same but remove the sign {id} in sign group {group}.
208
209 :sign unplace {id} group=* file={fname}
210 Same but remove the sign {id} from all the sign groups.
211
159 :sign unplace * file={fname} 212 :sign unplace * file={fname}
160 Remove all placed signs in file {fname}. 213 Remove all placed signs in file {fname}.
161 214
215 :sign unplace * group={group} file={fname}
216 Remove all placed signs in group {group} from file {fname}.
217
218 :sign unplace * group=* file={fname}
219 Remove all placed signs in all the groups from file {fname}.
220
162 :sign unplace {id} buffer={nr} 221 :sign unplace {id} buffer={nr}
163 Remove the previously placed sign {id} from buffer {nr}. 222 Remove the previously placed sign {id} from buffer {nr}.
164 223
224 :sign unplace {id} group={group} buffer={nr}
225 Remove the previously placed sign {id} in group {group} from
226 buffer {nr}.
227
228 :sign unplace {id} group=* buffer={nr}
229 Remove the previously placed sign {id} in all the groups from
230 buffer {nr}.
231
165 :sign unplace * buffer={nr} 232 :sign unplace * buffer={nr}
166 Remove all placed signs in buffer {nr}. 233 Remove all placed signs in buffer {nr}.
234
235 :sign unplace * group={group} buffer={nr}
236 Remove all placed signs in group {group} from buffer {nr}.
237
238 :sign unplace * group=* buffer={nr}
239 Remove all placed signs in all the groups from buffer {nr}.
167 240
168 :sign unplace {id} 241 :sign unplace {id}
169 Remove the previously placed sign {id} from all files it 242 Remove the previously placed sign {id} from all files it
170 appears in. 243 appears in.
171 244
245 :sign unplace {id} group={group}
246 Remove the previously placed sign {id} in group {group} from
247 all files it appears in.
248
249 :sign unplace {id} group=*
250 Remove the previously placed sign {id} in all the groups from
251 all the files it appears in.
252
172 :sign unplace * 253 :sign unplace *
173 Remove all placed signs. 254 Remove all placed signs in the global group.
255
256 :sign unplace * group=*
257 Remove all placed signs in all the groups.
174 258
175 :sign unplace 259 :sign unplace
176 Remove the placed sign at the cursor position. 260 Remove the placed sign at the cursor position.
177 261
178 262
179 LISTING PLACED SIGNS *:sign-place-list* 263 LISTING PLACED SIGNS *:sign-place-list*
264
265 See |sign_getplaced()| for the equivalent Vim script function.
180 266
181 :sign place file={fname} 267 :sign place file={fname}
182 List signs placed in file {fname}. 268 List signs placed in file {fname}.
183 See remark above about {fname} |:sign-fname|. 269 See remark above about {fname} |:sign-fname|.
184 270
271 :sign place group={group} file={fname}
272 List signs in group {group} placed in file {fname}.
273
185 :sign place buffer={nr} 274 :sign place buffer={nr}
186 List signs placed in buffer {nr}. 275 List signs placed in buffer {nr}.
187 276
277 :sign place group={group} buffer={nr}
278 List signs in group {group} placed in buffer {nr}.
279
188 :sign place List placed signs in all files. 280 :sign place List placed signs in all files.
281
282 :sign place group={group}
283 List placed signs in all sign groups in all the files.
189 284
190 285
191 JUMPING TO A SIGN *:sign-jump* *E157* 286 JUMPING TO A SIGN *:sign-jump* *E157*
192 287
193 :sign jump {id} file={fname} 288 :sign jump {id} file={fname}