108 lines
3.4 KiB
ReStructuredText
108 lines
3.4 KiB
ReStructuredText
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 colors, 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, making
|
||
the text impossible to read).
|
||
|
||
.. note:: 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.
|
||
|
||
To check how may colors your current terminal/$TERM supports, do:
|
||
|
||
.. code-block:: bash
|
||
|
||
tput colors
|
||
|
||
|
||
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:
|
||
|
||
.. code-block:: 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
|
||
|
||
.. code-block:: python
|
||
|
||
class FooTheme(theming.Theme):
|
||
COLOR_NAME = (fg_color, bg_color, opt_attr)
|
||
|
||
You do not have to define all the :ref:`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:
|
||
|
||
.. figure:: ./images/theme_256_colors.png
|
||
:alt: The list of all 256 colors
|
||
|
||
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
|
||
*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
|
||
*configuration file* to the directory that contains your
|
||
theme files.
|
||
|
||
.. _available-options:
|
||
|
||
Available options
|
||
-----------------
|
||
|
||
.. warning:: 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.
|