diff options
author | Bram Moolenaar <Bram@vim.org> | 2018-12-21 15:17:36 +0100 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2018-12-21 15:17:36 +0100 |
commit | 162b71479bd4dcdb3a2ef9198a1444f6f99e6843 (patch) | |
tree | edd67e40cafeff24ad1631f9035ecc132e73b22b /runtime/doc | |
parent | 48f377a476e4a3312aa0e3535aba170484b59483 (diff) |
patch 8.1.0614: placing signs can be complicatedv8.1.0614
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)
Diffstat (limited to 'runtime/doc')
-rw-r--r-- | runtime/doc/eval.txt | 219 | ||||
-rw-r--r-- | runtime/doc/sign.txt | 99 | ||||
-rw-r--r-- | runtime/doc/usr_41.txt | 8 |
3 files changed, 324 insertions, 2 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index afc4fe134b..f76af3848a 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -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 diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt index bd63ea9ade..115e1faa45 100644 --- a/runtime/doc/sign.txt +++ b/runtime/doc/sign.txt @@ -1,4 +1,4 @@ -*sign.txt* For Vim version 8.1. Last change: 2016 Aug 17 +*sign.txt* For Vim version 8.1. Last change: 2018 Dec 21 VIM REFERENCE MANUAL by Gordon Prieur @@ -51,6 +51,20 @@ The color of the column is set with the SignColumn group |hl-SignColumn|. Example to set the color: > :highlight SignColumn guibg=darkgrey +< + *sign-group* +Each sign can be assigned to either the global group or a named group. When +placing a sign, if a group name is not supplied, or an empty string is used, +then the sign is placed in the global group. Otherwise the sign is placed in +the named group. The sign identifier is unique within a group. The sign group +allows Vim plugins to use unique signs without interfering with other plugins +using signs. + + *sign-priority* +Each placed sign is assigned a priority value. When multiple signs are placed +on the same line, the attributes of the sign with the highest priority is used +independent of the sign group. The default priority for a sign is 10. The +priority is assigned at the time of placing a sign. ============================================================================== 2. Commands *sign-commands* *:sig* *:sign* @@ -69,6 +83,8 @@ comment. If you do need that, use the |:execute| command. DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* +See |sign_define()| for the equivalent Vim script function. + :sign define {name} {argument}... Define a new sign or set attributes for an existing sign. The {name} can either be a number (all digits) or a name @@ -106,13 +122,18 @@ DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* DELETING A SIGN *:sign-undefine* *E155* +See |sign_undefine()| for the equivalent Vim script function. + :sign undefine {name} Deletes a previously defined sign. If signs with this {name} are still placed this will cause trouble. + LISTING SIGNS *:sign-list* *E156* +See |sign_getdefined()| for the equivalent Vim script function. + :sign list Lists all defined signs and their attributes. :sign list {name} @@ -121,6 +142,8 @@ LISTING SIGNS *:sign-list* *E156* PLACING SIGNS *:sign-place* *E158* +See |sign_place()| for the equivalent Vim script function. + :sign place {id} line={lnum} name={name} file={fname} Place sign defined as {name} at line {lnum} in file {fname}. *:sign-fname* @@ -136,6 +159,25 @@ PLACING SIGNS *:sign-place* *E158* to be done several times and making changes may not work as expected). + The following optional sign attributes can be specified before + "file=": + group={group} Place sign in sign group {group} + priority={prio} Assign priority {prio} to sign + + By default, the sign is placed in the global sign group. + + By default, the sign is assigned a default priority of 10. To + assign a different priority value, use "priority={prio}" to + specify a value. The priority is used to determine the + highlight group used when multiple signs are placed on the + same line. + + Examples: > + :sign place 5 line=3 name=sign1 file=a.py + :sign place 6 group=g2 line=2 name=sign2 file=x.py + :sign place 9 group=g2 priority=50 line=5 + \ name=sign1 file=a.py +< :sign place {id} line={lnum} name={name} buffer={nr} Same, but use buffer {nr}. @@ -146,31 +188,73 @@ PLACING SIGNS *:sign-place* *E158* This can be used to change the displayed sign without moving it (e.g., when the debugger has stopped at a breakpoint). + The optional "group={group}" attribute can be used before + "file=" to select a sign in a particular group. + :sign place {id} name={name} buffer={nr} Same, but use buffer {nr}. REMOVING SIGNS *:sign-unplace* *E159* +See |sign_unplace()| for the equivalent Vim script function. + :sign unplace {id} file={fname} Remove the previously placed sign {id} from file {fname}. See remark above about {fname} |:sign-fname|. +:sign unplace {id} group={group} file={fname} + Same but remove the sign {id} in sign group {group}. + +:sign unplace {id} group=* file={fname} + Same but remove the sign {id} from all the sign groups. + :sign unplace * file={fname} Remove all placed signs in file {fname}. +:sign unplace * group={group} file={fname} + Remove all placed signs in group {group} from file {fname}. + +:sign unplace * group=* file={fname} + Remove all placed signs in all the groups from file {fname}. + :sign unplace {id} buffer={nr} Remove the previously placed sign {id} from buffer {nr}. +:sign unplace {id} group={group} buffer={nr} + Remove the previously placed sign {id} in group {group} from + buffer {nr}. + +:sign unplace {id} group=* buffer={nr} + Remove the previously placed sign {id} in all the groups from + buffer {nr}. + :sign unplace * buffer={nr} Remove all placed signs in buffer {nr}. +:sign unplace * group={group} buffer={nr} + Remove all placed signs in group {group} from buffer {nr}. + +:sign unplace * group=* buffer={nr} + Remove all placed signs in all the groups from buffer {nr}. + :sign unplace {id} Remove the previously placed sign {id} from all files it appears in. +:sign unplace {id} group={group} + Remove the previously placed sign {id} in group {group} from + all files it appears in. + +:sign unplace {id} group=* + Remove the previously placed sign {id} in all the groups from + all the files it appears in. + :sign unplace * - Remove all placed signs. + Remove all placed signs in the global group. + +:sign unplace * group=* + Remove all placed signs in all the groups. :sign unplace Remove the placed sign at the cursor position. @@ -178,15 +262,26 @@ REMOVING SIGNS *:sign-unplace* *E159* LISTING PLACED SIGNS *:sign-place-list* +See |sign_getplaced()| for the equivalent Vim script function. + :sign place file={fname} List signs placed in file {fname}. See remark above about {fname} |:sign-fname|. +:sign place group={group} file={fname} + List signs in group {group} placed in file {fname}. + :sign place buffer={nr} List signs placed in buffer {nr}. +:sign place group={group} buffer={nr} + List signs in group {group} placed in buffer {nr}. + :sign place List placed signs in all files. +:sign place group={group} + List placed signs in all sign groups in all the files. + JUMPING TO A SIGN *:sign-jump* *E157* diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 1ad044b324..343d476a4c 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -983,6 +983,14 @@ Jobs: *job-functions* job_info() get information about a job job_setoptions() set options for a job +Signs: *sign-functions* + sign_define() define or update a sign + sign_getdefined() get a list of defined signs + sign_getplaced() get a list of placed signs + sign_place() place a sign + sign_undefine() undefine a sign + sign_unplace() unplace a sign + Terminal window: *terminal-functions* term_start() open a terminal window and run a job term_list() get the list of terminal buffers |