aerc-stylesets - Man Page

styleset file specification for aerc(1)

Synopsis

aerc uses a simple configuration syntax to configure the styleset for its ui.

Styleset Configuration

Aerc uses a simple configuration file to describe a styleset. The styleset is described as key, value pairs. In each line, the key represents the style object it signifies and the color/atrribute of that is modified.

For example, in the line below, the foreground color of the style object "msglist_unread" is set to "cornflowerblue"

  msglist_unread.fg=cornflowerblue

The configuration also allows wildcard matching of the style_objects to configure multiple style objects at a time.

Style

The following options are available to be modified for each of the style objects.

fg

The foreground color of the style object is set.

Syntax: `<style_object>.fg=<color>`

bg

The background color of the style object is set.

Syntax: `<style_object>.bg=<color>`

bold

The bold attribute of the style object is set/unset.

Syntax: `<style_object>.bold=<true|false|toggle>`

blink

The blink attribute of the style object is set/unset. The terminal needs to support blinking text

Syntax: `<style_object>.bold=<true|false|toggle>`

underline

The underline attribute of the style object is set/unset. The terminal needs to support underline text

Syntax: `<style_object>.underline=<true|false|toggle>`

reverse

Reverses the color of the style object. Exchanges the foreground and background colors.

Syntax: `<style_object>.reverse=<true|false|toggle>` If the value is false, it doesn't change anything

normal

All the attributes of the style object are unset.

Syntax: `<style_object>.normal=<true>` The value doesn't matter

default

Set the style object to the default style of the context. Usually based on the terminal.

Syntax: `<style_object>.default=<true>` The value doesn't matter

Style Objects

The style objects represent the various ui elements or ui instances for styling.

Style ObjectDescription
defaultThe default style object used for normal ui elements while not using specialized configuration.
errorThe style used to show errors.
warning The style used when showing warnings.
successThe style used for success messages.
titleThe style object used to style titles in ui elements.
headerThe style object used to style headers in ui elements.
statusline_defaultThe default style applied to the statusline.
statusline_errorThe style used for error messages in statusline.
statusline_successThe style used for success messages in statusline.
msglist_defaultThe default style for messages in a message list.
msglist_unreadUnread messages in a message list.
msglist_readRead messages in a message list.
msglist_flaggedThe messages with the flagged flag.
msglist_deletedThe messages marked as deleted.
msglist_markedThe messages with the marked flag.
dirlist_defaultThe default style for directories in the directory list.
completion_defaultThe default style for the completion engine.
completion_gutterThe completion gutter.
completion_pillThe completion pill.
tabThe style for the tab bar.
stackThe style for ui stack element.
spinnerThe style for the loading spinner.
borderThe style used to draw borders. Only the background color is used.
selector_defaultThe default style for the selector ui element.
selector_focusedThe focused item in a selector ui element.
selector_chooserThe item chooser in a selector ui element.

fnmatch style wildcard matching

The styleset configuration can be made simpler by using the fnmatch style wildcard matching for the style object.

The special characters used in the fnmatch wildcards are:

PatternMeaning
*Matches everything
?Matches any single character

For example, the following wildcards can be made using this syntax.

ExampleDescription
*.fg=blueSet the foreground color of all style objects to blue.
*list.bg=hotpinkSet the background color of all style objects that end in list  to hotpink.

Selected modifier

Selected modifier can be applied to any style object. The style provided for the selected modifier are applied on top of the style object it corresponds to.

If you would like to make sure message that are flagged as read in the msglist appear in yellow foreground and black background. You can specify that with this:

msglist_default.selected.fg=yellow

msglist_default.selected.bg=black

If we specify the global style selected modifer using fnmatch as below:

*.selected.reverse=toggle

This toggles the reverse switch for selected version of all the style objects.

Layered styles

Some styles, (currently only the `msglist*` ones) are applied in layers. If a style differs from the base (in this case `msglist_default`) then that style applies, unless overridden by a higher layer. The order that `msglist` styles are applied in is, from first to last:

  msglist_default
  msglist_unread
  msglist_read
  msglist_flagged
  msglist_deleted
  msglist_marked

So, the marked style will override all other msglist styles.

Colors

The color values are set using the values accepted by the tcell library. The values can be one of the following.

default

The color is set as per the system or terminal default.

<Color name>

Any w3c approved color name is used to set colors for the style.

<Hex code>

Hexcode for a color can be used. The format must be "#XXXXXX"

Referenced By

aerc-config(5).

2021-07-21