diff options
author | mathieui <mathieui@mathieui.net> | 2013-04-08 18:52:35 +0200 |
---|---|---|
committer | mathieui <mathieui@mathieui.net> | 2013-04-08 18:52:35 +0200 |
commit | bd8d38d711e15d42ac8e797723af5242e4c3f4fb (patch) | |
tree | d3ea6da641be1c7e67a3123071cb816933436502 /doc/source/themes.rst | |
parent | e5f219d43edbb4b05c8890f81f2f93b90e215a10 (diff) | |
download | poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.gz poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.bz2 poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.tar.xz poezio-bd8d38d711e15d42ac8e797723af5242e4c3f4fb.zip |
Beginning of the migration to reST documentation
Diffstat (limited to 'doc/source/themes.rst')
-rw-r--r-- | doc/source/themes.rst | 108 |
1 files changed, 108 insertions, 0 deletions
diff --git a/doc/source/themes.rst b/doc/source/themes.rst new file mode 100644 index 00000000..98b5f13e --- /dev/null +++ b/doc/source/themes.rst @@ -0,0 +1,108 @@ +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. |