diff options
Diffstat (limited to 'runtime/doc/sign.txt')
| -rw-r--r-- | runtime/doc/sign.txt | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt new file mode 100644 index 0000000..4886f74 --- /dev/null +++ b/runtime/doc/sign.txt @@ -0,0 +1,346 @@ +*sign.txt* For Vim version 8.1. Last change: 2019 Jan 17 + + + VIM REFERENCE MANUAL by Gordon Prieur + and Bram Moolenaar + + +Sign Support Features *sign-support* + +1. Introduction |sign-intro| +2. Commands |sign-commands| + +{Vi does not have any of these features} +{only available when compiled with the |+signs| feature} + +============================================================================== +1. Introduction *sign-intro* *signs* + +When a debugger or other IDE tool is driving an editor it needs to be able +to give specific highlights which quickly tell the user useful information +about the file. One example of this would be a debugger which had an icon +in the left-hand column denoting a breakpoint. Another example might be an +arrow representing the Program Counter (PC). The sign features allow both +placement of a sign, or icon, in the left-hand side of the window and +definition of a highlight which will be applied to that line. Displaying the +sign as an image is most likely only feasible in gvim (although Sun +Microsystem's dtterm does support this it's the only terminal emulator I know +of which does). A text sign and the highlight should be feasible in any color +terminal emulator. + +Signs and highlights are not useful just for debuggers. Sun's Visual +WorkShop uses signs and highlights to mark build errors and SourceBrowser +hits. Additionally, the debugger supports 8 to 10 different signs and +highlight colors, see |NetBeans|. + +There are two steps in using signs: + +1. Define the sign. This specifies the image, text and highlighting. For + example, you can define a "break" sign with an image of a stop roadsign and + text "!!". + +2. Place the sign. This specifies the file and line number where the sign is + displayed. A defined sign can be placed several times in different lines + and files. + + *sign-column* +When signs are defined for a file, Vim will automatically add a column of two +characters to display them in. When the last sign is unplaced the column +disappears again. This behavior can be changed with the 'signcolumn' option. + +The color of the column is set with the SignColumn group |hl-SignColumn|. +Example to set the color: > + + :highlight SignColumn guibg=darkgrey +< + *sign-identifier* +Each placed sign is identified by a number called the sign identifier. This +identifier is used to jump to the sign or to remove the sign. The identifier +is assigned when placing the sign using the |:sign-place| command or the +|sign_place()| function. Each sign identifier should be a unique number. If +multiple placed signs use the same identifier, then jumping to or removing a +sign becomes unpredictable. To avoid overlapping identifiers, sign groups can +be used. The |sign_place()| function can be called with a zero sign identifier +to allocate the next available identifier. + + *sign-group* +Each placed sign can be assigned to either the global group or a named group. +When placing a sign, if a group name is not supplied, or an empty string is +used, then the sign is placed in the global group. Otherwise the sign is +placed in the named group. The sign identifier is unique within a group. The +sign group allows Vim plugins to use unique signs without interfering with +other plugins using signs. + + *sign-priority* +Each placed sign is assigned a priority value. When multiple signs are placed +on the same line, the attributes of the sign with the highest priority is used +independent of the sign group. The default priority for a sign is 10. The +priority is assigned at the time of placing a sign. + +When the line on which the sign is placed is deleted, the sign is moved to the +next line (or the last line of the buffer, if there is no next line). When +the delete is undone the sign does not move back. + +============================================================================== +2. Commands *sign-commands* *:sig* *:sign* + +Here is an example that places a sign "piet", displayed with the text ">>", in +line 23 of the current file: > + :sign define piet text=>> texthl=Search + :exe ":sign place 2 line=23 name=piet file=" . expand("%:p") + +And here is the command to delete it again: > + :sign unplace 2 + +Note that the ":sign" command cannot be followed by another command or a +comment. If you do need that, use the |:execute| command. + + +DEFINING A SIGN. *:sign-define* *E255* *E160* *E612* + +See |sign_define()| for the equivalent Vim script function. + +:sign define {name} {argument}... + Define a new sign or set attributes for an existing sign. + The {name} can either be a number (all digits) or a name + starting with a non-digit. Leading zeros are ignored, thus + "0012", "012" and "12" are considered the same name. + About 120 different signs can be defined. + + Accepted arguments: + + icon={bitmap} + Define the file name where the bitmap can be found. Should be + a full path. The bitmap should fit in the place of two + characters. This is not checked. If the bitmap is too big it + will cause redraw problems. Only GTK 2 can scale the bitmap + to fit the space available. + toolkit supports ~ + GTK 1 pixmap (.xpm) + GTK 2 many + Motif pixmap (.xpm) + Win32 .bmp, .ico, .cur + pixmap (.xpm) |+xpm_w32| + + linehl={group} + Highlighting group used for the whole line the sign is placed + in. Most useful is defining a background color. + + text={text} *E239* + Define the text that is displayed when there is no icon or the + GUI is not being used. Only printable characters are allowed + and they must occupy one or two display cells. + + texthl={group} + Highlighting group used for the text item. + + +DELETING A SIGN *:sign-undefine* *E155* + +See |sign_undefine()| for the equivalent Vim script function. + +:sign undefine {name} + Deletes a previously defined sign. If signs with this {name} + are still placed this will cause trouble. + + + +LISTING SIGNS *:sign-list* *E156* + +See |sign_getdefined()| for the equivalent Vim script function. + +:sign list Lists all defined signs and their attributes. + +:sign list {name} + Lists one defined sign and its attributes. + + +PLACING SIGNS *:sign-place* *E158* + +See |sign_place()| for the equivalent Vim script function. + +:sign place {id} line={lnum} name={name} file={fname} + Place sign defined as {name} at line {lnum} in file {fname}. + *:sign-fname* + The file {fname} must already be loaded in a buffer. The + exact file name must be used, wildcards, $ENV and ~ are not + expanded, white space must not be escaped. Trailing white + space is ignored. + + The sign is remembered under {id}, this can be used for + further manipulation. {id} must be a number. + It's up to the user to make sure the {id} is used only once in + each file (if it's used several times unplacing will also have + to be done several times and making changes may not work as + expected). + + The following optional sign attributes can be specified before + "file=": + group={group} Place sign in sign group {group} + priority={prio} Assign priority {prio} to sign + + By default, the sign is placed in the global sign group. + + By default, the sign is assigned a default priority of 10. To + assign a different priority value, use "priority={prio}" to + specify a value. The priority is used to determine the + highlight group used when multiple signs are placed on the + same line. + + Examples: > + :sign place 5 line=3 name=sign1 file=a.py + :sign place 6 group=g2 line=2 name=sign2 file=x.py + :sign place 9 group=g2 priority=50 line=5 + \ name=sign1 file=a.py +< +:sign place {id} line={lnum} name={name} [buffer={nr}] + Same, but use buffer {nr}. If the buffer argument is not + given, place the sign in the current buffer. + + *E885* +:sign place {id} name={name} file={fname} + Change the placed sign {id} in file {fname} to use the defined + sign {name}. See remark above about {fname} |:sign-fname|. + This can be used to change the displayed sign without moving + it (e.g., when the debugger has stopped at a breakpoint). + + The optional "group={group}" attribute can be used before + "file=" to select a sign in a particular group. + +:sign place {id} name={name} [buffer={nr}] + Same, but use buffer {nr}. If the buffer argument is not + given, use the current buffer. + + +REMOVING SIGNS *:sign-unplace* *E159* + +See |sign_unplace()| for the equivalent Vim script function. + +:sign unplace {id} file={fname} + Remove the previously placed sign {id} from file {fname}. + See remark above about {fname} |:sign-fname|. + +:sign unplace {id} group={group} file={fname} + Same but remove the sign {id} in sign group {group}. + +:sign unplace {id} group=* file={fname} + Same but remove the sign {id} from all the sign groups. + +:sign unplace * file={fname} + Remove all placed signs in file {fname}. + +:sign unplace * group={group} file={fname} + Remove all placed signs in group {group} from file {fname}. + +:sign unplace * group=* file={fname} + Remove all placed signs in all the groups from file {fname}. + +:sign unplace {id} buffer={nr} + Remove the previously placed sign {id} from buffer {nr}. + +:sign unplace {id} group={group} buffer={nr} + Remove the previously placed sign {id} in group {group} from + buffer {nr}. + +:sign unplace {id} group=* buffer={nr} + Remove the previously placed sign {id} in all the groups from + buffer {nr}. + +:sign unplace * buffer={nr} + Remove all placed signs in buffer {nr}. + +:sign unplace * group={group} buffer={nr} + Remove all placed signs in group {group} from buffer {nr}. + +:sign unplace * group=* buffer={nr} + Remove all placed signs in all the groups from buffer {nr}. + +:sign unplace {id} + Remove the previously placed sign {id} from all files it + appears in. + +:sign unplace {id} group={group} + Remove the previously placed sign {id} in group {group} from + all files it appears in. + +:sign unplace {id} group=* + Remove the previously placed sign {id} in all the groups from + all the files it appears in. + +:sign unplace * + Remove all placed signs in the global group from all the files. + +:sign unplace * group={group} + Remove all placed signs in group {group} from all the files. + +:sign unplace * group=* + Remove all placed signs in all the groups from all the files. + +:sign unplace + Remove a placed sign at the cursor position. If multiple signs + are placed in the line, then only one is removed. + +:sign unplace group={group} + Remove a placed sign in group {group} at the cursor + position. + +:sign unplace group=* + Remove a placed sign in any group at the cursor position. + + +LISTING PLACED SIGNS *:sign-place-list* + +See |sign_getplaced()| for the equivalent Vim script function. + +:sign place file={fname} + List signs placed in file {fname}. + See remark above about {fname} |:sign-fname|. + +:sign place group={group} file={fname} + List signs in group {group} placed in file {fname}. + +:sign place group=* file={fname} + List signs in all the groups placed in file {fname}. + +:sign place buffer={nr} + List signs placed in buffer {nr}. + +:sign place group={group} buffer={nr} + List signs in group {group} placed in buffer {nr}. + +:sign place group=* buffer={nr} + List signs in all the groups placed in buffer {nr}. + +:sign place List placed signs in the global group in all files. + +:sign place group={group} + List placed signs with sign group {group} in all files. + +:sign place group=* + List placed signs in all sign groups in all files. + + +JUMPING TO A SIGN *:sign-jump* *E157* + +See |sign_jump()| for the equivalent Vim script function. + +:sign jump {id} file={fname} + Open the file {fname} or jump to the window that contains + {fname} and position the cursor at sign {id}. + See remark above about {fname} |:sign-fname|. + If the file isn't displayed in window and the current file can + not be |abandon|ed this fails. + +:sign jump {id} group={group} file={fname} + Same but jump to the sign in group {group} + +:sign jump {id} [buffer={nr}] *E934* + Same, but use buffer {nr}. This fails if buffer {nr} does not + have a name. If the buffer argument is not given, use the + current buffer. + +:sign jump {id} group={group} [buffer={nr}] + Same but jump to the sign in group {group} + + + vim:tw=78:ts=8:noet:ft=help:norl: |