sign.txt (13130B)
1 *sign.txt* Nvim 2 3 4 VIM REFERENCE MANUAL by Gordon Prieur 5 and Bram Moolenaar 6 7 8 Sign Support Features *sign-support* 9 10 Type |gO| to see the table of contents. 11 12 ============================================================================== 13 1. Introduction *sign-intro* *signs* *gutter* 14 15 When a debugger or other IDE tool is driving an editor it needs to be able 16 to give specific highlights which quickly tell the user useful information 17 about the file. One example of this would be a debugger which had an icon 18 in the left-hand column denoting a breakpoint. Another example might be an 19 arrow representing the Program Counter (PC). The sign features allow both 20 placement of a sign, or icon, in the left-hand side of the window and 21 definition of a highlight which will be applied to that line. Displaying the 22 sign as an image is most likely only feasible in gvim (although Sun 23 Microsystem's dtterm does support this it's the only terminal emulator I know 24 of which does). A text sign and the highlight should be feasible in any color 25 terminal emulator. 26 27 Signs and highlights are not useful just for debuggers. There are plugins 28 that use signs to mark build errors or display version control status. 29 30 There are two steps in using signs: 31 32 1. Define the sign. This specifies the image, text and highlighting. For 33 example, you can define a "break" sign with an image of a stop roadsign and 34 text "!!". 35 36 2. Place the sign. This specifies the file and line number where the sign is 37 displayed. A defined sign can be placed several times in different lines 38 and files. 39 40 *sign-column* 41 When signs are defined for a file, Vim will automatically add a column of two 42 characters to display them in. When the last sign is unplaced the column 43 disappears again. This behavior can be changed with the 'signcolumn' option. 44 45 The color of the column is set with the SignColumn highlight group 46 |hl-SignColumn|. Example to set the color: > 47 48 :highlight SignColumn guibg=darkgrey 49 < 50 If 'cursorline' is enabled, then the CursorLineSign highlight group is used 51 |hl-CursorLineSign|. 52 *sign-identifier* 53 Each placed sign is identified by a number called the sign identifier. This 54 identifier is used to jump to the sign or to remove the sign. The identifier 55 is assigned when placing the sign using the |:sign-place| command or the 56 |sign_place()| function. Each sign identifier should be a unique number (per 57 buffer). Placing the same identifier twice will move the previously placed 58 sign. The |sign_place()| function can be called with a zero sign identifier 59 to allocate the next available identifier. 60 61 *sign-group* 62 Each placed sign can be assigned to either the global group or a named group. 63 When placing a sign, if a group name is not supplied, or an empty string is 64 used, then the sign is placed in the global group. Otherwise the sign is 65 placed in the named group. The sign identifier is unique within a group. The 66 sign group allows Vim plugins to use unique signs without interfering with 67 other plugins using signs. 68 69 *sign-priority* 70 Each placed sign is assigned a priority value independently of the sign group. 71 The default priority for a sign is 10, this value can be changed for different 72 signs by specifying a different value at definition time. When multiple signs 73 that each have an icon or text are placed on the same line, signs are ordered 74 with decreasing priority from left to right, up until the maximum width set in 75 'signcolumn'. Low priority signs that do not fit are hidden. Highest priority 76 signs with highlight attributes are always shown. 77 78 When the line on which the sign is placed is deleted, the sign is removed along 79 with it. 80 81 ============================================================================== 82 2. Commands *sign-commands* *:sig* *:sign* 83 84 Here is an example that places a sign "piet", displayed with the text ">>", in 85 line 23 of the current file: > 86 :sign define piet text=>> texthl=Search 87 :exe ":sign place 2 line=23 name=piet file=" .. expand("%:p") 88 89 And here is the command to delete it again: > 90 :sign unplace 2 91 92 Note that the ":sign" command cannot be followed by another command or a 93 comment. If you do need that, use the |:execute| command. 94 95 96 DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* 97 98 See |sign_define()| for the equivalent Vim script function. 99 100 :sig[n] define {name} {argument}... 101 Define a new sign or set attributes for an existing sign. 102 The {name} can either be a number (all digits) or a name 103 starting with a non-digit. Leading zeros are ignored, thus 104 "0012", "012" and "12" are considered the same name. 105 About 120 different signs can be defined. 106 107 Accepted arguments: 108 109 icon={bitmap} 110 Define the file name where the bitmap can be found. Should be 111 a full path. The bitmap should fit in the place of two 112 characters. This is not checked. If the bitmap is too big it 113 will cause redraw problems. 114 toolkit supports ~ 115 Win32 .bmp, .ico, .cur 116 117 priority={prio} 118 Default priority for the sign, see |sign-priority|. 119 120 linehl={group} 121 Highlighting group used for the whole line the sign is placed 122 in. Most useful is defining a background color. 123 124 numhl={group} 125 Highlighting group used for the line number on the line where 126 the sign is placed. Combines with |hl-LineNr|, 127 |hl-LineNrAbove|, |hl-LineNrBelow|, and |hl-CursorLineNr|. 128 129 text={text} *E239* 130 Define the text that is displayed when there is no icon or the 131 GUI is not being used. Only printable characters are allowed 132 and they must occupy one or two display cells. 133 134 texthl={group} 135 Highlighting group used for the text item. 136 137 culhl={group} 138 Highlighting group used for the text item when the cursor is 139 on the same line as the sign and 'cursorline' is enabled. 140 141 Example: > 142 :sign define MySign text=>> texthl=Search linehl=DiffText 143 < 144 145 DELETING A SIGN *:sign-undefine* *E155* 146 147 See |sign_undefine()| for the equivalent Vim script function. 148 149 :sig[n] undefine {name} 150 Deletes a previously defined sign. If signs with this {name} 151 are still placed this will cause trouble. 152 153 Example: > 154 :sign undefine MySign 155 < 156 157 LISTING SIGNS *:sign-list* *E156* 158 159 See |sign_getdefined()| for the equivalent Vim script function. 160 161 :sig[n] list Lists all defined signs and their attributes. 162 163 :sig[n] list {name} 164 Lists one defined sign and its attributes. 165 166 167 PLACING SIGNS *:sign-place* *E158* 168 169 See |sign_place()| for the equivalent Vim script function. 170 171 :sig[n] place {id} line={lnum} name={name} file={fname} 172 Place sign defined as {name} at line {lnum} in file {fname}. 173 *:sign-fname* 174 The file {fname} must already be loaded in a buffer. The 175 exact file name must be used, wildcards, $ENV and ~ are not 176 expanded, white space must not be escaped. Trailing white 177 space is ignored. 178 179 The sign is remembered under {id}, this can be used for 180 further manipulation. {id} must be a number. Placing the 181 same {id} multiple times will move the sign. 182 183 The following optional sign attributes can be specified before 184 "file=": 185 group={group} Place sign in sign group {group} 186 priority={prio} Assign priority {prio} to sign 187 188 By default, the sign is placed in the global sign group. 189 190 By default, the sign is assigned a default priority of 10, 191 unless specified otherwise by the sign definition. To assign 192 a different priority value, use "priority={prio}" to specify a 193 value. The priority is used to determine the sign that is 194 displayed when multiple signs are placed on the same line. 195 196 Examples: > 197 :sign place 5 line=3 name=sign1 file=a.py 198 :sign place 6 group=g2 line=2 name=sign2 file=x.py 199 :sign place 9 group=g2 priority=50 line=5 200 \ name=sign1 file=a.py 201 < 202 :sig[n] place {id} line={lnum} name={name} [buffer={nr}] 203 Same, but use buffer {nr}. If the buffer argument is not 204 given, place the sign in the current buffer. 205 206 Example: > 207 :sign place 10 line=99 name=sign3 208 :sign place 10 line=99 name=sign3 buffer=3 209 < 210 *E885* 211 :sig[n] place {id} name={name} file={fname} 212 Change the placed sign {id} in file {fname} to use the defined 213 sign {name}. See remark above about {fname} |:sign-fname|. 214 This can be used to change the displayed sign without moving 215 it (e.g., when the debugger has stopped at a breakpoint). 216 217 The optional "group={group}" attribute can be used before 218 "file=" to select a sign in a particular group. The optional 219 "priority={prio}" attribute can be used to change the priority 220 of an existing sign. 221 222 Example: > 223 :sign place 23 name=sign1 file=/path/to/edit.py 224 < 225 :sig[n] place {id} name={name} [buffer={nr}] 226 Same, but use buffer {nr}. If the buffer argument is not 227 given, use the current buffer. 228 229 Example: > 230 :sign place 23 name=sign1 231 :sign place 23 name=sign1 buffer=7 232 < 233 234 REMOVING SIGNS *:sign-unplace* *E159* 235 236 See |sign_unplace()| for the equivalent Vim script function. 237 238 :sig[n] unplace {id} file={fname} 239 Remove the previously placed sign {id} from file {fname}. 240 See remark above about {fname} |:sign-fname|. 241 242 :sig[n] unplace {id} group={group} file={fname} 243 Same but remove the sign {id} in sign group {group}. 244 245 :sig[n] unplace {id} group=* file={fname} 246 Same but remove the sign {id} from all the sign groups. 247 248 :sig[n] unplace * file={fname} 249 Remove all placed signs in file {fname}. 250 251 :sig[n] unplace * group={group} file={fname} 252 Remove all placed signs in group {group} from file {fname}. 253 254 :sig[n] unplace * group=* file={fname} 255 Remove all placed signs in all the groups from file {fname}. 256 257 :sig[n] unplace {id} buffer={nr} 258 Remove the previously placed sign {id} from buffer {nr}. 259 260 :sig[n] unplace {id} group={group} buffer={nr} 261 Remove the previously placed sign {id} in group {group} from 262 buffer {nr}. 263 264 :sig[n] unplace {id} group=* buffer={nr} 265 Remove the previously placed sign {id} in all the groups from 266 buffer {nr}. 267 268 :sig[n] unplace * buffer={nr} 269 Remove all placed signs in buffer {nr}. 270 271 :sig[n] unplace * group={group} buffer={nr} 272 Remove all placed signs in group {group} from buffer {nr}. 273 274 :sig[n] unplace * group=* buffer={nr} 275 Remove all placed signs in all the groups from buffer {nr}. 276 277 :sig[n] unplace {id} 278 Remove the previously placed sign {id} from all files it 279 appears in. 280 281 :sig[n] unplace {id} group={group} 282 Remove the previously placed sign {id} in group {group} from 283 all files it appears in. 284 285 :sig[n] unplace {id} group=* 286 Remove the previously placed sign {id} in all the groups from 287 all the files it appears in. 288 289 :sig[n] unplace * 290 Remove all placed signs in the global group from all the 291 files. 292 293 :sig[n] unplace * group={group} 294 Remove all placed signs in group {group} from all the files. 295 296 :sig[n] unplace * group=* 297 Remove all placed signs in all the groups from all the files. 298 299 :sig[n] unplace 300 Remove a placed sign at the cursor position. If multiple 301 signs are placed in the line, then only one is removed. 302 303 :sig[n] unplace group={group} 304 Remove a placed sign in group {group} at the cursor 305 position. 306 307 :sig[n] unplace group=* 308 Remove a placed sign in any group at the cursor position. 309 310 311 LISTING PLACED SIGNS *:sign-place-list* 312 313 See |sign_getplaced()| for the equivalent Vim script function. 314 315 :sig[n] place file={fname} 316 List signs placed in file {fname}. 317 See remark above about {fname} |:sign-fname|. 318 319 :sig[n] place group={group} file={fname} 320 List signs in group {group} placed in file {fname}. 321 322 :sig[n] place group=* file={fname} 323 List signs in all the groups placed in file {fname}. 324 325 :sig[n] place buffer={nr} 326 List signs placed in buffer {nr}. 327 328 :sig[n] place group={group} buffer={nr} 329 List signs in group {group} placed in buffer {nr}. 330 331 :sig[n] place group=* buffer={nr} 332 List signs in all the groups placed in buffer {nr}. 333 334 :sig[n] place List placed signs in the global group in all files. 335 336 :sig[n] place group={group} 337 List placed signs with sign group {group} in all files. 338 339 :sig[n] place group=* 340 List placed signs in all sign groups in all files. 341 342 343 JUMPING TO A SIGN *:sign-jump* *E157* 344 345 See |sign_jump()| for the equivalent Vim script function. 346 347 :sig[n] jump {id} file={fname} 348 Open the file {fname} or jump to the window that contains 349 {fname} and position the cursor at sign {id}. 350 See remark above about {fname} |:sign-fname|. 351 If the file isn't displayed in window and the current file can 352 not be |abandon|ed this fails. 353 354 :sig[n] jump {id} group={group} file={fname} 355 Same but jump to the sign in group {group} 356 357 :sig[n] jump {id} [buffer={nr}] *E934* 358 Same, but use buffer {nr}. This fails if buffer {nr} does not 359 have a name. If the buffer argument is not given, use the 360 current buffer. 361 362 :sig[n] jump {id} group={group} [buffer={nr}] 363 Same but jump to the sign in group {group} 364 365 366 ============================================================================== 367 3. Functions *sign-functions-details* 368 369 See: 370 - |sign_define()| 371 - |sign_getdefined()| 372 - |sign_getplaced()| 373 - |sign_jump()| 374 - |sign_place()| 375 - |sign_placelist()| 376 - |sign_undefine()| 377 - |sign_unplace()| 378 - |sign_unplacelist()| 379 380 vim:tw=78:ts=8:noet:ft=help:norl: