kakoune/doc/pages/faces.asciidoc

= Faces

== Declaration

A 'face' refers how the specified text is displayed, it has a foreground
color, a background color, and some attributes. The value of a face has the
following format:

--------------------------------
fg_color[,bg_color][+attributes]
--------------------------------

'fg_color', 'bg_color'::
    a color whose value can be expressed in the following formats:
        *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*:::
            a named color
        *default*:::
            keep the existing color
        *rgb:RRGGBB*:::
            hexadecimal value

'attributes'::
    string whose individual letters set an attribute:
        *u*:::
            underline
        *r*:::
            reverse
        *b*:::
            bold
        *B*:::
            blink
        *d*:::
            dim
        *i*:::
            italic
        *F*:::
            final, override the previous face instead of merging with it
            an will only be replaced if another face with the final
            attribute is applied
        *f*:::
            final foreground, as final but only applies to face's
            foreground color
        *g*:::
            final background, as final but only applies to face's
            background color
        *a*:::
            final attributes, as final but only applies to face's
            attributes

== Builtin faces

The following default faces are used by color schemes to highlight certain
areas of the user interface:

*Default*::
    default colors

*PrimarySelection*::
    main selection face for every selected character except the cursor

*SecondarySelection*::
    secondary selection face for every selected character except the cursor

*PrimaryCursor*::
    cursor of the primary selection

*SecondaryCursor*::
    cursor of the secondary selection

*PrimaryCursorEol*::
    cursor of the primary selection when it lies on and end of line character

*SecondaryCursorEol*::
    cursor of the secondary selection when it lies on and end of line character

*MenuForeground*::
    face for the selected element in menus

*MenuBackground*::
    face for the not selected elements in menus

*MenuInfo*::
    face for additional information for elements in menus

*Information*::
    face for the informations windows and information messages

*Error*::
    face of error messages

*StatusLine*::
    face used for the status line

*StatusLineMode*::
    face used for the current mode except the normal mode

*StatusLineInfo*::
    face used for special information

*StatusLineValue*::
    face used for special values (numeric prefixes, registers, etc.)

*StatusCursor*::
    face used for the status line cursor

*Prompt*::
    face used prompt displayed on the status line

*BufferPadding*::
    face applied on the `~` characters that follow the last line of a buffer

=== Builtin highlighters faces

The following faces are used by builtin highlighters if enabled.
(See <<highlighters#,`:doc highlighters`>>).

*LineNumbers*::
    face used by the `number-lines` highlighter

*LineNumberCursor*::
    face used to highlight the line number of the main selection

*LineNumbersWrapped*::
    face used to highlight the line number of wrapped lines

*MatchingChar*::
    face used by the `show-matching` highlighter

*Whitespace*::
    face used by the `show-whitespaces` highlighter