added documentation on how colorschemes work

2 files changed, 92 insertions, 1 deletions

diff --git a/TODO b/TODO
index 44de45aa..11d23a22 100644
--- a/TODO
+++ b/TODO
@@ -46,7 +46,7 @@ General
    (X) #61  10/02/09  show sum of size of marked files
    (X) #63  10/02/15  limit filesize in previews
    ( ) #64  10/02/25  scroll in previews
-   ( ) #66  10/02/28  explain how colorschemes work
+   (X) #66  10/02/28  explain how colorschemes work
 
 
 Bugs
diff --git a/doc/colorschemes.txt b/doc/colorschemes.txt
new file mode 100644
index 00000000..9df33c3e
--- /dev/null
+++ b/doc/colorschemes.txt
@@ -0,0 +1,91 @@
+= Abstract =
+
+This text explains colorschemes and how they work.
+
+
+= Context Tags =
+
+Context Tags provide information about the context.  If the tag
+"in_titlebar" is set, you probably want to know about the color
+of a part of the titlebar now.
+
+There are a number of context tags, specified in /ranger/gui/context.py
+in the constant CONTEXT_KEYS.
+
+A Context object, defined in the same file, contains attributes with
+the names of all tags, whose values are either True or False.
+
+
+= Implementation in the GUI Classes =
+
+The class CursesShortcuts in the file /ranger/gui/curses_shortcuts.py
+defines the methods color(*tags), color_at(y, x, wid, *tags) and
+color_reset().  This class is a superclass of Displayable, so these
+methods are available almost everywhere.
+
+Something like color("in_titlebar", "directory") will be called to
+get the color of directories in the titlebar.  This creates a
+ranger.gui.context.Context object, sets its attributes "in_titlebar" and
+"directory" to True, leaves the others as False, and passes it to the
+colorscheme's use(context) method.
+
+
+= The Color Scheme =
+
+A colorscheme should be a subclass of ranger.gui.ColorScheme and
+define the method use(context).  By looking at the context, this use-method
+has to determine a 3-tuple of integers: (foreground, background, attribute)
+and return it.
+
+foreground and background are integers representing colors,
+attribute is another integer with each bit representing one attribute.
+These integers are interpreted by the used terminal emulator.
+
+Abbreviations for colors and attributes are defined in ranger.gui.color.
+Two attributes can be combined via logical OR: bold | reverse
+
+Once the color for a set of tags is determined, it will be cached by
+default.  If you want more dynamic colorschemes (such as a different
+color for very large files), you will need to dig into the source code,
+perhaps add an own tag and modify the draw-method of the widget to use
+that tag.
+
+Run tc_colorscheme to check if your colorschemes are valid.
+
+
+= Specify a Colorscheme =
+
+Colorschemes are searched for in these directories:
+~/.ranger/colorschemes/
+/ranger/colorschemes/
+
+To specify which colorscheme to use, define the variable "colorscheme"
+in your options.py:
+colorscheme = colorschemes.default
+
+This means, use the (one) colorscheme contained in
+either ~/.ranger/colorschemes/default.py or /ranger/colorschemes/default.py.
+
+You can define more than one colorscheme in a colorscheme file.  The
+one named "Scheme" will be chosen in that case.  If there is no colorscheme
+named "Scheme", an arbitrary one will be picked.  You could also explicitly
+specify which colorscheme to use in your options.py:
+colorscheme = colorschemes.default.MyOtherScheme
+
+
+= Adapt a colorscheme =
+
+You may want to adapt a colorscheme to your needs without having
+a complete copy of it, but rather the changes only.  Say, you
+want the exact same colors as in the default colorscheme, but
+the directories to be green rather than blue, because you find the
+blue hard to read.
+
+This is done in the jungle colorscheme ranger.colorschemes.jungle.Scheme,
+check it out for implementation details.  In short, I made a subclass
+of the default scheme, set the initial colors to the result of the
+default use() method and modified the colors how I wanted.
+
+This has the obvious advantage that you need to write less, which
+results in less maintainance work and a greater chance that your colorscheme
+will work with future versions of ranger.