90 lines
3 KiB
Text
90 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.
|