Mercurial > vim

comparison runtime/doc/sign.txt @ 17456:e414281d8bb4 v8.1.1726

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.1726: the eval.txt help file is too big commit https://github.com/vim/vim/commit/ed997adaa1e9bd057ce732a73d933b739e9d0c30 Author: Bram Moolenaar <Bram@vim.org> Date: Sun Jul 21 16:42:00 2019 +0200 patch 8.1.1726: the eval.txt help file is too big Problem: The eval.txt help file is too big. Solution: Split off testing support to testing.txt. Move function details to where the functionality is explained.
author Bram Moolenaar <Bram@vim.org>
date Sun, 21 Jul 2019 16:45:05 +0200
parents d23afa4d8b63
children ea916dbbb9b9
comparison
equal deleted inserted replaced
17455:4ae435e21326 17456:e414281d8bb4
1 *sign.txt* For Vim version 8.1. Last change: 2019 Jun 04 1 *sign.txt* For Vim version 8.1. Last change: 2019 Jul 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
7 7
8 Sign Support Features *sign-support* 8 Sign Support Features *sign-support*
9 9
10 1. Introduction |sign-intro| 10 1. Introduction |sign-intro|
11 2. Commands |sign-commands| 11 2. Commands |sign-commands|
12 3. Functions |sign-functions-details|
12 13
13 {only available when compiled with the |+signs| feature} 14 {only available when compiled with the |+signs| feature}
14 15
15 ============================================================================== 16 ==============================================================================
16 1. Introduction *sign-intro* *signs* 17 1. Introduction *sign-intro* *signs*
342 343
343 :sign jump {id} group={group} [buffer={nr}] 344 :sign jump {id} group={group} [buffer={nr}]
344 Same but jump to the sign in group {group} 345 Same but jump to the sign in group {group}
345 346
346 347
348 ==============================================================================
349 3. Functions *sign-functions-details*
350
351 sign_define({name} [, {dict}]) *sign_define()*
352 sign_define({list})
353 Define a new sign named {name} or modify the attributes of an
354 existing sign. This is similar to the |:sign-define| command.
355
356 Prefix {name} with a unique text to avoid name collisions.
357 There is no {group} like with placing signs.
358
359 The {name} can be a String or a Number. The optional {dict}
360 argument specifies the sign attributes. The following values
361 are supported:
362 icon full path to the bitmap file for the sign.
363 linehl highlight group used for the whole line the
364 sign is placed in.
365 text text that is displayed when there is no icon
366 or the GUI is not being used.
367 texthl highlight group used for the text item
368
369 If the sign named {name} already exists, then the attributes
370 of the sign are updated.
371
372 The one argument {list} can be used to define a list of signs.
373 Each list item is a dictionary with the above items in {dict}
374 and a 'name' item for the sign name.
375
376 Returns 0 on success and -1 on failure. When the one argument
377 {list} is used, then returns a List of values one for each
378 defined sign.
379
380 Examples: >
381 call sign_define("mySign", {
382 \ "text" : "=>",
383 \ "texthl" : "Error",
384 \ "linehl" : "Search"})
385 call sign_define([
386 \ {'name' : 'sign1',
387 \ 'text' : '=>'},
388 \ {'name' : 'sign2',
389 \ 'text' : '!!'}
390 \ ])
391 <
392 sign_getdefined([{name}]) *sign_getdefined()*
393 Get a list of defined signs and their attributes.
394 This is similar to the |:sign-list| command.
395
396 If the {name} is not supplied, then a list of all the defined
397 signs is returned. Otherwise the attribute of the specified
398 sign is returned.
399
400 Each list item in the returned value is a dictionary with the
401 following entries:
402 icon full path to the bitmap file of the sign
403 linehl highlight group used for the whole line the
404 sign is placed in.
405 name name of the sign
406 text text that is displayed when there is no icon
407 or the GUI is not being used.
408 texthl highlight group used for the text item
409
410 Returns an empty List if there are no signs and when {name} is
411 not found.
412
413 Examples: >
414 " Get a list of all the defined signs
415 echo sign_getdefined()
416
417 " Get the attribute of the sign named mySign
418 echo sign_getdefined("mySign")
419 <
420 sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()*
421 Return a list of signs placed in a buffer or all the buffers.
422 This is similar to the |:sign-place-list| command.
423
424 If the optional buffer name {expr} is specified, then only the
425 list of signs placed in that buffer is returned. For the use
426 of {expr}, see |bufname()|. The optional {dict} can contain
427 the following entries:
428 group select only signs in this group
429 id select sign with this identifier
430 lnum select signs placed in this line. For the use
431 of {lnum}, see |line()|.
432 If {group} is '*', then signs in all the groups including the
433 global group are returned. If {group} is not supplied or is an
434 empty string, then only signs in the global group are
435 returned. If no arguments are supplied, then signs in the
436 global group placed in all the buffers are returned.
437 See |sign-group|.
438
439 Each list item in the returned value is a dictionary with the
440 following entries:
441 bufnr number of the buffer with the sign
442 signs list of signs placed in {bufnr}. Each list
443 item is a dictionary with the below listed
444 entries
445
446 The dictionary for each sign contains the following entries:
447 group sign group. Set to '' for the global group.
448 id identifier of the sign
449 lnum line number where the sign is placed
450 name name of the defined sign
451 priority sign priority
452
453 The returned signs in a buffer are ordered by their line
454 number and priority.
455
456 Returns an empty list on failure or if there are no placed
457 signs.
458
459 Examples: >
460 " Get a List of signs placed in eval.c in the
461 " global group
462 echo sign_getplaced("eval.c")
463
464 " Get a List of signs in group 'g1' placed in eval.c
465 echo sign_getplaced("eval.c", {'group' : 'g1'})
466
467 " Get a List of signs placed at line 10 in eval.c
468 echo sign_getplaced("eval.c", {'lnum' : 10})
469
470 " Get sign with identifier 10 placed in a.py
471 echo sign_getplaced("a.py", {'id' : 10})
472
473 " Get sign with id 20 in group 'g1' placed in a.py
474 echo sign_getplaced("a.py", {'group' : 'g1',
475 \ 'id' : 20})
476
477 " Get a List of all the placed signs
478 echo sign_getplaced()
479 <
480 *sign_jump()*
481 sign_jump({id}, {group}, {expr})
482 Open the buffer {expr} or jump to the window that contains
483 {expr} and position the cursor at sign {id} in group {group}.
484 This is similar to the |:sign-jump| command.
485
486 For the use of {expr}, see |bufname()|.
487
488 Returns the line number of the sign. Returns -1 if the
489 arguments are invalid.
490
491 Example: >
492 " Jump to sign 10 in the current buffer
493 call sign_jump(10, '', '')
494 <
495
496 *sign_place()*
497 sign_place({id}, {group}, {name}, {expr} [, {dict}])
498 Place the sign defined as {name} at line {lnum} in file or
499 buffer {expr} and assign {id} and {group} to sign. This is
500 similar to the |:sign-place| command.
501
502 If the sign identifier {id} is zero, then a new identifier is
503 allocated. Otherwise the specified number is used. {group} is
504 the sign group name. To use the global sign group, use an
505 empty string. {group} functions as a namespace for {id}, thus
506 two groups can use the same IDs. Refer to |sign-identifier|
507 and |sign-group| for more information.
508
509 {name} refers to a defined sign.
510 {expr} refers to a buffer name or number. For the accepted
511 values, see |bufname()|.
512
513 The optional {dict} argument supports the following entries:
514 lnum line number in the file or buffer
515 {expr} where the sign is to be placed.
516 For the accepted values, see |line()|.
517 priority priority of the sign. See
518 |sign-priority| for more information.
519
520 If the optional {dict} is not specified, then it modifies the
521 placed sign {id} in group {group} to use the defined sign
522 {name}.
523
524 Returns the sign identifier on success and -1 on failure.
525
526 Examples: >
527 " Place a sign named sign1 with id 5 at line 20 in
528 " buffer json.c
529 call sign_place(5, '', 'sign1', 'json.c',
530 \ {'lnum' : 20})
531
532 " Updates sign 5 in buffer json.c to use sign2
533 call sign_place(5, '', 'sign2', 'json.c')
534
535 " Place a sign named sign3 at line 30 in
536 " buffer json.c with a new identifier
537 let id = sign_place(0, '', 'sign3', 'json.c',
538 \ {'lnum' : 30})
539
540 " Place a sign named sign4 with id 10 in group 'g3'
541 " at line 40 in buffer json.c with priority 90
542 call sign_place(10, 'g3', 'sign4', 'json.c',
543 \ {'lnum' : 40, 'priority' : 90})
544 <
545
546 *sign_placelist()*
547 sign_placelist({list})
548 Place one or more signs. This is similar to the
549 |sign_place()| function. The {list} argument specifies the
550 List of signs to place. Each list item is a dict with the
551 following sign attributes:
552 buffer buffer name or number. For the accepted
553 values, see |bufname()|.
554 group sign group. {group} functions as a namespace
555 for {id}, thus two groups can use the same
556 IDs. If not specified or set to an empty
557 string, then the global group is used. See
558 |sign-group| for more information.
559 id sign identifier. If not specified or zero,
560 then a new unique identifier is allocated.
561 Otherwise the specified number is used. See
562 |sign-identifier| for more information.
563 lnum line number in the buffer {expr} where the
564 sign is to be placed. For the accepted values,
565 see |line()|.
566 name name of the sign to place. See |sign_define()|
567 for more information.
568 priority priority of the sign. When multiple signs are
569 placed on a line, the sign with the highest
570 priority is used. If not specified, the
571 default value of 10 is used. See
572 |sign-priority| for more information.
573
574 If {id} refers to an existing sign, then the existing sign is
575 modified to use the specified {name} and/or {priority}.
576
577 Returns a List of sign identifiers. If failed to place a
578 sign, the corresponding list item is set to -1.
579
580 Examples: >
581 " Place sign s1 with id 5 at line 20 and id 10 at line
582 " 30 in buffer a.c
583 let [n1, n2] = sign_placelist([
584 \ {'id' : 5,
585 \ 'name' : 's1',
586 \ 'buffer' : 'a.c',
587 \ 'lnum' : 20},
588 \ {'id' : 10,
589 \ 'name' : 's1',
590 \ 'buffer' : 'a.c',
591 \ 'lnum' : 30}
592 \ ])
593
594 " Place sign s1 in buffer a.c at line 40 and 50
595 " with auto-generated identifiers
596 let [n1, n2] = sign_placelist([
597 \ {'name' : 's1',
598 \ 'buffer' : 'a.c',
599 \ 'lnum' : 40},
600 \ {'name' : 's1',
601 \ 'buffer' : 'a.c',
602 \ 'lnum' : 50}
603 \ ])
604 <
605
606 sign_undefine([{name}]) *sign_undefine()*
607 sign_undefine({list})
608 Deletes a previously defined sign {name}. This is similar to
609 the |:sign-undefine| command. If {name} is not supplied, then
610 deletes all the defined signs.
611
612 The one argument {list} can be used to undefine a list of
613 signs. Each list item is the name of a sign.
614
615 Returns 0 on success and -1 on failure. For the one argument
616 {list} call, returns a list of values one for each undefined
617 sign.
618
619 Examples: >
620 " Delete a sign named mySign
621 call sign_undefine("mySign")
622
623 " Delete signs 'sign1' and 'sign2'
624 call sign_undefine(["sign1", "sign2"])
625
626 " Delete all the signs
627 call sign_undefine()
628 <
629
630 sign_unplace({group} [, {dict}]) *sign_unplace()*
631 Remove a previously placed sign in one or more buffers. This
632 is similar to the |:sign-unplace| command.
633
634 {group} is the sign group name. To use the global sign group,
635 use an empty string. If {group} is set to '*', then all the
636 groups including the global group are used.
637 The signs in {group} are selected based on the entries in
638 {dict}. The following optional entries in {dict} are
639 supported:
640 buffer buffer name or number. See |bufname()|.
641 id sign identifier
642 If {dict} is not supplied, then all the signs in {group} are
643 removed.
644
645 Returns 0 on success and -1 on failure.
646
647 Examples: >
648 " Remove sign 10 from buffer a.vim
649 call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
650
651 " Remove sign 20 in group 'g1' from buffer 3
652 call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
653
654 " Remove all the signs in group 'g2' from buffer 10
655 call sign_unplace('g2', {'buffer' : 10})
656
657 " Remove sign 30 in group 'g3' from all the buffers
658 call sign_unplace('g3', {'id' : 30})
659
660 " Remove all the signs placed in buffer 5
661 call sign_unplace('*', {'buffer' : 5})
662
663 " Remove the signs in group 'g4' from all the buffers
664 call sign_unplace('g4')
665
666 " Remove sign 40 from all the buffers
667 call sign_unplace('*', {'id' : 40})
668
669 " Remove all the placed signs from all the buffers
670 call sign_unplace('*')
671 <
672 sign_unplacelist({list}) *sign_unplacelist()*
673 Remove previously placed signs from one or more buffers. This
674 is similar to the |sign_unplace()| function.
675
676 The {list} argument specifies the List of signs to remove.
677 Each list item is a dict with the following sign attributes:
678 buffer buffer name or number. For the accepted
679 values, see |bufname()|. If not specified,
680 then the specified sign is removed from all
681 the buffers.
682 group sign group name. If not specified or set to an
683 empty string, then the global sign group is
684 used. If set to '*', then all the groups
685 including the global group are used.
686 id sign identifier. If not specified, then all
687 the signs in the specified group are removed.
688
689 Returns a List where an entry is set to 0 if the corresponding
690 sign was successfully removed or -1 on failure.
691
692 Example: >
693 " Remove sign with id 10 from buffer a.vim and sign
694 " with id 20 from buffer b.vim
695 call sign_unplacelist([
696 \ {'id' : 10, 'buffer' : "a.vim"},
697 \ {'id' : 20, 'buffer' : 'b.vim'},
698 \ ])
699 <
700
347 vim:tw=78:ts=8:noet:ft=help:norl: 701 vim:tw=78:ts=8:noet:ft=help:norl: