faces.asciidoc (6089B)
1 = Faces 2 3 == Declaration 4 5 A *face* determines how text is displayed. It has a foreground color, 6 a background color, and some attributes. The value of a face has the 7 following format: 8 9 ----------------------------------------------------------- 10 [fg_color][,bg_color[,underline_color]][+attributes][@base] 11 ----------------------------------------------------------- 12 13 fg_color, bg_color, underline_color:: 14 A color whose value can be: 15 A named color::: 16 *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, 17 *white* *bright-black*, *bright-red*, *bright-green*, 18 *bright-yellow* *bright-blue*, *bright-magenta*, *bright-cyan*, 19 *bright-white* 20 The color of the base face (see below)::: 21 *default* 22 A hexadecimal value::: 23 *rgb:RRGGBB*, *rgba:RRGGBBAA* 24 If left unspecified, the value of *default* is used. 25 Alpha values are used to blend the face onto either its base or else onto 26 whatever color happens to be used at the moment. For technical reasons, 27 alpha values must be >16. 28 29 attributes:: 30 A string whose individual letters each set an attribute: 31 *u*::: 32 underline 33 *c*::: 34 curly underline 35 Note: This takes precedence over underline if both are specified. 36 *U*::: 37 double underline 38 Note: This takes precedence over underline and curly underline if 39 also specified. 40 *r*::: 41 reverse 42 *b*::: 43 bold 44 *B*::: 45 blink 46 *d*::: 47 dim 48 *i*::: 49 italic 50 *s*::: 51 strikethrough 52 *F*::: 53 final:::: 54 Override the previous face instead of merging with it. Can 55 only be replaced if another face with the final attribute 56 is applied. 57 *f*::: 58 final foreground:::: 59 Same as final, but only applies to a face's foreground color. 60 *g*::: 61 final background:::: 62 Same as final, but only applies to a face's background color. 63 *a*::: 64 final attributes:::: 65 Same as final, but only applies to a face's attributes 66 Note: this will not clear to the f/g/a attributes of the base 67 face, `+a` cannot be used to remove `+f` and/or `+g`. 68 69 base:: 70 The face onto which other faces apply. Its value can be any face name, 71 as long as no cycle is introduced. A face can reference itself, in which 72 case it'll apply on top of the version of the parent scope. 73 74 == Built-in faces 75 76 The following faces are used by color schemes to highlight certain areas of 77 the user interface: 78 79 *Default*:: 80 default colors::: 81 The default foreground and background colors. If the value of *default* 82 is used here, then the colors used will be your terminal's defaults. 83 84 *PrimarySelection*:: 85 Main selection face for every selected character except the cursor. 86 87 *SecondarySelection*:: 88 Secondary selection face for every selected character except the cursor. 89 90 *PrimaryCursor*:: 91 Cursor of the primary selection. 92 93 *SecondaryCursor*:: 94 Cursor of the secondary selection. 95 96 *PrimaryCursorEol*:: 97 Cursor of the primary selection when it lies on an EOL (end of line) 98 character. 99 100 *SecondaryCursorEol*:: 101 Cursor of the secondary selection when it lies on an EOL (end of line) 102 character. 103 104 *MenuForeground*:: 105 Face for items selected in menus. 106 107 *MenuBackground*:: 108 Face for items not selected in menus. 109 110 *MenuInfo*:: 111 Face for the additional information displayed when selecting items in menus. 112 113 *Information*:: 114 Face for windows and messages displaying other information. 115 116 *InlineInformation*:: 117 Face for windows and messages displaying inline information. 118 119 *Error*:: 120 Face for errors reported by Kakoune in the status line. 121 122 *DiagnosticError*:: 123 Face for errors reported by external tools in the buffer. 124 125 *DiagnosticWarning*:: 126 Face for warnings reported by external tools in the buffer. 127 128 *StatusLine*:: 129 Face for the status line. 130 131 *StatusLineMode*:: 132 Face for the current mode, except normal mode. 133 134 *StatusLineInfo*:: 135 Face for special information. 136 137 *StatusLineValue*:: 138 Face for special values (numeric prefixes, registers, etc.). 139 140 *StatusCursor*:: 141 Face for the status line cursor. 142 143 *Prompt*:: 144 Face for the prompt displayed on the status line. 145 146 *BufferPadding*:: 147 Face applied on the *~* characters that follow the last line of a buffer. 148 149 === Built-in highlighter faces 150 151 The following faces are used by built-in highlighters if enabled. 152 (See <<highlighters#,`:doc highlighters`>>). 153 154 *LineNumbers*:: 155 Face used by the *number-lines* highlighter. 156 157 *LineNumberCursor*:: 158 Face used to highlight the line number of the main selection. 159 160 *LineNumbersWrapped*:: 161 Face used to highlight the line number of wrapped lines. 162 163 *MatchingChar*:: 164 Face used by the *show-matching* highlighter. 165 166 *Whitespace*:: 167 Face used by the *show-whitespaces* highlighter. 168 169 *WrapMarker*:: 170 Face used by the *wrap-marker* highlighter. 171 172 == Markup strings 173 174 In certain contexts, Kakoune can understand markup strings, which are strings 175 containing formatting information. In these strings, the {facename} syntax 176 will enable the face facename until another face gets activated, or the end 177 of the string is reached. 178 179 For example, the following command displays the text "default" in the 180 *Default* face, and "error" in the *Error* face: 181 182 ---- 183 echo -markup 'default {Error}error{Default} default' 184 ---- 185 186 Inside a markup string, a literal `{` character is written as `\{`, and a 187 literal backslash (`\`) character is written as `\\`. 188 189 The `{\}` string disables markup processing for the rest of the line. It 190 can be used to avoid having to escape text that might be mistaken for markup 191 instructions. 192 193 For example, this will prevent any `{` in the current buffer name from being 194 incorrectly interpreted as markup. 195 196 ---- 197 echo -markup "{Information}name:{\} %val{bufname}" 198 ----