From 0f78f06610c0e8887aba2ae50e99b86477a384b3 Mon Sep 17 00:00:00 2001 From: Reto Brunner Date: Wed, 27 May 2020 07:37:02 +0200 Subject: Add Style configuration The following functionalities are added to configure aerc ui styles. - Read stylesets from file with very basic fnmatch wildcard matching - Add default styleset - Support different stylesets as part of UiConfig allowing contextual styles. - Move widgets/ui elements to use the stylesets. - Add configuration manual for the styleset --- doc/aerc-config.5.scd | 14 ++++ doc/aerc-stylesets.7.scd | 189 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 doc/aerc-stylesets.7.scd (limited to 'doc') diff --git a/doc/aerc-config.5.scd b/doc/aerc-config.5.scd index eb88849..3ff5177 100644 --- a/doc/aerc-config.5.scd +++ b/doc/aerc-config.5.scd @@ -173,6 +173,20 @@ These options are configured in the *[ui]* section of aerc.conf. Default: 250ms +*stylesets-dirs* + The directories where the stylesets are stored. The config takes a + colon-seperated list of dirs. + + Default: "/usr/share/aerc/stylesets" + +*styleset-name* + The name of the styleset to be used to style the ui elements. The + stylesets are stored in the 'stylesets' directory in the config + directory. + + Default: default + + ## Contextual UI Configuration The UI configuration can be specialized for accounts, specific mail diff --git a/doc/aerc-stylesets.7.scd b/doc/aerc-stylesets.7.scd new file mode 100644 index 0000000..5b4cd37 --- /dev/null +++ b/doc/aerc-stylesets.7.scd @@ -0,0 +1,189 @@ +aerc-stylesets(7) + +# Name + +aerc-stylesets - 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: `.fg=` + +*bg* + The background color of the style object is set. + + Syntax: `.bg=` + +*bold* + The bold attribute of the style object is set/unset. + + Syntax: `.bold=` + +*blink* + The blink attribute of the style object is set/unset. + _The terminal needs to support blinking text_ + + Syntax: `.bold=` + +*underline* + The underline attribute of the style object is set/unset. + _The terminal needs to support underline text_ + + Syntax: `.underline=` + +*reverse* + Reverses the color of the style object. Exchanges the foreground + and background colors. + + Syntax: `.reverse=` + _If the value is false, it doesn't change anything_ + +*normal* + All the attributes of the style object are unset. + + Syntax: `.normal=` + _The value doesn't matter_ + +*default* + Set the style object to the default style of the context. Usually + based on the terminal. + + Syntax: `.default=` + _The value doesn't matter_ + +## Style Objects +The style objects represent the various ui elements or ui instances for +styling. + +[[ *Style Object* +:[ *Description* +| default +: The default style object used for normal ui elements while not + using specialized configuration. +| error +: The style used to show errors. +| warning +: The style used when showing warnings. +| success +: The style used for success messages. +| title +: The style object used to style titles in ui elements. +| header +: The style object used to style headers in ui elements. +| statusline_default +: The default style applied to the statusline. +| statusline_error +: The style used for error messages in statusline. +| statusline_success +: The style used for success messages in statusline. +| msglist_default +: The default style for messages in a message list. +| msglist_unread +: Unread messages in a message list. +| msglist_read +: Read messages in a message list. +| msglist_deleted +: The messages marked as deleted. +| msglist_marked +: The messages with the marked flag. +| msglist_flagged +: The messages with the flagged flag. +| dirlist_default +: The default style for directories in the directory list. +| completion_default +: The default style for the completion engine. +| completion_gutter +: The completion gutter. +| completion_pill +: The completion pill. +| tab +: The style for the tab bar. +| stack +: The style for ui stack element. +| spinner +: The style for the loading spinner. +| border +: The style used to draw borders. *Only the background color is used*. +| selecter_default +: The default style for the selecter ui element. +| selecter_focused +: The focused item in a selecter ui element. +| selecter_chooser +: The item chooser in a selecter 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: +[[ *Pattern* +:[ *Meaning* +| \* +: Matches everything +| \? +: Matches any single character + +For example, the following wildcards can be made using this syntax. +[[ *Example* +:[ Description +| \*.fg=blue +: Set the foreground color of all style objects to blue. +| \*list.bg=hotpink +: Set 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 correspons 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. + +\tmsglist_default.selected.fg=yellow +\tmsglist_default.selected.bg=black + +If we specify the global style selected modifer using fnmatch as below: + +\t\*.selected.reverse=toggle + +This toggles the reverse switch for selected version of all the style objects. + +## 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. + + ** + Any w3c approved color name is used to set colors for the style. + + ** + Hexcode for a color can be used. The format must be "\#XXXXXX" + -- cgit 1.4.1-2-gfad0