Mercurial > vim
annotate runtime/doc/sign.txt @ 5146:6ec6b7ff2d43 v7.4a
Vim 7.4a BETA release.
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Sat, 06 Jul 2013 15:44:11 +0200 |
| parents | 11d40fc82f11 |
| children | 09c88160095d |
| rev | line source |
|---|---|
| 5146 | 1 *sign.txt* For Vim version 7.4a. Last change: 2012 Jul 10 |
| 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 | |
| 48 disappears again. The color of the column is set with the SignColumn group | |
| 49 |hl-SignColumn|. Example to set the color: > | |
| 50 | |
| 51 :highlight SignColumn guibg=darkgrey | |
| 52 | |
| 53 ============================================================================== | |
| 54 2. Commands *sign-commands* *:sig* *:sign* | |
| 55 | |
| 2152 | 56 Here is an example that places a sign "piet", displayed with the text ">>", in |
| 7 | 57 line 23 of the current file: > |
| 58 :sign define piet text=>> texthl=Search | |
| 59 :exe ":sign place 2 line=23 name=piet file=" . expand("%:p") | |
| 60 | |
| 61 And here is the command to delete it again: > | |
| 62 :sign unplace 2 | |
| 63 | |
| 64 Note that the ":sign" command cannot be followed by another command or a | |
| 65 comment. If you do need that, use the |:execute| command. | |
| 66 | |
| 67 | |
| 68 DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* | |
| 69 | |
| 70 :sign define {name} {argument}... | |
| 71 Define a new sign or set attributes for an existing sign. | |
| 72 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
|
73 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
|
74 "0012", "012" and "12" are considered the same name. |
| 7 | 75 About 120 different signs can be defined. |
| 76 | |
| 77 Accepted arguments: | |
| 78 | |
| 3256 | 79 icon={bitmap} |
| 7 | 80 Define the file name where the bitmap can be found. Should be |
| 81 a full path. The bitmap should fit in the place of two | |
| 82 characters. This is not checked. If the bitmap is too big it | |
| 83 will cause redraw problems. Only GTK 2 can scale the bitmap | |
| 84 to fit the space available. | |
| 85 toolkit supports ~ | |
| 86 GTK 1 pixmap (.xpm) | |
| 87 GTK 2 many | |
| 88 Motif pixmap (.xpm) | |
| 3256 | 89 Win32 .bmp, .ico, .cur |
| 90 pixmap (.xpm) |+xpm_w32| | |
| 7 | 91 |
| 92 linehl={group} | |
| 93 Highlighting group used for the whole line the sign is placed | |
| 94 in. Most useful is defining a background color. | |
| 95 | |
| 96 text={text} *E239* | |
| 97 Define the text that is displayed when there is no icon or the | |
| 98 GUI is not being used. Only printable characters are allowed | |
| 99 and they must occupy one or two display cells. | |
| 100 | |
| 101 texthl={group} | |
| 102 Highlighting group used for the text item. | |
| 103 | |
| 104 | |
| 105 DELETING A SIGN *:sign-undefine* *E155* | |
| 106 | |
| 107 :sign undefine {name} | |
| 108 Deletes a previously defined sign. If signs with this {name} | |
| 109 are still placed this will cause trouble. | |
| 110 | |
| 111 | |
| 112 LISTING SIGNS *:sign-list* *E156* | |
| 113 | |
| 114 :sign list Lists all defined signs and their attributes. | |
| 115 | |
| 116 :sign list {name} | |
| 117 Lists one defined sign and its attributes. | |
| 118 | |
| 119 | |
| 120 PLACING SIGNS *:sign-place* *E158* | |
| 121 | |
| 122 :sign place {id} line={lnum} name={name} file={fname} | |
| 123 Place sign defined as {name} at line {lnum} in file {fname}. | |
| 124 *:sign-fname* | |
| 125 The file {fname} must already be loaded in a buffer. The | |
| 126 exact file name must be used, wildcards, $ENV and ~ are not | |
| 127 expanded, white space must not be escaped. Trailing white | |
| 128 space is ignored. | |
| 129 | |
| 130 The sign is remembered under {id}, this can be used for | |
| 131 further manipulation. {id} must be a number. | |
| 132 It's up to the user to make sure the {id} is used only once in | |
| 133 each file (if it's used several times unplacing will also have | |
| 134 to be done several times and making changes may not work as | |
| 135 expected). | |
| 136 | |
| 137 :sign place {id} line={lnum} name={name} buffer={nr} | |
| 138 Same, but use buffer {nr}. | |
| 139 | |
| 140 :sign place {id} name={name} file={fname} | |
| 141 Change the placed sign {id} in file {fname} to use the defined | |
| 142 sign {name}. See remark above about {fname} |:sign-fname|. | |
| 143 This can be used to change the displayed sign without moving | |
| 144 it (e.g., when the debugger has stopped at a breakpoint). | |
| 145 | |
| 146 :sign place {id} name={name} buffer={nr} | |
| 147 Same, but use buffer {nr}. | |
| 148 | |
| 149 | |
| 150 REMOVING SIGNS *:sign-unplace* *E159* | |
| 151 | |
| 152 :sign unplace {id} file={fname} | |
| 153 Remove the previously placed sign {id} from file {fname}. | |
| 154 See remark above about {fname} |:sign-fname|. | |
| 155 | |
| 3672 | 156 :sign unplace * file={fname} |
| 157 Remove all placed signs in file {fname}. | |
| 158 | |
| 7 | 159 :sign unplace {id} buffer={nr} |
| 3672 | 160 Remove the previously placed sign {id} from buffer {nr}. |
| 161 | |
| 162 :sign unplace * buffer={nr} | |
| 163 Remove all placed signs in buffer {nr}. | |
| 7 | 164 |
| 165 :sign unplace {id} | |
| 166 Remove the previously placed sign {id} from all files it | |
| 167 appears in. | |
| 168 | |
| 169 :sign unplace * | |
| 170 Remove all placed signs. | |
| 171 | |
| 172 :sign unplace | |
| 173 Remove the placed sign at the cursor position. | |
| 174 | |
| 175 | |
| 176 LISTING PLACED SIGNS | |
| 177 | |
| 178 :sign place file={fname} | |
| 179 List signs placed in file {fname}. | |
| 180 See remark above about {fname} |:sign-fname|. | |
| 181 | |
| 182 :sign place buffer={nr} | |
| 183 List signs placed in buffer {nr}. | |
| 184 | |
| 185 :sign place List placed signs in all files. | |
| 186 | |
| 187 | |
| 188 JUMPING TO A SIGN *:sign-jump* *E157* | |
| 189 | |
| 190 :sign jump {id} file={fname} | |
| 191 Open the file {fname} or jump to the window that contains | |
| 192 {fname} and position the cursor at sign {id}. | |
| 193 See remark above about {fname} |:sign-fname|. | |
| 194 If the file isn't displayed in window and the current file can | |
| 195 not be |abandon|ed this fails. | |
| 196 | |
| 197 :sign jump {id} buffer={nr} | |
| 198 Same, but use buffer {nr}. | |
| 199 | |
| 200 vim:tw=78:ts=8:ft=help:norl: |