From bb572219d1436f32fb6bd09f16943a5df7db8e12 Mon Sep 17 00:00:00 2001 From: Florent Le Coz Date: Sat, 5 Nov 2011 03:08:15 +0100 Subject: Add documentation for themes. --- doc/en/themes.txt | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 doc/en/themes.txt (limited to 'doc/en') diff --git a/doc/en/themes.txt b/doc/en/themes.txt new file mode 100644 index 00000000..ebf654fe --- /dev/null +++ b/doc/en/themes.txt @@ -0,0 +1,89 @@ +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 <>, +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. -- cgit v1.2.3