kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

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 ----