kakoune/doc/pages/faces.asciidoc

= Faces

== Declaration

A 'face' determines how 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][@base]
-----------------------------------------

'fg_color', 'bg_color'::
    a color whose value can be expressed in the following formats:
        *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*:::
        *bright-black*, *bright-red*, *bright-green*, *bright-yellow*:::
        *bright-blue*, *bright-magenta*, *bright-cyan*, *bright-white*:::
            a named color
        *default*:::
            keep the existing color
        *rgb:RRGGBB*:::
            hexadecimal value
        *rgba:RRGGBBAA*:::
            hexadecimal value
    if unspecified, *default* is used.
    Alpha values are used to blend the face onto either its base or the existing
    color. For technical reasons alpha values must be >16 if specified.

'attributes'::
    string whose individual letters set an attribute:
        *u*:::
            underline
        *r*:::
            reverse
        *b*:::
            bold
        *B*:::
            blink
        *d*:::
            dim
        *i*:::
            italic
        *s*:::
            strikethrough
        *F*:::
            final, override the previous face instead of merging with it,
            and this face 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

'base'::
    The base face on which this face applies, which can be any face name,
    as long as no cycle is introduced. A face can reference itself, in
    which case it will apply on top of the parent scope version.

== 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 an end of line character

*SecondaryCursorEol*::
    cursor of the secondary selection when it lies on an 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 highlighter 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

*WrapMarker*::
    face used by the `wrap -marker` highlighter

== Markup strings

In certain contexts, Kakoune can take a markup string, which is a string
containing formatting information. In these strings, the {facename}
syntax will enable the face facename until another face gets activated,
or the end of the string is reached.

For example, the following command displays the text "default" in the
Default face, and "error" in the Error face:

----
echo -markup 'default {Error}error{Default} default'
----

Inside a markup string, a literal `{` character is written `\{`, and a
literal backslash (`\`) that precedes a '{' character is escaped as well
(`\\`).

The `{\}` string disables markup processing for the rest of the line,
and can be used to avoid having to escape text that might be mistaken
for markup instructions.

For example this will prevent any '{' in the current buffer name from
being incorrectly interpreted as markup instruction.

----
echo -markup "{Information}name:{\} %val{bufname}"
----