Mercurial > vim
annotate runtime/doc/sign.txt @ 13963:1174611ad715 v8.1.0000
Vim 8.1 release
commit https://github.com/vim/vim/commit/b1c9198afb7ff902588b45fbe44f0760a9f48375
Author: Bram Moolenaar <Bram@vim.org>
Date: Thu May 17 17:04:55 2018 +0200
Vim 8.1 release
Update version number and information. Fix a couple of tests.
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Thu, 17 May 2018 17:15:08 +0200 |
| parents | 9f48eab77d62 |
| children | 2f7e67dd088c |
| rev | line source |
|---|---|
| 13963 | 1 *sign.txt* For Vim version 8.1. Last change: 2016 Aug 17 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Gordon Prieur | |
| 5 and Bram Moolenaar | |
| 6 | |
| 7 | |
| 8 Sign Support Features *sign-support* | |
| 9 | |
| 10 1. Introduction |sign-intro| | |
| 11 2. Commands |sign-commands| | |
| 12 | |
| 13 {Vi does not have any of these features} | |
| 14 {only available when compiled with the |+signs| feature} | |
| 15 | |
| 16 ============================================================================== | |
| 17 1. Introduction *sign-intro* *signs* | |
| 18 | |
| 19 When a debugger or other IDE tool is driving an editor it needs to be able | |
| 20 to give specific highlights which quickly tell the user useful information | |
| 236 | 21 about the file. One example of this would be a debugger which had an icon |
| 22 in the left-hand column denoting a breakpoint. Another example might be an | |
| 23 arrow representing the Program Counter (PC). The sign features allow both | |
| 7 | 24 placement of a sign, or icon, in the left-hand side of the window and |
| 236 | 25 definition of a highlight which will be applied to that line. Displaying the |
| 7 | 26 sign as an image is most likely only feasible in gvim (although Sun |
| 236 | 27 Microsystem's dtterm does support this it's the only terminal emulator I know |
| 7 | 28 of which does). A text sign and the highlight should be feasible in any color |
| 29 terminal emulator. | |
| 30 | |
| 236 | 31 Signs and highlights are not useful just for debuggers. Sun's Visual |
| 7 | 32 WorkShop uses signs and highlights to mark build errors and SourceBrowser |
| 236 | 33 hits. Additionally, the debugger supports 8 to 10 different signs and |
| 7 | 34 highlight colors. |workshop| Same for Netbeans |netbeans|. |
| 35 | |
| 36 There are two steps in using signs: | |
| 37 | |
| 38 1. Define the sign. This specifies the image, text and highlighting. For | |
| 39 example, you can define a "break" sign with an image of a stop roadsign and | |
| 40 text "!!". | |
| 41 | |
| 42 2. Place the sign. This specifies the file and line number where the sign is | |
| 43 displayed. A defined sign can be placed several times in different lines | |
| 44 and files. | |
| 45 | |
| 46 When signs are defined for a file, Vim will automatically add a column of two | |
| 47 characters to display them in. When the last sign is unplaced the column | |
|
9860
9eaf8ef656e9
commit https://github.com/vim/vim/commit/0952131376a517fc12dc5ae908a97018b4ee23f0
Christian Brabandt <cb@256bit.org>
parents:
5908
diff
changeset
|
48 disappears again. This behavior can be changed with the 'signcolumn' option. |
|
9eaf8ef656e9
commit https://github.com/vim/vim/commit/0952131376a517fc12dc5ae908a97018b4ee23f0
Christian Brabandt <cb@256bit.org>
parents:
5908
diff
changeset
|
49 |
|
9eaf8ef656e9
commit https://github.com/vim/vim/commit/0952131376a517fc12dc5ae908a97018b4ee23f0
Christian Brabandt <cb@256bit.org>
parents:
5908
diff
changeset
|
50 The color of the column is set with the SignColumn group |hl-SignColumn|. |
|
9eaf8ef656e9
commit https://github.com/vim/vim/commit/0952131376a517fc12dc5ae908a97018b4ee23f0
Christian Brabandt <cb@256bit.org>
parents:
5908
diff
changeset
|
51 Example to set the color: > |
| 7 | 52 |
| 53 :highlight SignColumn guibg=darkgrey | |
| 54 | |
| 55 ============================================================================== | |
| 56 2. Commands *sign-commands* *:sig* *:sign* | |
| 57 | |
| 2152 | 58 Here is an example that places a sign "piet", displayed with the text ">>", in |
| 7 | 59 line 23 of the current file: > |
| 60 :sign define piet text=>> texthl=Search | |
| 61 :exe ":sign place 2 line=23 name=piet file=" . expand("%:p") | |
| 62 | |
| 63 And here is the command to delete it again: > | |
| 64 :sign unplace 2 | |
| 65 | |
| 66 Note that the ":sign" command cannot be followed by another command or a | |
| 67 comment. If you do need that, use the |:execute| command. | |
| 68 | |
| 69 | |
| 70 DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* | |
| 71 | |
| 72 :sign define {name} {argument}... | |
| 73 Define a new sign or set attributes for an existing sign. | |
| 74 The {name} can either be a number (all digits) or a name | |
|
2608
7d8af31066c8
Updated runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
2577
diff
changeset
|
75 starting with a non-digit. Leading digits are ignored, thus |
|
7d8af31066c8
Updated runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
2577
diff
changeset
|
76 "0012", "012" and "12" are considered the same name. |
| 7 | 77 About 120 different signs can be defined. |
| 78 | |
| 79 Accepted arguments: | |
| 80 | |
| 3256 | 81 icon={bitmap} |
| 7 | 82 Define the file name where the bitmap can be found. Should be |
| 83 a full path. The bitmap should fit in the place of two | |
| 84 characters. This is not checked. If the bitmap is too big it | |
| 85 will cause redraw problems. Only GTK 2 can scale the bitmap | |
| 86 to fit the space available. | |
| 87 toolkit supports ~ | |
| 88 GTK 1 pixmap (.xpm) | |
| 89 GTK 2 many | |
| 90 Motif pixmap (.xpm) | |
| 3256 | 91 Win32 .bmp, .ico, .cur |
| 92 pixmap (.xpm) |+xpm_w32| | |
| 7 | 93 |
| 94 linehl={group} | |
| 95 Highlighting group used for the whole line the sign is placed | |
| 96 in. Most useful is defining a background color. | |
| 97 | |
| 98 text={text} *E239* | |
| 99 Define the text that is displayed when there is no icon or the | |
| 100 GUI is not being used. Only printable characters are allowed | |
| 101 and they must occupy one or two display cells. | |
| 102 | |
| 103 texthl={group} | |
| 104 Highlighting group used for the text item. | |
| 105 | |
| 106 | |
| 107 DELETING A SIGN *:sign-undefine* *E155* | |
| 108 | |
| 109 :sign undefine {name} | |
| 110 Deletes a previously defined sign. If signs with this {name} | |
| 111 are still placed this will cause trouble. | |
| 112 | |
| 113 | |
| 114 LISTING SIGNS *:sign-list* *E156* | |
| 115 | |
| 116 :sign list Lists all defined signs and their attributes. | |
| 117 | |
| 118 :sign list {name} | |
| 119 Lists one defined sign and its attributes. | |
| 120 | |
| 121 | |
| 122 PLACING SIGNS *:sign-place* *E158* | |
| 123 | |
| 124 :sign place {id} line={lnum} name={name} file={fname} | |
| 125 Place sign defined as {name} at line {lnum} in file {fname}. | |
| 126 *:sign-fname* | |
| 127 The file {fname} must already be loaded in a buffer. The | |
| 128 exact file name must be used, wildcards, $ENV and ~ are not | |
| 129 expanded, white space must not be escaped. Trailing white | |
| 130 space is ignored. | |
| 131 | |
| 132 The sign is remembered under {id}, this can be used for | |
| 133 further manipulation. {id} must be a number. | |
| 134 It's up to the user to make sure the {id} is used only once in | |
| 135 each file (if it's used several times unplacing will also have | |
| 136 to be done several times and making changes may not work as | |
| 137 expected). | |
| 138 | |
| 139 :sign place {id} line={lnum} name={name} buffer={nr} | |
| 140 Same, but use buffer {nr}. | |
| 141 | |
| 5908 | 142 *E885* |
| 7 | 143 :sign place {id} name={name} file={fname} |
| 144 Change the placed sign {id} in file {fname} to use the defined | |
| 145 sign {name}. See remark above about {fname} |:sign-fname|. | |
| 146 This can be used to change the displayed sign without moving | |
| 147 it (e.g., when the debugger has stopped at a breakpoint). | |
| 148 | |
| 149 :sign place {id} name={name} buffer={nr} | |
| 150 Same, but use buffer {nr}. | |
| 151 | |
| 152 | |
| 153 REMOVING SIGNS *:sign-unplace* *E159* | |
| 154 | |
| 155 :sign unplace {id} file={fname} | |
| 156 Remove the previously placed sign {id} from file {fname}. | |
| 157 See remark above about {fname} |:sign-fname|. | |
| 158 | |
| 3672 | 159 :sign unplace * file={fname} |
| 160 Remove all placed signs in file {fname}. | |
| 161 | |
| 7 | 162 :sign unplace {id} buffer={nr} |
| 3672 | 163 Remove the previously placed sign {id} from buffer {nr}. |
| 164 | |
| 165 :sign unplace * buffer={nr} | |
| 166 Remove all placed signs in buffer {nr}. | |
| 7 | 167 |
| 168 :sign unplace {id} | |
| 169 Remove the previously placed sign {id} from all files it | |
| 170 appears in. | |
| 171 | |
| 172 :sign unplace * | |
| 173 Remove all placed signs. | |
| 174 | |
| 175 :sign unplace | |
| 176 Remove the placed sign at the cursor position. | |
| 177 | |
| 178 | |
| 5510 | 179 LISTING PLACED SIGNS *:sign-place-list* |
| 7 | 180 |
| 181 :sign place file={fname} | |
| 182 List signs placed in file {fname}. | |
| 183 See remark above about {fname} |:sign-fname|. | |
| 184 | |
| 185 :sign place buffer={nr} | |
| 186 List signs placed in buffer {nr}. | |
| 187 | |
| 188 :sign place List placed signs in all files. | |
| 189 | |
| 190 | |
| 191 JUMPING TO A SIGN *:sign-jump* *E157* | |
| 192 | |
| 193 :sign jump {id} file={fname} | |
| 194 Open the file {fname} or jump to the window that contains | |
| 195 {fname} and position the cursor at sign {id}. | |
| 196 See remark above about {fname} |:sign-fname|. | |
| 197 If the file isn't displayed in window and the current file can | |
| 198 not be |abandon|ed this fails. | |
| 199 | |
|
9908
2b6654519a7c
commit https://github.com/vim/vim/commit/7571d55f7dcc009a375b2124cce2c8b21f361234
Christian Brabandt <cb@256bit.org>
parents:
9860
diff
changeset
|
200 :sign jump {id} buffer={nr} *E934* |
|
2b6654519a7c
commit https://github.com/vim/vim/commit/7571d55f7dcc009a375b2124cce2c8b21f361234
Christian Brabandt <cb@256bit.org>
parents:
9860
diff
changeset
|
201 Same, but use buffer {nr}. This fails if buffer {nr} does not |
|
2b6654519a7c
commit https://github.com/vim/vim/commit/7571d55f7dcc009a375b2124cce2c8b21f361234
Christian Brabandt <cb@256bit.org>
parents:
9860
diff
changeset
|
202 have a name. |
|
2b6654519a7c
commit https://github.com/vim/vim/commit/7571d55f7dcc009a375b2124cce2c8b21f361234
Christian Brabandt <cb@256bit.org>
parents:
9860
diff
changeset
|
203 |
| 7 | 204 |
| 205 vim:tw=78:ts=8:ft=help:norl: |