Skip to content

Latest commit

 

History

History
1097 lines (858 loc) · 40 KB

README.md

File metadata and controls

1097 lines (858 loc) · 40 KB
Raw

vimade

([n]vim[f]ade)

Fade, Highlight, and Customize Your Windows + Buffers

What is this?

Vimade helps you maintain focus on the active part of the screen, especially when working with many open windows. It allows you to customize, highlight, fade, tint, and animate colors in your windows and buffers.

What is required?

Neovim 0.8.0+: This plugin supports a lua-only code path, you are all set!

Vim7.4+ and Neovim < 0.8.0: Python or Python3 support is required. If using these older versions of Neovim, you'll need to install pynvim.

Features

  • Fade or highlight windows or buffers.
  • Link windows so they change together (e.g. diffsplit)
  • Blocklist specific windows or buffers from customization.
  • Set Custom tints for a unique visual experience.
  • Prebuilt recipes for quick and easy customization.
  • Fully customizable (styles, recipes, and more).
  • Animated transitions for a smooth visual experience.
  • Automatically adjust to configuration changes.
  • Helpers to make inactive built-in highlights look better
  • Supports 256 color terminals and termguicolors.
  • Sub-milliscond Lua performance and highly optimized Python logic for Vim.
  • Preconfigured commands (VimadeEnable, VimadeDisable, VimadeRedraw, etc)
  • Supports all versions of Neovim and Vim 7.4+
  • Vim Documentation/Help

Whats coming?

  • More awesome features and improvements! (details to be added later)

Getting started:

Installation

  • Any plugin manager will work. Here's an example using vim-plug:

    ::vimscript::plug::

      Plug 'TaDaa/vimade'

  • And for Lua users using lazy.nvim:

    ::lua::lazy::

      require('lazy').setup({spec = {'tadaa/vimade'}})
    For Python users:

    If you are using vim or older versions of neovim and want to configure using python, you need to bind your setup to Vimade#PythonReady. This ensures that Vimade has been added to the python path before your configuration runs. Here's an example that sets up the Minimalist recipe.

     
    function! SetupMyVimadeConfig()
python << EOF
from vimade import vimade
from vimade.recipe.minimalist import Minimalist
vimade.setup(**Minimalist(animate=True))
EOF
endfunction
au! User Vimade#PythonReady call SetupMyVimadeConfig()
Lazy loading

  • In Neovim 0.8.0+, use lazy.nvim or similar plugin manager and the event of choice:

    ::lua::lazy::

    require('lazy').setup({spec = {'tadaa/vimade', event = 'VeryLazy'}})

  • For Vim or more granular control, enable vimade.lazy and call vimade#Load():

      ::vimscript::

    let g:vimade = {}
let g:vimade.lazy = 1

au WinEnter * ++once call vimade#Load()
Configuring Vimade (a basic guide)

Vimade works by just installing it and no configuration is required. However, it also offers extensive customizations. Most users may want to adjust the fadelevel and tint. You can configure Vimade using Vimscript, Lua, or Python.

If you prefer a general configuration compatible with both Neovim and Vim, Vimscript is a good option. You can also apply the Lua and Python-specific parts on top of these options, so nothing is mutually exclusive.

::vimscript::

let g:vimade = {}

This initializes a vimade object for configuration. Vimade will automatically extend it with default values.

Now let's start adding changes:

::vimscript::

let g:vimade.fadelevel = 0.5

This code changes the opacity of inactive windows. You can choose any value between 0 (completely faded) and 1 (fully opaque).

Let's add a blue tint:

::vimscript::

let g:vimade.tint = {'fg':{'rgb':[0,0,255], 'intensity': 0.5}}

You should notice that your text color has changed. The tint option can manipulate fg, bg, and sp attributes. Changing vimade.tint.bg lets you customize the background color of inactive windows.

Let's try something a bit more complicated, suppose we have a filetree that we don't want to dim as extremely as our other windows. You may remember that I said we need to configure functions directly in python or lua, so let's take a look:

::lua:: 

require('vimade').setup{
  fadelevel = function(style, state)
    if style.win.buf_opts.syntax == 'nerdtree' then
      return 0.8
    else
      return 0.4
    end
  end}

::python:: 

from vimade import vimade
vimade.setup(
  fadelevel = lambda style, state:
    0.8 if style.win.buf_opts['syntax'] == 'nerdtree'
    else 0.4)

Both languages use almost identitical syntax for configuration.

Advanced configurations in python and lua are treated as overlays, whatever you pass through the setup functions will overlay on top of your vimscript configuration. This means you won't be able to do an advanced configuration, then override it with a vimscript configuration after. You'll need to unset the advanced configuration first, which can be done as seen below

::lua:: 

-- sets the overlay back to empty
require('vimade').setup{}

::python:: 

from vimade import vimade
# sets the overlay back to empty
vimade.setup()

You now know the basics for configuring Vimade!

Vimscript defaults

::vimscript::

let g:vimade = {
\   " common options below
\   'renderer': 'auto',
\   'ncmode': 'buffers',
\   'fadelevel': 0.4,
\   'tint': '',
\   'basebg': '',
\   'blocklist': {
\     'default': {
\       'buf_opts': {
\         'buftype': lua ? ['prompt', 'terminal'] : ['popup', 'prompt']
\       },
\       'win_config':{
\         'relative': v:true
\       },
\     }
\   },
\   'link': {},
\   'groupdiff': 1,
\   'groupscrollbind': 0,
\   'checkinterval': g:vimade_features.has_gui_running && !(g:vimade_features.has_nvim) ? 100 : 500,
\   'usecursorhold': g:vimade_features.has_gui_running && !g:vimade_features.has_nvim && g:vimade_features.has_gui_version,
\   'enablefocusfading': 0,
\   'normalid': '',
\   'normalncid': '',
\   'lazy': 0,
\   " python-only options below
\   'basegroups': ['Folded', 'Search', 'SignColumn', 'CursorLine', 'CursorLineNr', 'DiffAdd', 'DiffChange', 'DiffDelete', 'DiffText', 'FoldColumn', 'Whitespace', 'NonText', 'SpecialKey', 'Conceal', 'EndOfBuffer', 'WinSeparator', 'LineNr', 'LineNrAbove', 'LineNrBelow'],
\   'enablebasegroups': 1,
\   'enablesigns': 1,
\   'signsid': 13100,
\   'signsretentionperiod': 4000,
\   'signspriority': 31,
\   'fademinimap': 1,
\   'fadepriority': 10,
\   'disablebatch': 0,
\   " lua only options below
\   'nohlcheck': 1,
\ }
Lua defaults

::lua::

vimade.setup{
  style = require(vimade.style.default).Default().style,
  ncmode = 'buffers',
  fadelevel = 0.4,
  tint = {},
  basebg = '',
  blocklist = {
    buf_opts = { buftype = ['prompt', 'terminal'] },
    win_config { relative = true },
  },
  link = {},
  groupdiff = 1,
  groupscrollbind = 0,
  enablefocusfading = 0,
  normalid = '',
  normalncid = '',
  nohlcheck = 1,
}
Python defaults

::python::

from vimade import vimade
from vimade.recipe.default import Default
vimade.setup(
  style = Default()['style'],
  ncmode = 'buffers',
  fadelevel = 0.4,
  tint = None,
  basebg = '',
  blocklist = {
    'buf_opts': { 'buftype': ['popup', 'prompt'] },
    'win_config': { 'relative': True },
  },
  link = {},
  groupdiff = 1,
  groupscrollind = 0
  enablefocusfading = 0
  normalid = '',
  normalncid = '',
  basegroups = ['Folded', 'Search', 'SignColumn', 'CursorLine', 'CursorLineNr', 'DiffAdd', 'DiffChange', 'DiffDelete', 'DiffText', 'FoldColumn', 'Whitespace', 'NonText', 'SpecialKey', 'Conceal', 'EndOfBuffer', 'WinSeparator', 'LineNr', 'LineNrAbove', 'LineNrBelow'],
  enablebasegroups = 1,
  enablesigns = 1,
  signsid = 13100,
  signsretentionperiod = 4000,
  signspriority = 31,
  fademinimap = 1,
  fadepriority = 10,
  disablebatch = 0,
)
Option docs & descriptions

Options for Lua, Python, and Vimscript

option values/type default description
renderer 'auto' 'python' 'lua'
'auto' auto automatically assigns vim users to python and detects if neovim users have the requires features for lua. For neovim users on lua mode, the python logic is never run. Neovim users with missing features will be set to python and need pynvim installed.
ncmode 'windows' 'buffers' 'buffers' highlight or unhighlight buffers or windows together
fadelevel float [0-1] function(style,state)=>float 0.4 The amount of fade opacity that should be applied to fg-text (0 is invisible and 1 is no fading)
tint When set via lua or python, each object or number can also be a function that returns the corresponding value component

{'fg':{'rgb':[255,255,255], 'intensity':1, 'bg':{'rgb':[0,0,0], 'intensity':1}, 'sp':{'fg':[0,0,255], 'intensity':0.5}}}		 nil The amount of tint that can be applied against each highlight component (fg, bg, sp). Intensity is a float value [0-1], where 1 is the most intense and 0 is not tinted. See the tinting tutorial for more details.
basebg '#FFFFFF' [255,255,255] 0xFFFFFF nil This value manipulates the target background color. This is most useful for transparent windows, where the Normal bg is NONE. Set this value to a good target value to improve fading accuracy.
blocklist When set via lua or python, the top level named object can be a function(win)=>bool. Each nested object or value can also be a function(relative_config)=>bool. True indicates blocked, False not linked, nil indeterminate.

{[key:string]: {'buf_opts': {[key]:string: value}, 'buf_vars': {...}, 'win_opts': {...}, 'win_vars': 'win_config': {...}}}		 {'default':{'buf_opts': {'buftype':['prompt', 'terminal', 'popup']}, 'win_config': {'relative': 1}}} If the window is determined to be blocked, Vimade highlights will be removed and it will skip the styling process. See the block and linking section for more details.
link When set via lua or python, the top level named object can be a function(win, active_win)=>bool. Each nested object or value can also be a function(relative_win_obj,active_win_obj)=>bool. True indicates linked, False not linked, nil indeterminate.

 nil Determines whether the current window should be linked and unhighlighted with the active window. groupdiff and groupscrollbind tie into the default behavior of this object behind the scenes to unlink diffs. See the block and linking section for more details.
groupdiff 0 1 bool 1 highlights and unhighlights diff windows together.
groupscrollbind 0 1 bool 0 highlights and unhighlights scrolllbound windows together.
checkinterval int 100-500 Time in milliseconds before re-checking windows. Default varies depending on Neovim, terminals, and gui vim.
usecursorhold 0 1 bool 0 Whether to use cursorhold events instead of async timer. Setting this option disables the timer. This option defaults to 0 for most editor versions. gvim defaults to 1 due to async timers breaking visual selections. If you use this value, remember to set :set updatetime appropriately.
enablefocusfading 0 1 bool 0 Highlight the active window on application focus and blur events. This can be desirable when switching applications, but requires additional setup for terminal and tmux. See enablefocusfading section for more details (TODO link)
normalid int nil The id of the Normal highlight. Vimade will automatically set this, so you don't need to worry about it. You can override it though if you just want to play around.
normalncid int nil The id of the NormalNC highlight. Vimade will automatically set this, so you don't need to worry about it. You can override it though if you just want to play around.
lazy 1 0 nil When set to 1 Vimade is disabled at startup. You will need to manually call vimade#Load(). See lazy loading section for more details.

Options only for Lua

option values/type default description
nohlcheck bool true When set to false, Vimade will recompute namespaces each frame. This is useful if you have a plugin that dynamically changes highlights periodically. When to true Vimade only recomputes namespaces when you switch between buffers/windows. Performance isn't an issue either way as the recomputation process is sub-millisecond.

Options only for python

option values/type default description
enablesigns 0 1 bool True Whether or not to fade signs. For python this has to be performed per-buffer. If you want per-window signs, you will need to link your sign highlights to Normal.
signsid int 13100 The id that should be used to generate sign. This is required to avoid collisions with other plugins.
signsretentionperiod int 4000 The amount of time after a window becomes inactive to check for sign updates. Many plugins asynchronously update the buffer after switching windows, this helps ensure signs stay faded.
fademinimap 0 1 bool 1 Enables a special fade effect for severin-lemaignan/vim-minimap. Setting vimade.fademinimap to 0 disables the special fade.
matchpriority int 10 Controls the highlighting priority. You may want to tweak this value to make Vimade play nicely with other highlighting plugins and behaviors. For example, if you want hlsearch to show results on all buffers, you may want to lower this value to 0.
linkwincolor string[] [] Vim only option when wincolor is supported. List of highlights that will be linked to Normal. Normal is highlighted using setlocal wincolor, which gives Vim some flexibility to target highlight groups (see minimalist recipe).
disablebatch 0 1 bool 0 Disables IPC batching. Enabling this will greatly reduce performance, but allow you debug issues.
enablebasegroups 0 1 bool true Only old Neovim. Allows winlocal winhl for the basegroups listed below.
basegroups string[] every built-in highlight Only old Neovim. Fades the listed highlights in addition to the buffer text.
enabletreesitter 0 1 bool 0 Only old Neovim. Uses treesitter to directly query highlight groups instead of relying on synID.
Preparing a transparent terminal

When using a transparent terminal, your Normal highlight is set to NONE. Plugins like Vimade don't know the real color. Vimade will assume that your background is either black or white depending on the value of echo &background. For better color accuracy:

  1. Prepare a pure white background (it must be exactly #FFFFFF).

  2. Place your terminal over the background

  3. Use a color picker tool to obtain the exact color value. This value is typically a good starting point.

  4. Set basebg to whatever the color value is in your Vimade config. For example:

    ::vimscript::

    let g:vimade.basebg=[11,11,11]

    ::lua::

    require('vimade').setup{basebg={11,11,11}}

    ::python::

    from vimade import vimade
vimade.setup(basebg=[11,11,11])

  5. Repeat step 4, but darken basebg until you find a value that suits your preferences.


Buffers or windows

The primary and legacy behavior of Vimade is to fade and tint inactive buffers. You can also enable window fading if you prefer!

::vimscript::

let g:vimade.ncmode = 'buffers'
let g:vimade.ncmode = 'windows'

Most users should try each option to see what they like best. For most, there are inherit benefits to fading based on buffers as its easier to see which windows are impacted by your edits or which windows you can cleanup.

Tinting

There are lots of ways that you can configure tinting. Tinting influences the color of fg, bg, and sp for every highlight group. Every option allows you specify intensity, which determines how much color to add.

Changing the fg alters the text color. Let's give our inactive windows some yoda spunk:

::vimscript::

let g:vimade.tint = {'fg':{'rgb':[0,255,0], 'intensity': 0.3}}

The more that you raise the intensity, the closer each highlight will be the specified rgb value. So let's say you want to disable syntax highlighting on inactive windows, all you need to do is set the intensity to the value 1.

::vimscript::

let g:vimade.tint = {'fg':{'rgb':[200,200,200], 'intensity': 1}}

bg directly impacts the window background color. It also indirectly impacts the fg color if you have fading enabled because fades are performed against the background color.

::vimscript::

let g:vimade.tint = {'bg':{'rgb':[0,0,0], 'intensity': 0.15}}

bg and all tint attributes have different effects depending on the value of vimade.ncmode. When using let g:vimade.ncmode='buffers', tints only impact inactive buffers. When using let g:vimade.ncmode='windows' they affect windows, see the screenshots below for a comparison that also combines our changes above.

::vimscript::

let g:vimade.ncmode = 'buffers'
let g:vimade.tint = {
  \ 'fg': { 'rgb': [0,255,0], 'intensity': 0.3 },
  \ 'bg': { 'rgb': [0,0,0], 'intensity': 0.15 }}

::vimscript::

let g:vimade.ncmode = 'windows'
let g:vimade.tint = {
  \ 'fg': {'rgb': [0,255,0], 'intensity': 0.3 },
  \ 'bg': {'rgb': [0,0,0], 'intensity': 0.15 }}

Blocklists and linking

Blocklists and linking are conceptually similar processes. Blocklists prevent a window from being styled. Linking on the other hand lets you bind other windows to the active window so that they style and unstyle together.

You can specific any property in the following objects, or use a function that returns true when a condition is met.

let g:vimade.blocklist = {
 \ 'rule_name': {
 \   'buf_names': [], " list of strings and/or functions to evaluate string comparison
 \   'buf_opts': {}, " any buffer scoped option (e.g. buftype)
 \   'buf_vars': {}, " any buffer variable (i.e. `let b:...`)
 \   'win_opts': {}, " any window scoped option
 \   'win_vars': {}, " any window variable (i.e `let w:...`)
 \   'win_config': {}, " any window config item (see `help nvim_win_get_config`)
 \ }
}
let g:vimade.link = {
 \ 'rule_name': {
 \   'buf_names': [], " list of strings and/or functions to evaluate string comparison
 \   'buf_opts': {}, " any buffer scoped option (e.g. buftype)
 \   'buf_vars': {}, " any buffer variable (i.e. `let b:...`)
 \   'win_opts': {}, " any window scoped option
 \   'win_vars': {}, " any window variable (i.e `let w:...`)
 \   'win_config': {}, " any window config item (see `help nvim_win_get_config`)
 \ }
}

The rule_name in the config above is arbitrary, but don't use default unless you want to override Vimade's default settings.

For lua defaults are:

  blocklist = {
    default = {
      -- terminal is temporarily disabled until proper fading is added
      buf_opts = {buftype = {'prompt', 'terminal'}},
      win_config = {
        relative = true
      },
    },
  },

and python:

'blocklist': {
  'default': {
    'buf_opts': {
      'buftype': ['popup', 'prompt']
    },
    'win_config': {
      'relative': True #block all floating windows # TODO we can make this more customized soon
     },
  }
},

Each value for a property is a considered a value-matcher, you can use an array-like or exact value type. Array-like indicates that any value in the array is a match. Using boolean (true) indicates that any truthy value will match.

Let's put this to the test and block all window variables with 'cool' equal to 1 or 2

let w:cool = 2
let g:vimade.blocklist = {
\  'demo_tutorial': {
\    'win_vars': { 'cool': [1,2] },
\  }
\ }

Now when you navigate off the window, nothing happens.

Let's replace the previous rule with a function that blocks everything except when a floating window is open:

::lua::

require('vimade').setup({
  blocklist = {
    demo_tutorial = function (win, current)
      -- current can be nil
      if (win.win_config.relative == '') and (current and current.win_config.relative ~= '') then
        return false
      end
      return true
    end
  }
})

::python::

def only_behind_float_windows (win, current):
  # current can be None
  if (win.win_config['relative'] == '') and (current and current.win_config['relative'] != ''):
    return False
  return True

vimade.setup(blocklist = {
    'demo_tutorial': only_behind_float_windows,
})

Now nothing is faded except when you open a floating window, voilà!

For a final step let's apply the same concepts to linking

let w:linked_window = 1
let g:vimade.blocklist = {
\  'demo_tutorial': {
\    'win_vars': { 'linked_window': 1 },
\  }
\ }

Navigate to another window and also apply

let w:linked_window = 1

The windows are now bound together and will style and unstyle together. This is an extremely useful concept and Vimade uses it behind the scenes to ensure that diffs are visible in unison.

Style modifiers

Styles are the core functions that drive Vimade. Each style decides how to manipulate the highlights based on their own input. Styles can be combined, nested, or transpose each other, the process itself is configurable and its up to you to decide how to use them. This section is intended for advanced customizations or users who want to build their own recipes. You are also more than welcome to build your own style and add it into Vimade.

Fade

Fades each window based on the value (also referred to as fadelevel). Colors are modified against the background color.

::lua::

local Fade = require('vimade.style.fade').Fade
vimade.setup{
  style = {
    Fade{value = 0.4}
  }
}

::python::

from vimade import vimade
from vimade.style.fade import Fade
vimade.setup(style = [
  Fade(value = 0.4)
])
option values/type default description
value number function(style,state)=>number nil The target fadelevel. Value ranges from 0 to 1, where 0 is completely faded and 1 is unfaded.
tick function()=>void nil A function that is run once per frame. Useful if you need to do expensive pre-computation that shouldn't occur once per-window.
Tint

Tints each window based on fg, bg, and sp inputs.

::lua::

local Tint = require('vimade.style.Tint').Tint
vimade.setup{
  style = {
    Tint{
      value = {
        fg = {rgb = {0,0,0}, intensity = 0.5},
        bg = {rgb = {0,0,0}, intensity = 0.5},
        sp = {rgb = {0,0,0}, intensity = 0.5},
      }
    }
  }
}

::python::

from vimade import vimade
from vimade.style.tint import Tint
vimade.setup(style = [
  Tint(value = {
    'fg': { 'rgb': [0,0,0], 'intensity': 0.5 },
    'bg': { 'rgb': [0,0,0], 'intensity': 0.5 },
    'sp': { 'rgb': [0,0,0], 'intensity': 0.5 },
  })
])
option values/type default description
value 
{fg:{rgb:[num,num,num],intensity:num},
 bg:{rgb:[num,num,num],intensity:num},
 sp:{rgb:[num,num,num],intensity:num}}
function(style,state)=any(functions can be used for any part of the tint config object)		 nil The target tint colors. Intensity is the inverse of fadelevel. 1 is full intensity, while 0 is not applied.
tick function()=>void nil A function that is run once per frame. Useful if you need to do expensive pre-computation that shouldn't occur once per-window.
Include

Runs nested style modifiers when the highlight is included in the value.

::lua::

local Fade = require('vimade.style.fade').Fade
local Include = require('vimade.style.include').Include
vimade.setup{
  style = {
    Include{
      value = ['WinSeparator', 'VertSplit', 'LineNr', 'LineNrAbove', 'LineNrBelow'],
      style = {
        Fade { value = 0.4 }
      }
    }
  }
}

::python::

from vimade import vimade
from vimade.style.fade import Fade
from vimade.style.include import Include
vimade.setup(style = [
  Include(
    value = ['Normal', 'Comment'],
    style = [
      Fade(value = 0.4)
    ]
  )
])
option values/type default description
value string[] nil The list of highlight names that the nested styles will execute modifies on.
style Style[] nil The list of styles that are run when highlights are included.
tick function()=>void nil A function that is run once per frame. Useful if you need to do expensive pre-computation that shouldn't occur once per-window.
Exclude

Runs nested style modifiers when the highlight is not included in the value.

::lua::

local Fade = require('vimade.style.fade').Fade
local Exclude = require('vimade.style.exclude').Exclude
vimade.setup{
  style = {
    Exclude{
      value = ['WinSeparator', 'VertSplit', 'LineNr', 'LineNrAbove', 'LineNrBelow'],
      style = {
        Fade { value = 0.4 }
      }
    }
  }
}

::python::

from vimade import vimade
from vimade.style.fade import Fade
from vimade.style.exclude import Exclude
vimade.setup(style = [
  Exclude(
    value = ['Normal', 'Comment'],
    style = [
      Fade(value = 0.4)
    ]
  )
])
option values/type default description
value string[] nil The list of highlight names that the nested styles will execute modifies on.
style Style[] nil The list of styles that are run when highlights are included.
tick function()=>void nil A function that is run once per frame. Useful if you need to do expensive pre-computation that shouldn't occur once per-window.
Combining styles

This section is not ready yet!
Animations

The section below will look at using a custom animation value within a style, so please read the style section before proceeding!

Animations are functions that mutate values over time. Vimade includes a number of helpers that alter the interpolation process.

[!NOTE] Animations can only be added using lua or python.

Let's look at an example:

::lua::

local Fade = require('vimade.style.fade').Fade
local animate = require('vimade.style.value.animate')
require('vimade').setup{style = {
  Fade {
    value = animate.Number {
      start = 1,
      to = 0.2
    }
  }
}}

::python::

from vimade import vimade
from vimade.style import fade
from vimade.style.value import animate
vimade.setup(style = [
  Fade(value = animate.Number(
    start = 1,
    to = 0.2,
  )),
])

The example above uses animate.Number to fade inactive windows from no-fade start = 1 to almost completely faded to = 0.2.

The animation can be further customized by overriding any of the default values:

::lua::

local Fade = require('vimade.style.fade').Fade
local direction = require('vimade.style.value.direction')
local ease = require('vimade.style.value.ease')
local animate = require('vimade.style.value.animate')
require('vimade').setup{style = {
  Fade {
    value = animate.Number {
      start = 1,
      to = 0.2,
      direction = direction.IN_OUT,
      ease = ease.OUT_BOUNCE,
      duration = 1000,
      delay = 100,
    }
  }
}}

::python::

from vimade import vimade
from vimade.style import fade
from vimade.style.value import animate
from vimade style.value import direction
from vimade style.value import ease
vimade.setup(style = [
  Fade(value = animate.Number(
    start = 1,
    to = 0.2,
    direction = direction.IN_OUT,
    ease = ease.OUT_BOUNCE,
    duration = 1000,
    delay = 100,
  )),
])

Every value type can be animated included tints and nested values in complex objects. See the recipe source for more examples.

option values/type default description
start any function(style,state)=>any nil The starting value that the animation begins at. If direction=IN_OUT, then the starting value is only used one time when the value is uninitialized.
to any function(style,state)=>any nil The ending value that the animation ends at.
direction IN OUT IN_OUT OUT These are specialized functions and MUST be used from the exported vimade.style.value.direction enum. OUT is a outward animation, which should typically be associated with "leaving" something. IN is an inward animation that should be associated with "entering". IN_OUT tracks the value and performs both IN and OUT behaviors.
ease LINEAR OUT_QUART IN_QUART IN_OUT_QUART IN_CUBIC OUT_CUBIC ... OUT_QUART These are functions and can be used from vimade.style.value.ease. You can also use your own custom function(time)=>percent_time. Easing functions change the animation behavior by mutating percent_time. See source for examples: lua | python.
duration number function(state,state)=>number 300 The duration of the animation in milliseconds.
delay number function(style,state)=>number 0 How long to wait before starting the animation.
Recipe: Default

This recipe is enabled by default, but you can re-apply it with additional customizations (e.g. animations). You can only enable recipes through a configuration overlay (no vimscript).

::lua:: source (see here for additional params)

local Default = require('vimade.recipe.default').Default
require('vimade').setup(Default(animate=true))

::python:: source (see here for additional params)

from vimade import vimade
from vimade.recipe.default import Default
vimade.setup(**Default(animate=True))

Recipe: Minimalist

This recipe hides low value built-in highlights on inactive windows such as number column and end of buffer highlights. Greatly reduces visibility of WinSeparator on inactive windows.

::lua:: source (see here for additional params)

local Minimalist = require('vimade.recipe.minimalist').Minimalist
require('vimade').setup(Minimalist{animate = true})

::python:: source (see here for additional params)

NOTE: For vim users with wincolor, minimalist will link the no_visibility_highlights to Normal so that they can completely fade-out per-window.

from vimade import vimade
from vimade.recipe.minimalist import Minimalist
vimade.setup(**Minimalist(animate = True))

Commands
command description
VimadeEnable Enables Vimade. Not necessary to run unless you have explicitly disabled Vimade.
VimadeDisable Disable and remove all Vimade highlights.
VimadeToggle Toggle between enabled/disabled states.
VimadeRedraw Force vimade to recalculate and redraw every highlight.
VimadeInfo Provides debug information for Vimade. Please include this info in bug reports.
VimadeWinDisable Disables fading for the current window.
VimadeWinEnable Enables fading for the current window.
VimadeBufDisable Disables fading for the current buffer.
VimadeBufEnable Enables fading for the current buffer.
VimadeFadeActive Fades the current active window.
VimadeUnfadeActive Unfades the current active window.
VimadeOverrideFolded Overrides the Folded highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include Folded highlights that are distracting in faded windows.
VimadeOverrideSignColumn Overrides the SignColumn highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include SignColumn highlights that are distracting in faded windows.
VimadeOverrideLineNr Overrides the LineNr highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include LineNr highlights that are distracting in faded windows.
VimadeOverrideSplits Overrides the VertSplit highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include VertSplit highlights that are distracting in faded windows.
VimadeOverrideNonText Overrides the NonText highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include NonText highlights that are distracting in faded windows.
VimadeOverrideEndOfBuffer Overrides the EndOfBuffer highlight by creating a link to the Vimade base fade. This should produce acceptable results for colorschemes that include EndOfBuffer highlights that are distracting in faded windows.
VimadeOverrideAll Combines all VimadeOverride commands.
VimadeFadeLevel [0.0-1.0] Sets the FadeLevel config and forces an immediate redraw.
VimadeFadePriority [0+] Sets the FadePriority config and forces an immediate redraw.
FAQ/Help

Tmux is not working!

  • Vimade only works in a 256 or higher color mode and by default TMUX may set t_Co to 8. it is recommended that you set export TERM=xterm-256color before starting vim. You can also set set termguicolors inside vim if your term supports it for an even more accurate level of fading.

Comparison against other plugins

Many similar Neovim plugins have recently been created. I'm not aware of any feature that these plugins support that Vimade doesn't, so I'm going to keep this table limited to key differences. If you find a feature gap, please file an issue or contribute!

Feature Vimade Shade Tint Sunglasses
Fade buffers Yes
Fade windows Yes Yes Yes Yes
Group diffs Yes via function
Links Yes via function
Blocklist Yes via function Yes
Animations Yes
Recipes Yes
256 colors Yes
Per-window config (e.g. fadelevel, tint, etc) Yes
Cleared highlights Yes Yes
Supports Vim + All versions of Neovim Yes

Contributing

Feel free to open a PR or file issues for bugs and feature requests. All contributions are valued even its just a question! If you are looking for a place to share your own code and flavor in this plugin, recipes are a great starting place.

Thanks for reading!