3fc8e29d10
Add support for a third color in face definition that controls the underline and a 'c' attribute for curly underline (that takes precedence over 'u' if both are specified) Allow empty colors to mean default, so that `,,red+u` means the same as `default,default,red+u` Fixes #4138
180 lines
5.2 KiB
Plaintext
180 lines
5.2 KiB
Plaintext
= 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[,underline_color]][+attributes][@base]
|
|
-----------------------------------------------------------
|
|
|
|
'fg_color', 'bg_color', 'underline_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 or empty, *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
|
|
*c*:::
|
|
curly underline, takes precedence over underline if both are
|
|
specified
|
|
*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}"
|
|
----
|