mini-tabline.txt

*mini.tabline* Tabline
*MiniTabline*

MIT License Copyright (c) 2021 Evgeni Chasnovski

==============================================================================

Key idea: show all listed buffers in readable way with minimal total width.

Features:
- Buffers are listed in the order of their identifier (see |bufnr()|).

- Different highlight groups for "states" of buffer affecting 'buffer tabs'.

- Buffer names are made unique by extending paths to files or appending
  unique identifier to buffers without name.

- Current buffer is displayed "optimally centered" (in center of screen
  while maximizing the total number of buffers shown) when there are many
  buffers open.

- 'Buffer tabs' are clickable if Neovim allows it.

- Extra information section in case of multiple Neovim tabpages.

- Truncation symbols which show if there are tabs to the left and/or right.
  Exact characters are taken from 'listchars' global value (`precedes` and
  `extends` fields) and are shown only if 'list' option is enabled.

What it doesn't do:
- Custom buffer order is not supported.

# Dependencies ~

Suggested dependencies (provide extra functionality, will work without them):

- Enabled |MiniIcons| module to show icons near file names.
  Falls back to using 'nvim-tree/nvim-web-devicons' plugin or shows nothing.

# Setup ~

This module needs a setup with `require('mini.tabline').setup({})`
(replace `{}` with your `config` table). It will create global Lua table
`MiniTabline` which you can use for scripting or manually (with
`:lua MiniTabline.*`).

See |MiniTabline.config| for `config` structure and default values.

You can override runtime config settings locally to buffer inside
`vim.b.minitabline_config` which should have same structure as
`MiniTabline.config`. See |mini.nvim-buffer-local-config| for more details.

# Suggested option values ~

Some options are set automatically by |MiniTabline.setup()|:
- 'showtabline' is set to 2 to always show tabline.

# Highlight groups ~

* `MiniTablineCurrent` - buffer is current (has cursor in it).
* `MiniTablineVisible` - buffer is visible (displayed in some window).
* `MiniTablineHidden` - buffer is hidden (not displayed).
* `MiniTablineModifiedCurrent` - buffer is modified and current.
* `MiniTablineModifiedVisible` - buffer is modified and visible.
* `MiniTablineModifiedHidden` - buffer is modified and hidden.
* `MiniTablineFill` - unused right space of tabline.
* `MiniTablineTabpagesection` - section with tabpage information.
* `MiniTablineTrunc` - truncation symbols indicating more left/right tabs.

To change any highlight group, modify it directly with |:highlight|.

# Disabling ~

To disable (show empty tabline), set `vim.g.minitabline_disable` (globally) or
`vim.b.minitabline_disable` (for a buffer) to `true`. Considering high number
of different scenarios and customization intentions, writing exact rules
for disabling module's functionality is left to user. See
|mini.nvim-disabling-recipes| for common recipes.

------------------------------------------------------------------------------
                                                           *MiniTabline.setup()*
                         `MiniTabline.setup`({config})
Module setup

Parameters ~
{config} `(table|nil)` Module config table. See |MiniTabline.config|.

Usage ~
>lua
  require('mini.tabline').setup() -- use default config
  -- OR
  require('mini.tabline').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
                                                            *MiniTabline.config*
                              `MiniTabline.config`
Module config

Default values:
>lua
  MiniTabline.config = {
    -- Whether to show file icons (requires 'mini.icons')
    show_icons = true,

    -- Function which formats the tab label
    -- By default surrounds with space and possibly prepends with icon
    format = nil,

    -- Where to show tabpage section in case of multiple vim tabpages.
    -- One of 'left', 'right', 'none'.
    tabpage_section = 'left',
  }
<
# Format ~

`config.format` is a callable that takes buffer identifier and pre-computed
label as arguments and returns a string with formatted label. Output will be
treated strictly as text (i.e. no 'statusline' like constructs is allowed).
This function will be called for all displayable in tabline buffers.
Default: |MiniTabline.default_format()|.

Example of adding "+" suffix for modified buffers: >lua

  function(buf_id, label)
    local suffix = vim.bo[buf_id].modified and '+ ' or ''
    return MiniTabline.default_format(buf_id, label) .. suffix
  end
<
------------------------------------------------------------------------------
                                             *MiniTabline.make_tabline_string()*
                      `MiniTabline.make_tabline_string`()
Make string for |tabline|

------------------------------------------------------------------------------
                                                  *MiniTabline.default_format()*
                `MiniTabline.default_format`({buf_id}, {label})
Default tab format

Used by default as `config.format`.
Prepends label with padded icon based on buffer's name (if `show_icon`
in |MiniTabline.config| is `true`) and surrounds label with single space.
Note: it is meant to be used only as part of `format` in |MiniTabline.config|.

Parameters ~
{buf_id} `(number)` Buffer identifier.
{label} `(string)` Pre-computed label.

Return ~
`(string)` Formatted label.


 vim:tw=78:ts=8:noet:ft=help:norl: