Mercurial > vim
comparison runtime/doc/eval.txt @ 15209:3a99b2e6d136 v8.1.0614
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 | 8b334e4cb97f |
children | dada0b389d4f |
comparison
equal
deleted
inserted
replaced
15208:acf68008ca43 | 15209:3a99b2e6d136 |
---|---|
2406 sha256({string}) String SHA256 checksum of {string} | 2406 sha256({string}) String SHA256 checksum of {string} |
2407 shellescape({string} [, {special}]) | 2407 shellescape({string} [, {special}]) |
2408 String escape {string} for use as shell | 2408 String escape {string} for use as shell |
2409 command argument | 2409 command argument |
2410 shiftwidth([{col}]) Number effective value of 'shiftwidth' | 2410 shiftwidth([{col}]) Number effective value of 'shiftwidth' |
2411 sign_define({name} [, {dict}]) Number define or update a sign | |
2412 sign_getdefined([{name}]) List get a list of defined signs | |
2413 sign_getplaced([{expr} [, {dict}]]) | |
2414 List get a list of placed signs | |
2415 sign_place({id}, {group}, {name}, {expr} [, {dict}]) | |
2416 Number place a sign | |
2417 sign_undefine([{name}]) Number undefine a sign | |
2418 sign_unplace({group} [, {dict}]) | |
2419 Number unplace a sign | |
2411 simplify({filename}) String simplify filename as much as possible | 2420 simplify({filename}) String simplify filename as much as possible |
2412 sin({expr}) Float sine of {expr} | 2421 sin({expr}) Float sine of {expr} |
2413 sinh({expr}) Float hyperbolic sine of {expr} | 2422 sinh({expr}) Float hyperbolic sine of {expr} |
2414 sort({list} [, {func} [, {dict}]]) | 2423 sort({list} [, {func} [, {dict}]]) |
2415 List sort {list}, using {func} to compare | 2424 List sort {list}, using {func} to compare |
7856 When there is one argument {col} this is used as column number | 7865 When there is one argument {col} this is used as column number |
7857 for which to return the 'shiftwidth' value. This matters for the | 7866 for which to return the 'shiftwidth' value. This matters for the |
7858 'vartabstop' feature. If the 'vartabstop' setting is enabled and | 7867 'vartabstop' feature. If the 'vartabstop' setting is enabled and |
7859 no {col} argument is given, column 1 will be assumed. | 7868 no {col} argument is given, column 1 will be assumed. |
7860 | 7869 |
7861 | 7870 sign_define({name} [, {dict}]) *sign_define()* |
7871 Define a new sign named {name} or modify the attributes of an | |
7872 existing sign. This is similar to the |:sign-define| command. | |
7873 | |
7874 Prefix {name} with a unique text to avoid name collisions. | |
7875 There is no {group} like with placing signs. | |
7876 | |
7877 The {name} can be a String or a Number. The optional {dict} | |
7878 argument specifies the sign attributes. The following values | |
7879 are supported: | |
7880 icon full path to the bitmap file for the sign. | |
7881 linehl highlight group used for the whole line the | |
7882 sign is placed in. | |
7883 text text that is displayed when there is no icon | |
7884 or the GUI is not being used. | |
7885 texthl highlight group used for the text item | |
7886 For an existing sign, the attributes are updated. | |
7887 | |
7888 Returns 0 on success and -1 on failure. | |
7889 | |
7890 Examples: > | |
7891 call sign_define("mySign", {"text" : "=>", "texthl" : | |
7892 \ "Error", "linehl" : "Search"}) | |
7893 < | |
7894 sign_getdefined([{name}]) *sign_getdefined()* | |
7895 Get a list of defined signs and their attributes. | |
7896 This is similar to the |:sign-list| command. | |
7897 | |
7898 If the {name} is not supplied, then a list of all the defined | |
7899 signs is returned. Otherwise the attribute of the specified | |
7900 sign is returned. | |
7901 | |
7902 Each list item in the returned value is a dictionary with the | |
7903 following entries: | |
7904 icon full path to the bitmap file of the sign | |
7905 linehl highlight group used for the whole line the | |
7906 sign is placed in. | |
7907 name name of the sign | |
7908 text text that is displayed when there is no icon | |
7909 or the GUI is not being used. | |
7910 texthl highlight group used for the text item | |
7911 | |
7912 Returns an empty List if there are no signs and when {name} is | |
7913 not found. | |
7914 | |
7915 Examples: > | |
7916 " Get a list of all the defined signs | |
7917 echo sign_getdefined() | |
7918 | |
7919 " Get the attribute of the sign named mySign | |
7920 echo sign_getdefined("mySign") | |
7921 < | |
7922 sign_getplaced([{expr} [, {dict}]]) *sign_getplaced()* | |
7923 Return a list of signs placed in a buffer or all the buffers. | |
7924 This is similar to the |:sign-place-list| command. | |
7925 | |
7926 If the optional buffer name {expr} is specified, then only the | |
7927 list of signs placed in that buffer is returned. For the use | |
7928 of {expr}, see |bufname()|. The optional {dict} can contain | |
7929 the following entries: | |
7930 group select only signs in this group | |
7931 id select sign with this identifier | |
7932 lnum select signs placed in this line. For the use | |
7933 of {lnum}, see |line()|. | |
7934 If {group} is '*', then signs in all the groups including the | |
7935 global group are returned. If {group} is not supplied, then | |
7936 only signs in the global group are returned. If no arguments | |
7937 are supplied, then signs in the global group placed in all the | |
7938 buffers are returned. | |
7939 | |
7940 Each list item in the returned value is a dictionary with the | |
7941 following entries: | |
7942 bufnr number of the buffer with the sign | |
7943 signs list of signs placed in {bufnr}. Each list | |
7944 item is a dictionary with the below listed | |
7945 entries | |
7946 | |
7947 The dictionary for each sign contains the following entries: | |
7948 group sign group. Set to '' for the global group. | |
7949 id identifier of the sign | |
7950 lnum line number where the sign is placed | |
7951 name name of the defined sign | |
7952 priority sign priority | |
7953 | |
7954 Returns an empty list on failure. | |
7955 | |
7956 Examples: > | |
7957 " Get a List of signs placed in eval.c in the | |
7958 " global group | |
7959 echo sign_getplaced("eval.c") | |
7960 | |
7961 " Get a List of signs in group 'g1' placed in eval.c | |
7962 echo sign_getplaced("eval.c", {'group' : 'g1'}) | |
7963 | |
7964 " Get a List of signs placed at line 10 in eval.c | |
7965 echo sign_getplaced("eval.c", {'lnum' : 10}) | |
7966 | |
7967 " Get sign with identifier 10 placed in a.py | |
7968 echo sign_getplaced("a.py", {'id' : 10'}) | |
7969 | |
7970 " Get sign with id 20 in group 'g1' placed in a.py | |
7971 echo sign_getplaced("a.py", {'group' : 'g1', | |
7972 \ 'id' : 20'}) | |
7973 | |
7974 " Get a List of all the placed signs | |
7975 echo sign_getplaced() | |
7976 < | |
7977 *sign_place()* | |
7978 sign_place({id}, {group}, {name}, {expr} [, {dict}]) | |
7979 Place the sign defined as {name} at line {lnum} in file {expr} | |
7980 and assign {id} and {group} to sign. This is similar to the | |
7981 |:sign-place| command. | |
7982 | |
7983 If the sign identifier {id} is zero, then a new identifier is | |
7984 allocated. Otherwise the specified number is used. {group} is | |
7985 the sign group name. To use the global sign group, use an | |
7986 empty string. {group} functions as a namespace for {id}, thus | |
7987 two groups can use the same IDs. | |
7988 | |
7989 {name} refers to a defined sign. | |
7990 {expr} refers to a buffer name or number. For the accepted | |
7991 values, see |bufname()|. | |
7992 | |
7993 The optional {dict} argument supports the following entries: | |
7994 lnum line number in the buffer {expr} where | |
7995 the sign is to be placed. For the | |
7996 accepted values, see |line()|. | |
7997 priority priority of the sign. See | |
7998 |sign-priority| for more information. | |
7999 | |
8000 If the optional {dict} is not specified, then it modifies the | |
8001 placed sign {id} in group {group} to use the defined sign | |
8002 {name}. | |
8003 | |
8004 Returns the sign identifier on success and -1 on failure. | |
8005 | |
8006 Examples: > | |
8007 " Place a sign named sign1 with id 5 at line 20 in | |
8008 " buffer json.c | |
8009 call sign_place(5, '', 'sign1', 'json.c', | |
8010 \ {'lnum' : 20}) | |
8011 | |
8012 " Updates sign 5 in buffer json.c to use sign2 | |
8013 call sign_place(5, '', 'sign2', 'json.c') | |
8014 | |
8015 " Place a sign named sign3 at line 30 in | |
8016 " buffer json.c with a new identifier | |
8017 let id = sign_place(0, '', 'sign3', 'json.c', | |
8018 \ {'lnum' : 30}) | |
8019 | |
8020 " Place a sign named sign4 with id 10 in group 'g3' | |
8021 " at line 40 in buffer json.c with priority 90 | |
8022 call sign_place(10, 'g3', 'sign4', 'json.c', | |
8023 \ {'lnum' : 40, 'priority' : 90}) | |
8024 < | |
8025 sign_undefine([{name}]) *sign_undefine()* | |
8026 Deletes a previously defined sign {name}. This is similar to | |
8027 the |:sign-undefine| command. If {name} is not supplied, then | |
8028 deletes all the defined signs. | |
8029 | |
8030 Returns 0 on success and -1 on failure. | |
8031 | |
8032 Examples: > | |
8033 " Delete a sign named mySign | |
8034 call sign_undefine("mySign") | |
8035 | |
8036 " Delete all the signs | |
8037 call sign_undefine() | |
8038 < | |
8039 sign_unplace({group} [, {dict}]) *sign_unplace()* | |
8040 Remove a previously placed sign in one or more buffers. This | |
8041 is similar to the |:sign-unplace()| command. | |
8042 | |
8043 {group} is the sign group name. To use the global sign group, | |
8044 use an empty string. If {group} is set to '*', then all the | |
8045 groups including the global group are used. | |
8046 The signs in {group} are selected based on the entries in | |
8047 {dict}. The following optional entries in {dict} are | |
8048 supported: | |
8049 buffer buffer name or number. See |bufname()|. | |
8050 id sign identifier | |
8051 If {dict} is not supplied, then all the signs in {group} are | |
8052 removed. | |
8053 | |
8054 Returns 0 on success and -1 on failure. | |
8055 | |
8056 Examples: > | |
8057 " Remove sign 10 from buffer a.vim | |
8058 call sign_unplace('', {'buffer' : "a.vim", 'id' : 10}) | |
8059 | |
8060 " Remove sign 20 in group 'g1' from buffer 3 | |
8061 call sign_unplace('g1', {'buffer' : 3, 'id' : 20}) | |
8062 | |
8063 " Remove all the signs in group 'g2' from buffer 10 | |
8064 call sign_unplace('g2', {'buffer' : 10}) | |
8065 | |
8066 " Remove sign 30 in group 'g3' from all the buffers | |
8067 call sign_unplace('g3', {'id' : 30}) | |
8068 | |
8069 " Remove all the signs placed in buffer 5 | |
8070 call sign_unplace('*', {'buffer' : 5}) | |
8071 | |
8072 " Remove the signs in group 'g4' from all the buffers | |
8073 call sign_unplace('g4') | |
8074 | |
8075 " Remove sign 40 from all the buffers | |
8076 call sign_unplace('*', {'id' : 40}) | |
8077 | |
8078 " Remove all the placed signs from all the buffers | |
8079 call sign_unplace('*') | |
8080 < | |
7862 simplify({filename}) *simplify()* | 8081 simplify({filename}) *simplify()* |
7863 Simplify the file name as much as possible without changing | 8082 Simplify the file name as much as possible without changing |
7864 the meaning. Shortcuts (on MS-Windows) or symbolic links (on | 8083 the meaning. Shortcuts (on MS-Windows) or symbolic links (on |
7865 Unix) are not resolved. If the first path component in | 8084 Unix) are not resolved. If the first path component in |
7866 {filename} designates the current directory, this will be | 8085 {filename} designates the current directory, this will be |