89 lines
3 KiB
Text
89 lines
3 KiB
Text
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 color will be available, and poezio will replace the colors by one
|
||
of the 8 values available. Thus, some theme file 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 *themimg.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 note in a theme file.
|
||
|
||
[[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.
|