1*sign.txt* For Vim version 7.3. Last change: 2010 May 07 2 3 4 VIM REFERENCE MANUAL by Gordon Prieur 5 and Bram Moolenaar 6 7 8Sign Support Features *sign-support* 9 101. Introduction |sign-intro| 112. Commands |sign-commands| 12 13{Vi does not have any of these features} 14{only available when compiled with the |+signs| feature} 15 16============================================================================== 171. Introduction *sign-intro* *signs* 18 19When a debugger or other IDE tool is driving an editor it needs to be able 20to give specific highlights which quickly tell the user useful information 21about the file. One example of this would be a debugger which had an icon 22in the left-hand column denoting a breakpoint. Another example might be an 23arrow representing the Program Counter (PC). The sign features allow both 24placement of a sign, or icon, in the left-hand side of the window and 25definition of a highlight which will be applied to that line. Displaying the 26sign as an image is most likely only feasible in gvim (although Sun 27Microsystem's dtterm does support this it's the only terminal emulator I know 28of which does). A text sign and the highlight should be feasible in any color 29terminal emulator. 30 31Signs and highlights are not useful just for debuggers. Sun's Visual 32WorkShop uses signs and highlights to mark build errors and SourceBrowser 33hits. Additionally, the debugger supports 8 to 10 different signs and 34highlight colors. |workshop| Same for Netbeans |netbeans|. 35 36There are two steps in using signs: 37 381. 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 422. 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 46When signs are defined for a file, Vim will automatically add a column of two 47characters to display them in. When the last sign is unplaced the column 48disappears 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============================================================================== 542. Commands *sign-commands* *:sig* *:sign* 55 56Here is an example that places a sign "piet", displayed with the text ">>", in 57line 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 61And here is the command to delete it again: > 62 :sign unplace 2 63 64Note that the ":sign" command cannot be followed by another command or a 65comment. If you do need that, use the |:execute| command. 66 67 68DEFINING 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 102DELETING 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 109LISTING 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 117PLACING 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 147REMOVING 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 167LISTING 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 179JUMPING 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: 192