Mercurial > vim
annotate runtime/doc/sign.txt @ 2577:073ff46fe397
Fold Vim 7.2 default branch back to trunk to avoid two heads. (Tony
Mechelynck)
author | Bram Moolenaar <bram@vim.org> |
---|---|
date | Fri, 20 Aug 2010 11:11:57 +0200 |
parents | ee53a39d5896 733f0dc510c3 |
children | 7d8af31066c8 |
rev | line source |
---|---|
2572
ee53a39d5896
Last changes for the 7.3 release!
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
1 *sign.txt* For Vim version 7.3. Last change: 2010 May 07 |
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 | |
73 starting with a non-digit. | |
74 About 120 different signs can be defined. | |
75 | |
76 Accepted arguments: | |
77 | |
78 icon={pixmap} | |
79 Define the file name where the bitmap can be found. Should be | |
80 a full path. The bitmap should fit in the place of two | |
81 characters. This is not checked. If the bitmap is too big it | |
82 will cause redraw problems. Only GTK 2 can scale the bitmap | |
83 to fit the space available. | |
84 toolkit supports ~ | |
85 GTK 1 pixmap (.xpm) | |
86 GTK 2 many | |
87 Motif pixmap (.xpm) | |
88 | |
89 linehl={group} | |
90 Highlighting group used for the whole line the sign is placed | |
91 in. Most useful is defining a background color. | |
92 | |
93 text={text} *E239* | |
94 Define the text that is displayed when there is no icon or the | |
95 GUI is not being used. Only printable characters are allowed | |
96 and they must occupy one or two display cells. | |
97 | |
98 texthl={group} | |
99 Highlighting group used for the text item. | |
100 | |
101 | |
102 DELETING A SIGN *:sign-undefine* *E155* | |
103 | |
104 :sign undefine {name} | |
105 Deletes a previously defined sign. If signs with this {name} | |
106 are still placed this will cause trouble. | |
107 | |
108 | |
109 LISTING SIGNS *:sign-list* *E156* | |
110 | |
111 :sign list Lists all defined signs and their attributes. | |
112 | |
113 :sign list {name} | |
114 Lists one defined sign and its attributes. | |
115 | |
116 | |
117 PLACING SIGNS *:sign-place* *E158* | |
118 | |
119 :sign place {id} line={lnum} name={name} file={fname} | |
120 Place sign defined as {name} at line {lnum} in file {fname}. | |
121 *:sign-fname* | |
122 The file {fname} must already be loaded in a buffer. The | |
123 exact file name must be used, wildcards, $ENV and ~ are not | |
124 expanded, white space must not be escaped. Trailing white | |
125 space is ignored. | |
126 | |
127 The sign is remembered under {id}, this can be used for | |
128 further manipulation. {id} must be a number. | |
129 It's up to the user to make sure the {id} is used only once in | |
130 each file (if it's used several times unplacing will also have | |
131 to be done several times and making changes may not work as | |
132 expected). | |
133 | |
134 :sign place {id} line={lnum} name={name} buffer={nr} | |
135 Same, but use buffer {nr}. | |
136 | |
137 :sign place {id} name={name} file={fname} | |
138 Change the placed sign {id} in file {fname} to use the defined | |
139 sign {name}. See remark above about {fname} |:sign-fname|. | |
140 This can be used to change the displayed sign without moving | |
141 it (e.g., when the debugger has stopped at a breakpoint). | |
142 | |
143 :sign place {id} name={name} buffer={nr} | |
144 Same, but use buffer {nr}. | |
145 | |
146 | |
147 REMOVING SIGNS *:sign-unplace* *E159* | |
148 | |
149 :sign unplace {id} file={fname} | |
150 Remove the previously placed sign {id} from file {fname}. | |
151 See remark above about {fname} |:sign-fname|. | |
152 | |
153 :sign unplace {id} buffer={nr} | |
154 Same, but use buffer {nr}. | |
155 | |
156 :sign unplace {id} | |
157 Remove the previously placed sign {id} from all files it | |
158 appears in. | |
159 | |
160 :sign unplace * | |
161 Remove all placed signs. | |
162 | |
163 :sign unplace | |
164 Remove the placed sign at the cursor position. | |
165 | |
166 | |
167 LISTING PLACED SIGNS | |
168 | |
169 :sign place file={fname} | |
170 List signs placed in file {fname}. | |
171 See remark above about {fname} |:sign-fname|. | |
172 | |
173 :sign place buffer={nr} | |
174 List signs placed in buffer {nr}. | |
175 | |
176 :sign place List placed signs in all files. | |
177 | |
178 | |
179 JUMPING TO A SIGN *:sign-jump* *E157* | |
180 | |
181 :sign jump {id} file={fname} | |
182 Open the file {fname} or jump to the window that contains | |
183 {fname} and position the cursor at sign {id}. | |
184 See remark above about {fname} |:sign-fname|. | |
185 If the file isn't displayed in window and the current file can | |
186 not be |abandon|ed this fails. | |
187 | |
188 :sign jump {id} buffer={nr} | |
189 Same, but use buffer {nr}. | |
190 | |
191 vim:tw=78:ts=8:ft=help:norl: |