|
236
|
1 *sign.txt* For Vim version 7.0aa. Last change: 2005 Apr 04
|
|
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
|
|
|
56 Here is an example that places a sign piet, displayed with the text ">>", in
|
|
|
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:
|
