diff options
| -rw-r--r-- | TODO | 2 | ||||
| -rw-r--r-- | doc/colorschemes.txt | 91 |
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. |