Themes
======

This page describes how themes work in poezio and how to create or
modify one.

A theme contains color attributes and character definitions. Poezio can display
up to _256_ colors if your terminal supports it. Most of the time,
if it doesn’t work, that’s because the _$TERM_ environnment variable is
wrong. For example with tmux or screen, set it to _screen-256color_, in
_xterm_, set it to _xterm-256color_, etc. If your terminal doesn’t have 256,
only 8 colors will be available, and poezio will replace the colors by one
of the 8 values available. Thus, some theme files may not work properly
if you only have 8 colors for example light gray on dark gray may
be converted to black on black if only 8 colors are available, making
the text impossible to read). The default theme should work properly in any
case. If not, that’s a bug.

A theme file is a python file (with the .py extension) containing a
class, inheriting the *theming.Theme* class defined into the *theming*
poezio module.

Create a theme
--------------

To create a theme named foo, create a file named foo.py into the theme
directory (by default it’s _~/.local/share/poezio/themes/_) and insert
into it:

[source,python]
----
import theming

class FooTheme(theming.Theme):
      # Define here colors for that theme
theme = FooTheme()
----

To define a _color pair_ and assign it to the COLOR_NAME option, just do
[source,python]
----
class FooTheme(theming.Theme):
      COLOR_NAME = (fg_color, bg_color, opt_attr)
----

You do not have to define all the <<available-options,available options>>,
you can decide that your theme will only change some options, the other
one will just have the default value (from the default theme).

Colors and attributes
~~~~~~~~~~~~~~~~~~~~~
A color pair defines how the text will be displayed on the screen. It
has a _foreground color_ (fg_color), a _background color_ (bg_color)
and an *_optional_* _attribute_ (opt_attr).

Colors
^^^^^^
A color is a number between -1 and 255. If it -1, this is the default
color defined by your terminal (for example if your terminal displays
text white on black by default, a fg_color of -1 is white, and a bg_color
of -1 is black). If it’s between 0 and 256 it represents one of the colors
on the image:

image::../images/theme_256_colors.png["The list of all 256 colors", title="The list of all 256 colors"]

Attributes
^^^^^^^^^^
An attribute is a python string (so, it has to be surrounded by
*" "* or *' '*). It can be one of the following

* *'b'*: bold text
* *'u'*: underlined text

Use a theme
-----------
To use a theme, just define the _theme_ option into the
link:configure.html[configuration file] to the name of the theme you want
to use. If that theme is not found, the default theme will be used instead.
Note that the default theme is defined directly into poezio’s source code,
and not in a theme file.

Change the theme directory
--------------------------
To change the default theme directory (_~/.local/share/poezio/themes/_ by
default), you have to change the _themes_dir_ option in the
link:configure.html[configuration file] to the directory that contains your
theme files.

[[available-options]]
Available options
-----------------

CAUTION: This section is not complete.

All available options can be found into the default theme, which is into the
_theming.py_ file from the poezio’s source code.