xenia/home
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'Pound-Hash/docs_faces'

Browse Source
This commit is contained in:
Maxime Coste 2022-07-28 21:19:52 +10:00
commit f137ee6595
1 changed files with 83 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
doc/pages/faces.asciidoc
View File

@ -2,37 +2,37 @@
== Declaration == Declaration
A 'face' determines how text is displayed, it has a foreground A *face* determines how text is displayed. It has a foreground color,
color, a background color, and some attributes. The value of a face has the a background color, and some attributes. The value of a face has the
following format: following format:
----------------------------------------------------------- -----------------------------------------------------------
[fg_color][,bg_color[,underline_color]][+attributes][@base] [fg_color][,bg_color[,underline_color]][+attributes][@base]
----------------------------------------------------------- -----------------------------------------------------------
'fg_color', 'bg_color', 'underline_color':: fg_color, bg_color, underline_color::
a color whose value can be expressed in the following formats: A color whose value can be:
*black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*, *white*::: A named color:::
*bright-black*, *bright-red*, *bright-green*, *bright-yellow*::: *black*, *red*, *green*, *yellow*, *blue*, *magenta*, *cyan*,
*bright-blue*, *bright-magenta*, *bright-cyan*, *bright-white*::: *white* *bright-black*, *bright-red*, *bright-green*,
a named color *bright-yellow* *bright-blue*, *bright-magenta*, *bright-cyan*,
*default*::: *bright-white*
keep the existing color The color of the base face (see below):::
*rgb:RRGGBB*::: *default*
hexadecimal value A hexadecimal value:::
*rgba:RRGGBBAA*::: *rgb:RRGGBB*, *rgba:RRGGBBAA*
hexadecimal value If left unspecified, the value of *default* is used.
if unspecified or empty, *default* is used. Alpha values are used to blend the face onto either its base or else onto
Alpha values are used to blend the face onto either its base or the existing whatever color happens to be used at the moment. For technical reasons,
color. For technical reasons alpha values must be >16 if specified. alpha values must be >16.
'attributes':: attributes::
string whose individual letters set an attribute: A string whose individual letters each set an attribute:
*u*::: *u*:::
underline underline
*c*::: *c*:::
curly underline, takes precedence over underline if both are curly underline
specified Note: This takes precedence over underline if both are specified.
*r*::: *r*:::
reverse reverse
*b*::: *b*:::
@ -46,139 +46,143 @@ following format:
*s*::: *s*:::
strikethrough strikethrough
*F*::: *F*:::
final, override the previous face instead of merging with it, final::::
and this face will only be replaced if another face with Override the previous face instead of merging with it. Can
the final attribute is applied only be replaced if another face with the final attribute
is applied.
*f*::: *f*:::
final foreground, as final but only applies to face's final foreground::::
foreground color Same as final, but only applies to a face's foreground color.
*g*::: *g*:::
final background, as final but only applies to face's final background::::
background color Same as final, but only applies to a face's background color.
*a*::: *a*:::
final attributes, as final but only applies to face's final attributes::::
attributes Same as final, but only applies to a face's attributes.
'base':: base::
The base face on which this face applies, which can be any face name, The face onto which other faces apply. Its value can be any face name,
as long as no cycle is introduced. A face can reference itself, in as long as no cycle is introduced. A face can reference itself, in which
which case it will apply on top of the parent scope version. case it'll apply on top of the version of the parent scope.
== Builtin faces == Built-in faces
The following default faces are used by color schemes to highlight certain The following faces are used by color schemes to highlight certain areas of
areas of the user interface: the user interface:
*Default*:: *Default*::
default colors default colors:::
The default foreground and background colors. If the value of *default*
is used here, then the colors used will be your terminal's defaults.
*PrimarySelection*:: *PrimarySelection*::
main selection face for every selected character except the cursor Main selection face for every selected character except the cursor.
*SecondarySelection*:: *SecondarySelection*::
secondary selection face for every selected character except the cursor Secondary selection face for every selected character except the cursor.
*PrimaryCursor*:: *PrimaryCursor*::
cursor of the primary selection Cursor of the primary selection.
*SecondaryCursor*:: *SecondaryCursor*::
cursor of the secondary selection Cursor of the secondary selection.
*PrimaryCursorEol*:: *PrimaryCursorEol*::
cursor of the primary selection when it lies on an end of line character Cursor of the primary selection when it lies on an EOL (end of line)
character.
*SecondaryCursorEol*:: *SecondaryCursorEol*::
cursor of the secondary selection when it lies on an end of line character Cursor of the secondary selection when it lies on an EOL (end of line)
character.
*MenuForeground*:: *MenuForeground*::
face for the selected element in menus Face for items selected in menus.
*MenuBackground*:: *MenuBackground*::
face for the not selected elements in menus Face for items not selected in menus.
*MenuInfo*:: *MenuInfo*::
face for additional information for elements in menus Face for the additional information displayed when selecting items in menus.
*Information*:: *Information*::
face for the informations windows and information messages Face for windows and messages displaying other information.
*Error*:: *Error*::
face of errors reported by Kakoune in the status line Face for errors reported by Kakoune in the status line.
*DiagnosticError*:: *DiagnosticError*::
face of errors reported by external tools in the buffer Face for errors reported by external tools in the buffer.
*DiagnosticWarning*:: *DiagnosticWarning*::
face of warnings reported by external tools in the buffer Face for warnings reported by external tools in the buffer.
*StatusLine*:: *StatusLine*::
face used for the status line Face for the status line.
*StatusLineMode*:: *StatusLineMode*::
face used for the current mode except the normal mode Face for the current mode, except normal mode.
*StatusLineInfo*:: *StatusLineInfo*::
face used for special information Face for special information.
*StatusLineValue*:: *StatusLineValue*::
face used for special values (numeric prefixes, registers, etc.) Face for special values (numeric prefixes, registers, etc.).
*StatusCursor*:: *StatusCursor*::
face used for the status line cursor Face for the status line cursor.
*Prompt*:: *Prompt*::
face used prompt displayed on the status line Face for the prompt displayed on the status line.
*BufferPadding*:: *BufferPadding*::
face applied on the `~` characters that follow the last line of a buffer Face applied on the *~* characters that follow the last line of a buffer.
=== Builtin highlighter faces === Built-in highlighter faces
The following faces are used by builtin highlighters if enabled. The following faces are used by built-in highlighters if enabled.
(See <<highlighters#,`:doc highlighters`>>). (See <<highlighters#,`:doc highlighters`>>).
*LineNumbers*:: *LineNumbers*::
face used by the `number-lines` highlighter Face used by the *number-lines* highlighter.
*LineNumberCursor*:: *LineNumberCursor*::
face used to highlight the line number of the main selection Face used to highlight the line number of the main selection.
*LineNumbersWrapped*:: *LineNumbersWrapped*::
face used to highlight the line number of wrapped lines Face used to highlight the line number of wrapped lines.
*MatchingChar*:: *MatchingChar*::
face used by the `show-matching` highlighter Face used by the *show-matching* highlighter.
*Whitespace*:: *Whitespace*::
face used by the `show-whitespaces` highlighter Face used by the *show-whitespaces* highlighter.
*WrapMarker*:: *WrapMarker*::
face used by the `wrap -marker` highlighter Face used by the *wrap-marker* highlighter.
== Markup strings == Markup strings
In certain contexts, Kakoune can take a markup string, which is a string In certain contexts, Kakoune can understand markup strings, which are strings
containing formatting information. In these strings, the {facename} containing formatting information. In these strings, the {facename} syntax
syntax will enable the face facename until another face gets activated, will enable the face facename until another face gets activated, or the end
or the end of the string is reached. of the string is reached.
For example, the following command displays the text "default" in the For example, the following command displays the text "default" in the
Default face, and "error" in the Error face: *Default* face, and "error" in the *Error* face:
---- ----
echo -markup 'default {Error}error{Default} default' echo -markup 'default {Error}error{Default} default'
---- ----
Inside a markup string, a literal `{` character is written `\{`, and a Inside a markup string, a literal `{` character is written as `\{`, and a
literal backslash (`\`) that precedes a '{' character is escaped as well literal backslash (`\`) character is written as `\\`.
(`\\`).
The `{\}` string disables markup processing for the rest of the line, The `{\}` string disables markup processing for the rest of the line. It
and can be used to avoid having to escape text that might be mistaken can be used to avoid having to escape text that might be mistaken for markup
for markup instructions. instructions.
For example this will prevent any '{' in the current buffer name from For example, this will prevent any `{` in the current buffer name from being
being incorrectly interpreted as markup instruction. incorrectly interpreted as markup.
---- ----
echo -markup "{Information}name:{\} %val{bufname}" echo -markup "{Information}name:{\} %val{bufname}"