3.6. Theming¶
Alot can be run in 1, 16 or 256 colour mode. The requested mode is determined by the command-line parameter -C or read from option colourmode config value. The default is 256, which scales down depending on how many colours your terminal supports.
Most parts of the user interface can be individually coloured to your liking.
To make it easier to switch between or share different such themes, they are defined in separate
files (see below for the exact format).
To specify the theme to use, set the theme config option to the name of a theme-file.
A file by that name will be looked up in the path given by the themes_dir config setting
which defaults to $XDG_CONFIG_HOME/alot/themes, and ~/.config/alot/themes/
,
if XDG_CONFIG_HOME is empty or not set. If the themes_dir is not
present then the contents of $XDG_DATA_DIRS/alot/themes will be tried in order.
This defaults to /usr/local/share/alot/themes
and /usr/share/alot/themes
, in that order.
These locations are meant to be used by distro packages to put themes in.
3.6.1. Theme Files¶
contain a section for each MODE plus “help” for the bindings-help overlay
and “global” for globally used themables like footer, prompt etc.
Each such section defines colour attributes for the parts that
can be themed. The names of the themables should be self-explanatory.
Have a look at the default theme file at alot/defaults/default.theme
and the config spec
alot/defaults/default.theme
for the exact format.
3.6.2. Colour Attributes¶
Attributes are sextuples of urwid Attribute strings that specify foreground and background for mono, 16 and 256-colour modes respectively. For mono-mode only the flags blink, standup, underline and bold are available, 16c mode supports these in combination with the colour names:
brown dark red dark magenta dark blue dark cyan dark green
yellow light red light magenta light blue light cyan light green
black dark gray light gray white
In high-colour mode, you may use the above plus grayscales g0 to g100 and
colour codes given as # followed by three hex values.
See here
and here
for more details on the interpreted values. A colour picker that makes choosing colours easy can be
found in alot/extra/colour_picker.py
.
As an example, check the setting below that makes the footer line appear as underlined bold red text on a bright green background:
[[global]]
#name mono fg mono bg 16c fg 16c bg 256c fg 256c bg
# | | | | | |
# v v v v v v
footer = 'bold,underline', '', 'light red, bold, underline', 'light green', 'light red, bold, underline', '#8f6'
3.6.3. Search mode threadlines¶
The subsection ‘[[threadline]]’ of the ‘[search]’ section in Theme Files determines how to present a thread: here, attributes ‘normal’ and ‘focus’ provide fallback/spacer themes and ‘parts’ is a (string) list of displayed subwidgets. Possible part strings are:
authors
content
date
mailcount
subject
tags
For every listed part there must be a subsection with the same name, defining
- normal:
attribute used for this part if unfocussed
- focus:
attribute used for this part if focussed
- width:
tuple indicating the width of the part. This is either (‘fit’, min, max) to force the widget to be at least min and at most max characters wide, or (‘weight’, n) which makes it share remaining space with other ‘weight’ parts.
- alignment:
how to place the content string if the widget space is larger. This must be one of ‘right’, ‘left’ or ‘center’.
3.6.3.1. Dynamic theming of thread lines based on query matching¶
To highlight some thread lines (use different attributes than the defaults found in the ‘[[threadline]]’ section), one can define sections with prefix ‘threadline’. Each one of those can redefine any part of the structure outlined above, the rest defaults to values defined in ‘[[threadline]]’.
The section used to theme a particular thread is the first one (in file-order) that matches the criteria defined by its ‘query’ and ‘tagged_with’ values:
If ‘query’ is defined, the thread must match that querystring.
If ‘tagged_with’ is defined, is value (string list) must be a subset of the accumulated tags of all messages in the thread.
Note
that ‘tagged_with = A,B’ is different from ‘query = “is:A AND is:B”’: the latter will match only if the thread contains a single message that is both tagged with A and B.
Moreover, note that if both query and tagged_with is undefined, this section will always match and thus overwrite the defaults.
The example below shows how to highlight unread threads: The date-part will be bold red if the thread has unread messages and flagged messages and just bold if the thread has unread but no flagged messages:
[search]
# default threadline
[[threadline]]
normal = 'default','default','default','default','#6d6','default'
focus = 'standout','default','light gray','dark gray','white','#68a'
parts = date,mailcount,tags,authors,subject
[[[date]]]
normal = 'default','default','light gray','default','g58','default'
focus = 'standout','default','light gray','dark gray','g89','#68a'
width = 'fit',10,10
# ...
# highlight threads containing unread and flagged messages
[[threadline-flagged-unread]]
tagged_with = 'unread','flagged'
[[[date]]]
normal = 'default','default','light red,bold','default','light red,bold','default'
# highlight threads containing unread messages
[[threadline-unread]]
query = 'is:unread'
[[[date]]]
normal = 'default','default','light gray,bold','default','g58,bold','default'
3.6.5. ANSI escape codes¶
Alot’s message display will interpret ANSI escape codes in the “body” text to be displayed.
You can use this feature to let your HTML renderer interpret colours from html mails and translate them to ANSI escapes. For instance, elinks can do this for you if you use the following entry in your ~/.mailcap:
text/html; elinks -force-html -dump -dump-color-mode 3 -dump-charset utf8 -eval 'set document.codepage.assume = "%{charset}"' %s; copiousoutput
3.6.6. Test your theme¶
Use the script in extra/theme_test.py to test your theme file. You should test with different terminal configurations, take black-on-white and white-on-black themes in account.