From 6a70583077425bbe165196cf09f49aca3cb222b8 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Sat, 7 Jul 2018 12:09:26 -0400 Subject: Revamped context section of the colorscheme doc Added basic instruction on how to add a context key with a working example. --- doc/colorschemes.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 6 deletions(-) (limited to 'doc/colorschemes.md') diff --git a/doc/colorschemes.md b/doc/colorschemes.md index c7600700..eaf90174 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -6,14 +6,71 @@ 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. +Context tags provide information about the context and are Boolean values (`True` +or `False`). For example, 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`. +The default context tags are specified in `/ranger/gui/context.py` in the +constant `CONTEXT_KEYS`. Custom tags can be specified in a custom plugin file in +`~/.config/ranger/plugins/`. The code to use follows. -A Context object, defined in the same file, contains attributes with the names -of all tags, whose values are either `True` or `False`. +```python +# Import the class +import ranger.gui.context + +# Add your key names +ranger.gui.context.CONTEXT_KEYS.append('my_key') + +# Set it to false (the default value) +ranger.gui.context.Context.my_key = False + +# Or use an array for multiple names +my_keys = ['key_one', 'key_two'] +ranger.gui.context.CONTEXT_KEYS.append(my_keys) + +# Set them to False +for key in my_keys: + code = 'ranger.gui.context.Context.' + key + ' = False' + exec(code) +``` + +As you may or may not have guessed, this only tells ranger that they exist, not +what they mean. To do this, you'll have to dig around in the source code. As an +example, let's walk through adding a key that highlights `README.md` files +differently. All the following code will be written in a standalone plugin file. + +First, from above, we'll add the key `readme` and set it to `False`. + +```python +import ranger.gui.context + +ranger.gui.context.CONTEXT_KEYS.append('readme') +ranger.gui.context.Context.readme = False +``` + +Then we'll use the hook `hook_before_drawing` to tell ranger that our key is +talking about `README.md` files. + +```python +import ranger.gui.widgets.browsercolumn + +OLD_HOOK_BEFORE_DRAWING = ranger.gui.widgets.browsercolumn.hook_before_drawing + +def new_hook_before_drawing(fsobject, color_list): + if fsobject.basename === 'README.md': + color_list.append('readme') + + return OLD_HOOK_BEFORE_DRAWING(fsobject, color_list) + +ranger.gui.widgets.browsercolumn.hook_before_drawing = new_hook_before_drawing +``` + +Notice we call the old `hook_before_drawing`. This makes sure that we don't +overwrite another plugin's code, we just append our own to it. + +To highlight it a different color, just [add it to your colorscheme][1] + +[1]:#adapt-a-colorscheme Implementation in the GUI Classes --------------------------------- -- cgit 1.4.1-2-gfad0 From 2a8565d175a58172983d410b36e8644d484c1cc8 Mon Sep 17 00:00:00 2001 From: Saturnus Numerius Date: Sat, 7 Jul 2018 12:22:19 -0400 Subject: Fixed some capitalization issues --- doc/colorschemes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/colorschemes.md') diff --git a/doc/colorschemes.md b/doc/colorschemes.md index eaf90174..458cfc53 100644 --- a/doc/colorschemes.md +++ b/doc/colorschemes.md @@ -21,7 +21,7 @@ import ranger.gui.context # Add your key names ranger.gui.context.CONTEXT_KEYS.append('my_key') -# Set it to false (the default value) +# Set it to False (the default value) ranger.gui.context.Context.my_key = False # Or use an array for multiple names -- cgit 1.4.1-2-gfad0