Custimized Handlers

Custimized Handlers

This page guides you on how to add customized handlers to the Neominimap plugin. Handlers allow you to define how specific types of annotations (like TODO comments or diagnostic signs) are displayed on the minimap.

Handler Structure

A handler is defined by the Neominimap.Map.Handler class, which includes several fields:

• name: A string that identifies the handler.
• mode: Defines how the annotations are displayed (icon, sign, background highlight...).
• namespace: Either an integer or string representing the namespace in which the handler operates.
• autocmds: A list of autocommands that trigger the handler’s behavior. Each autocmd includes:
  • event: The Vim event(s) that trigger the autocmd.
  • opts: Optional settings for the autocmd, including a callback function that applies the handler. Note that the callback function takes an additional argument called apply. This function is for applying the handler to a specific buffer. See the following example.
• init: A function that initializes the handler.
• get_annotations: A function that retrieves a list of annotations for a given buffer.

the get_annotations function returns a list of annotations, each defined by the Neominimap.Map.Handler.Annotation type. This type includes the following fields:

• lnum: The starting line number (1-based index).
• end_lnum: The ending line number (1-based index).
• id: A unique identifier for the annotation within a single handler.
• priority: The priority level for displaying the annotation.
• icon: (Optional) An icon associated with the annotation. Useful when mode is icon.
• highlight: The highlight group for rendering the annotation.

Example Handler

Here’s an example of a handler that integrates with todo-comments.nvim:

---@type Neominimap.Map.Handler
local extmark_handler = {
    name = "Todo Comment",
    mode = "icon",
    namespace = vim.api.nvim_create_namespace("neominimap_todo_comment"),
    init = function() end,
    autocmds = {
        {
            event = { "TextChanged", "TextChangedI" },
            opts = {
                callback = function(apply, args)
                    local bufnr = tonumber(args.buf) ---@cast bufnr integer
                    vim.schedule(function()
                        apply(bufnr)
                    end)
                end,
            },
        },
        {
            event = "WinScrolled",
            opts = {
                callback = function(apply)
                    local winid = vim.api.nvim_get_current_win()
                    if not winid or not vim.api.nvim_win_is_valid(winid) then
                        return
                    end
                    local bufnr = vim.api.nvim_win_get_buf(winid)
                    vim.schedule(function()
                        if bufnr and vim.api.nvim_buf_is_valid(bufnr) then
                            apply(bufnr)
                        end
                    end)
                end,
            },
        },
    },
    get_annotations = function(bufnr)
        local ok, _ = pcall(require, "todo-comments")
        if not ok then
            return {}
        end
        local ns_id = vim.api.nvim_get_namespaces()["todo-comments"]
        local extmarks = vim.api.nvim_buf_get_extmarks(bufnr, ns_id, 0, -1, {
            details = true,
        })
        local icons = {
            FIX = " ",
            TODO = " ",
            HACK = " ",
            WARN = " ",
            PERF = " ",
            NOTE = " ",
            TEST = "⏲ ",
        }
        local id = { FIX = 1, TODO = 2, HACK = 3, WARN = 4, PERF = 5, NOTE = 6, TEST = 7 }
        return vim.tbl_map(function(extmark) ---@param extmark vim.api.keyset.get_extmark_item
            local detail = extmark[4] ---@type vim.api.keyset.extmark_details
            local group = detail.hl_group ---@type string
            local kind = string.sub(group, 7)
            local icon = icons[kind]
            ---@type Neominimap.Map.Handler.Annotation
            return {
                lnum = extmark[2],
                end_lnum = extmark[2],
                id = id[kind],
                highlight = "TodoFg" .. kind, --- You can customize the highlight here.
                icon = icon,
                priority = detail.priority,
            }
        end, extmarks)
    end,
}

vim.g.neominimap = {
    handlers = {
        extmark_handler,
    }
}

Here is an overview

For more exapmles, checkout the built-in handlers in source code.