colorscheme: clean up

1 files changed, 56 insertions, 33 deletions

diff --git a/ranger/gui/colorscheme.py b/ranger/gui/colorscheme.py
index 967a4fdd..f9fe5d90 100644
--- a/ranger/gui/colorscheme.py
+++ b/ranger/gui/colorscheme.py
@@ -1,3 +1,33 @@
+"""
+Colorschemes define colors for specific contexts.
+
+Generally, this works by passing a set of keywords (strings) to
+the colorscheme.get() method to receive the tuple (fg, bg, attr).
+fg, bg are the foreground and background colors and attr is the attribute.
+The values are specified in ranger.gui.color.
+
+A colorscheme must...
+
+1. be inside either of these directories:
+~/.ranger/colorschemes/
+path/to/ranger/colorschemes/
+
+2. be a subclass of ranger.gui.colorscheme.ColorScheme
+
+3. implement a use(self, context) method which returns (fg, bg, attr).
+context is a struct which contains all entries of CONTEXT_KEYS,
+associated with either True or False.
+
+define which colorscheme to use by having this to your options.py:
+from ranger import colorschemes
+colorscheme = colorschemes.filename
+
+If your colorscheme-file contains more than one colorscheme, specify it with:
+colorscheme = colorschemes.filename.classname
+"""
+
+from ranger.ext.openstruct import OpenStruct
+
 CONTEXT_KEYS = [ 'reset', 'error',
 		'in_browser', 'in_statusbar', 'in_titlebar', 'in_console',
 		'in_pager', 'in_taskview',
@@ -14,36 +44,25 @@ CONTEXT_KEYS = [ 'reset', 'error',
 		'title', 'text', 'highlight', 'bars', 'quotes',
 		'keybuffer']
 
-# colorscheme specification:
-#
-# A colorscheme must...
-#
-# 1. be inside either of these directories:
-# ~/.ranger/colorschemes/
-# path/to/ranger/colorschemes/
-#
-# 2. be a subclass ofranger.gui.colorscheme.ColorScheme
-# 
-# 3. have a use(self, context) method which returns a tuple of 3 integers.
-# the first integer is the foreground color, the second is the background
-# color, the third is the attribute, as specified by the curses module.
-#
-#
-# define which colorscheme to use by having this to your options.py:
-# from ranger import colorschemes
-# colorscheme = colorschemes.filename
-# 
-# If your colorscheme-file contains more than one colorscheme, specify it with:
-# colorscheme = colorschemes.filename.classname
+class ColorScheme(object):
+	"""
+	This is the class that colorschemes must inherit from.
 
-from ranger.ext.openstruct import OpenStruct
+	it defines get() 
+	it defines the get() method, which returns the color tuple
+	which fits to the given keys.
+	"""
 
-class ColorScheme(object):
 	def __init__(self):
 		self.cache = {}
 
 	def get(self, *keys):
-		"""Determine the (fg, bg, attr) tuple or get it from cache"""
+		"""
+		Returns the (fg, bg, attr) for the given keys.
+
+		Using this function rather than use() will cache all
+		colors for faster access.
+		"""
 		try:
 			return self.cache[keys]
 
@@ -59,19 +78,23 @@ class ColorScheme(object):
 			return color
 
 	def get_attr(self, *keys):
-		"""Returns the curses attr integer for the specified keys"""
+		"""
+		Returns the curses attribute for the specified keys
+		
+		Ready to use for curses.setattr()
+		"""
+		from curses import color_pair
 		from ranger.gui.color import get_color
-		import curses
 
 		fg, bg, attr = self.get(*keys)
-		return attr | curses.color_pair(get_color(fg, bg))
-
+		return attr | color_pair(get_color(fg, bg))
 
 	def use(self, context):
-		"""Use the colorscheme to determine the (fg, bg, attr) tuple.
-      This is a dummy function which always returns default_colors.
-      Override this in your custom colorscheme!
-      """
+		"""
+		Use the colorscheme to determine the (fg, bg, attr) tuple.
+		This is a dummy function which always returns default_colors.
+		Override this in your custom colorscheme!
+		"""
 		from ranger.gui.color import default_colors
-		return default_colors
 
+		return default_colors