Skip to content
Permalink
Browse files

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)
  • Loading branch information...
brammool committed Dec 21, 2018
1 parent 48f377a commit 162b71479bd4dcdb3a2ef9198a1444f6f99e6843
Showing with 2,071 additions and 285 deletions.
  1. +219 −0 runtime/doc/eval.txt
  2. +97 −2 runtime/doc/sign.txt
  3. +8 −0 runtime/doc/usr_41.txt
  4. +8 −0 src/alloc.h
  5. +227 −89 src/buffer.c
  6. +332 −10 src/evalfunc.c
  7. +498 −170 src/ex_cmds.c
  8. +4 −0 src/globals.h
  9. +14 −0 src/list.c
  10. +13 −0 src/misc2.c
  11. +2 −2 src/netbeans.c
  12. +11 −6 src/proto/buffer.pro
  13. +7 −0 src/proto/ex_cmds.pro
  14. +1 −0 src/proto/list.pro
  15. +1 −0 src/proto/misc2.pro
  16. +5 −0 src/structs.h
  17. +621 −5 src/testdir/test_signs.vim
  18. +2 −0 src/version.c
  19. +1 −1 src/workshop.c
@@ -2408,6 +2408,15 @@ shellescape({string} [, {special}])
String escape {string} for use as shell
command argument
shiftwidth([{col}]) Number effective value of 'shiftwidth'
sign_define({name} [, {dict}]) Number define or update a sign
sign_getdefined([{name}]) List get a list of defined signs
sign_getplaced([{expr} [, {dict}]])
List get a list of placed signs
sign_place({id}, {group}, {name}, {expr} [, {dict}])
Number place a sign
sign_undefine([{name}]) Number undefine a sign
sign_unplace({group} [, {dict}])
Number unplace a sign
simplify({filename}) String simplify filename as much as possible
sin({expr}) Float sine of {expr}
sinh({expr}) Float hyperbolic sine of {expr}
@@ -7858,7 +7867,217 @@ shiftwidth([{col}]) *shiftwidth()*
'vartabstop' feature. If the 'vartabstop' setting is enabled and
no {col} argument is given, column 1 will be assumed.

sign_define({name} [, {dict}]) *sign_define()*
Define a new sign named {name} or modify the attributes of an
existing sign. This is similar to the |:sign-define| command.

Prefix {name} with a unique text to avoid name collisions.
There is no {group} like with placing signs.

The {name} can be a String or a Number. The optional {dict}
argument specifies the sign attributes. The following values
are supported:
icon full path to the bitmap file for the sign.
linehl highlight group used for the whole line the
sign is placed in.
text text that is displayed when there is no icon
or the GUI is not being used.
texthl highlight group used for the text item
For an existing sign, the attributes are updated.

Returns 0 on success and -1 on failure.

Examples: >
call sign_define("mySign", {"text" : "=>", "texthl" :
\ "Error", "linehl" : "Search"})
<
sign_getdefined([{name}]) *sign_getdefined()*
Get a list of defined signs and their attributes.
This is similar to the |:sign-list| command.

If the {name} is not supplied, then a list of all the defined
signs is returned. Otherwise the attribute of the specified
sign is returned.

Each list item in the returned value is a dictionary with the
following entries:
icon full path to the bitmap file of the sign
linehl highlight group used for the whole line the
sign is placed in.
name name of the sign
text text that is displayed when there is no icon
or the GUI is not being used.
texthl highlight group used for the text item

Returns an empty List if there are no signs and when {name} is
not found.

Examples: >
" Get a list of all the defined signs
echo sign_getdefined()

" Get the attribute of the sign named mySign
echo sign_getdefined("mySign")
<
sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()*
Return a list of signs placed in a buffer or all the buffers.
This is similar to the |:sign-place-list| command.

If the optional buffer name {expr} is specified, then only the
list of signs placed in that buffer is returned. For the use
of {expr}, see |bufname()|. The optional {dict} can contain
the following entries:
group select only signs in this group
id select sign with this identifier
lnum select signs placed in this line. For the use
of {lnum}, see |line()|.
If {group} is '*', then signs in all the groups including the
global group are returned. If {group} is not supplied, then
only signs in the global group are returned. If no arguments
are supplied, then signs in the global group placed in all the
buffers are returned.

Each list item in the returned value is a dictionary with the
following entries:
bufnr number of the buffer with the sign
signs list of signs placed in {bufnr}. Each list
item is a dictionary with the below listed
entries

The dictionary for each sign contains the following entries:
group sign group. Set to '' for the global group.
id identifier of the sign
lnum line number where the sign is placed
name name of the defined sign
priority sign priority

Returns an empty list on failure.

Examples: >
" Get a List of signs placed in eval.c in the
" global group
echo sign_getplaced("eval.c")

" Get a List of signs in group 'g1' placed in eval.c
echo sign_getplaced("eval.c", {'group' : 'g1'})

" Get a List of signs placed at line 10 in eval.c
echo sign_getplaced("eval.c", {'lnum' : 10})

" Get sign with identifier 10 placed in a.py
echo sign_getplaced("a.py", {'id' : 10'})

" Get sign with id 20 in group 'g1' placed in a.py
echo sign_getplaced("a.py", {'group' : 'g1',
\ 'id' : 20'})

" Get a List of all the placed signs
echo sign_getplaced()
<
*sign_place()*
sign_place({id}, {group}, {name}, {expr} [, {dict}])
Place the sign defined as {name} at line {lnum} in file {expr}
and assign {id} and {group} to sign. This is similar to the
|:sign-place| command.

If the sign identifier {id} is zero, then a new identifier is
allocated. Otherwise the specified number is used. {group} is
the sign group name. To use the global sign group, use an
empty string. {group} functions as a namespace for {id}, thus
two groups can use the same IDs.

{name} refers to a defined sign.
{expr} refers to a buffer name or number. For the accepted
values, see |bufname()|.

The optional {dict} argument supports the following entries:
lnum line number in the buffer {expr} where
the sign is to be placed. For the
accepted values, see |line()|.
priority priority of the sign. See
|sign-priority| for more information.

If the optional {dict} is not specified, then it modifies the
placed sign {id} in group {group} to use the defined sign
{name}.

Returns the sign identifier on success and -1 on failure.

Examples: >
" Place a sign named sign1 with id 5 at line 20 in
" buffer json.c
call sign_place(5, '', 'sign1', 'json.c',
\ {'lnum' : 20})

" Updates sign 5 in buffer json.c to use sign2
call sign_place(5, '', 'sign2', 'json.c')

" Place a sign named sign3 at line 30 in
" buffer json.c with a new identifier
let id = sign_place(0, '', 'sign3', 'json.c',
\ {'lnum' : 30})

" Place a sign named sign4 with id 10 in group 'g3'
" at line 40 in buffer json.c with priority 90
call sign_place(10, 'g3', 'sign4', 'json.c',
\ {'lnum' : 40, 'priority' : 90})
<
sign_undefine([{name}]) *sign_undefine()*
Deletes a previously defined sign {name}. This is similar to
the |:sign-undefine| command. If {name} is not supplied, then
deletes all the defined signs.

Returns 0 on success and -1 on failure.

Examples: >
" Delete a sign named mySign
call sign_undefine("mySign")

" Delete all the signs
call sign_undefine()
<
sign_unplace({group} [, {dict}]) *sign_unplace()*
Remove a previously placed sign in one or more buffers. This
is similar to the |:sign-unplace()| command.

{group} is the sign group name. To use the global sign group,
use an empty string. If {group} is set to '*', then all the
groups including the global group are used.
The signs in {group} are selected based on the entries in
{dict}. The following optional entries in {dict} are
supported:
buffer buffer name or number. See |bufname()|.
id sign identifier
If {dict} is not supplied, then all the signs in {group} are
removed.

Returns 0 on success and -1 on failure.

Examples: >
" Remove sign 10 from buffer a.vim
call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})

" Remove sign 20 in group 'g1' from buffer 3
call sign_unplace('g1', {'buffer' : 3, 'id' : 20})

" Remove all the signs in group 'g2' from buffer 10
call sign_unplace('g2', {'buffer' : 10})

" Remove sign 30 in group 'g3' from all the buffers
call sign_unplace('g3', {'id' : 30})

" Remove all the signs placed in buffer 5
call sign_unplace('*', {'buffer' : 5})

" Remove the signs in group 'g4' from all the buffers
call sign_unplace('g4')

" Remove sign 40 from all the buffers
call sign_unplace('*', {'id' : 40})

" Remove all the placed signs from all the buffers
call sign_unplace('*')
<
simplify({filename}) *simplify()*
Simplify the file name as much as possible without changing
the meaning. Shortcuts (on MS-Windows) or symbolic links (on

0 comments on commit 162b714

Please sign in to comment.
You can’t perform that action at this time.