ui.kak

Toggle UI highlighters in Kakoune.

Installation

Add ui.kak to your autoload or source it manually.

What’s included

Commands to toggle various user interface highlighters and related hooks.

A ui user mode is defined with key mappings for all commands.

ui-line-numbers-toggle

Display line numbers.

ui-whitespaces-toggle

Display whitespaces.

ui-trailing-spaces-toggle

Display trailing spaces.

ui-wrap-toggle

Wrap lines to window width.

ui-matching-toggle

Display matching char.

ui-git-diff-toggle

Display git diff. When enabled, adds hooks for automatically updating git diff on BufWritePost and BufReload. Disabling removes the hooks.

ui-lint-toggle

Display lint diagnostics. When enabled, adds hooks for automatically updating lint diagnostics on BufWritePost and BufReload. Disabling removes the hooks.

ui-search-toggle

Dynamically display search matches using Search face. When enabled, adds hooks to highlight search matches on /,?,*,n and N keys. Pressing <esc> removes the highlights.

ui-todos-toggle

Display TODO, FIXME, XXX, NOTE in buffer using TodoComment face.

ui-cursorline-toggle

Display current cursor line using CursorLine face.

ui-cursorcolumn-toggle

Display current cursor column using CursorColumn face.

In addition to ui-*-toggle, each command is also available in the forms of ui-*-enable and ui-*-disable.

Configuration

The mode can be entered via a ui command. Alternatively, define a custom keymapping:

map global user -docstring "UI mode" u ': enter-user-mode ui<ret>'

Enabling commands on start

To enable commands by default when Kakoune starts, call them in a WinCreate hook, for example:

hook global WinCreate .* %{
    ui-line-numbers-toggle
    ui-cursorline-toggle
    ui-trailing-spaces-toggle
    ui-matching-toggle
    ui-search-toggle
}

Interacting with other plugins

If you need to do something whenever a highlighter is added or removed, you can call commands in the ui-hl-changed User hook.

As an example, to fix the placement of Scrollbar.kak's highlighter when toggling various highlighters with ui.kak, create a ui-hl-changed User hook:

hook global WinCreate .* %{
    ui-line-numbers-toggle
    scrollbar-enable

    # move scrollbar to left of stack whenever ui highlighters change
    hook window User ui-hl-changed %{ move-scrollbar-to-left }
}

Custom options

The following options can be changed customize the appearance of some highlighters.

Full list of applicable flags can be found here.

ui_line_numbers_flags

custom flags for ui-line-numbers-toggle

ui_whitespaces_flags

custom flags for ui-whitespaces-toggle

ui_wrap_flags

custom flags for ui-wrap-toggle

ui_todo_keywords_regex

custom regex for ui-todos-toggle, default: \b(TODO|FIXME|XXX|NOTE)\b

Example:

# make lines numbers relative, highlight current line and use empty space for separator
set-option global ui_line_numbers_flags -relative -hlcursor -separator " "

# wrap at 80 chars, at word boundaries and use "..." for marker
set-option global ui_wrap_flags -width 80 -word -marker ...

Custom faces

The following custom faces are used by some highlighters.

Search

face used by the ui-search-toggle command, default: +bu@MatchingChar

TrailingSpace

face used by the ui-whitespaces-toggle command, default: Error

TodoComment

face used by the ui-todos-toggle command, default: b@Information

CursorLine

face used by the ui-cursorline-toggle command, default: default,rgba:77777720

CursorColumn

face used by the ui-cursorcolumn-toggle command, default: default,rgba:77777720