*vem-tabline.txt* Plugin to display your buffers and tabs in the tabline.

                      Vem Tabline by Andrés Sopeña

==============================================================================
CONTENTS                                                           *vem-tabline*

        Description ........................... |vem-tabline-description|
        Buffer order .......................... |vem-tabline-buffer-order|
        Selecting buffers ..................... |vem-tabline-selecting-buffers|
        Deleting buffers ...................... |vem-tabline-deleting-buffers|
        Multiwindow mode ...................... |vem-tabline-multiwindow-mode|
        Colors ................................ |vem-tabline-colors|
        Filetype icons ........................ |vem-tabline-filetype-icons|
        Settings .............................. |vem-tabline-settings|
        Source ................................ |vem-tabline-source|

==============================================================================
DESCRIPTION                                            *vem-tabline-description*

Vem Tabline is a lightweight plugin that uses Vim's native tabline to display
your tabs and listed buffers at the top of the screen. Buffers are shown to
the left using their names and tabs are numbered and shown to the right. Eg:
>
    | buffer1 | buffer2* | buffer3 |                             | 1 | 2 | 3 |
<
Modified buffers are marked with '*' and identical buffer names are appended
the name of the first different directory names in their path:
>
    | foo | bar@dir1 | bar@dir2 |                                | 1 | 2 | 3 |
<
You can use the normal Vim commands to manage your buffers and tabs and the
tabline will be updated accordingly.

Note: Vem Tabline is a component of a bigger Vim configuration setup named Vem
(https://www.vem-editor.org). Hence the plugin name. In any case, Vem Tabline
can be used totally independently from the Vem project.

==============================================================================
BUFFER ORDER                                          *vem-tabline-buffer-order*

Vem Tabline allows you to change the order in which buffers are shown in each
tab. To do so, use the following <Plug> mappings:

    Move selected buffer to the left:  `<Plug>vem_move_buffer_left-`
    Move selected buffer to the right: `<Plug>vem_move_buffer_right-`

Vim doesn't support ordering buffers natively so if you use `:bnext` and
`:bprev`, they will not follow the order of buffers in the tabline if you have
modified it. To avoid this problem you can use the following mappings:

    Select previous buffer in tabline: `<Plug>vem_prev_buffer-`
    Select next buffer in tabline:     `<Plug>vem_next_buffer-`

For example, you could set your mappings like:
>
    nmap <leader>h <Plug>vem_move_buffer_left-
    nmap <leader>l <Plug>vem_move_buffer_right-
    nmap <leader>p <Plug>vem_prev_buffer-
    nmap <leader>n <Plug>vem_next_buffer-
<
==============================================================================
SELECTING BUFFERS                                *vem-tabline-selecting-buffers*

As shown in |vem-tabline-buffer-order|, you can use the mappings:
>
    <Plug>vem_prev_buffer-
    <Plug>vem_next_buffer-
<
to select the next or previous buffer according to the order in which they
are displayed in the tabline.

With the variable `g:vem_tabline_show_number`, you can also display a number
next to the name of the buffer. If you set it to `'buffnr'`, the number of the
buffer will be displayed:
>
    | 3:file1.txt | 12:file2.txt | +1 more                       | 1 | 2 | 3 |
<
And you can switch to any buffer, using the `:buffer` command:
>
    :b12

If you set `g:vem_tabline_show_number` to `'index'`, then the displayed buffers
will show a sequential number starting with `1`:
>
    | 1:file1.txt | 2:file2.txt | +1 more                        | 1 | 2 | 3 |
>
In that case, you can use that number to switch to the buffer using the
provided command `VemTablineGo`:
>
    :VemTablineGo 2
<
Since the buffers are numered from 1 for the buffers that you see in the
tabline, you can define mappings to quickly jump to them:
>
    nmap <leader>1 :VemTablineGo 1<CR>
    nmap <leader>2 :VemTablineGo 2<CR>
    nmap <leader>3 :VemTablineGo 3<CR>
    nmap <leader>4 :VemTablineGo 4<CR>
    nmap <leader>5 :VemTablineGo 5<CR>
    nmap <leader>6 :VemTablineGo 6<CR>
    nmap <leader>7 :VemTablineGo 7<CR>
    nmap <leader>8 :VemTablineGo 8<CR>
    nmap <leader>9 :VemTablineGo 9<CR>
<
The command `VemTablineGo` is a bit verbose on purpose so it doesn't conflict
with commands that may already be defined in your Vim configuration. However,
if you prefer something shorter, you can create your own commmand with:
>
    command! -nargs=1 Go call VemTablineGo("<args>")
<
This will define a `Go` command that behaves exactly like `VemTablineGo`. You
can use any name of your liking here, but remember that Vim user commands must
start with uppercase.

==============================================================================
DELETING BUFFERS                                 *vem-tabline-deleting-buffers*

If you reorder the buffers in the tabline and then you delete one of them, Vim
will choose a new buffer to display instead. This will usually be the next
buffer in Vim's jump list and not necessarily the next one in the tabline. If
you delete several of them in a row, you don't really know which buffer will
be selected in the tabline and the resulting effect looks a bit random.

If you want to have the next buffer in the tabline to be selected when you
delete the current one, you can add something like this to your `vimrc`:
>
    function! DeleteCurrentBuffer() abort
        let current_buffer = bufnr('%')
        let next_buffer = vem_tabline#tabline.get_replacement_buffer()
        try
            exec 'confirm ' . current_buffer . 'bdelete'
            if next_buffer != 0
                exec next_buffer . 'buffer'
            endif
        catch /E516:/
           " If the operation is cancelled, do nothing
        endtry
    endfunction
    nmap <leader>x :call DeleteCurrentBuffer()<CR>
<
With this, you can press `<leader>x` (typically `\x`), and the current buffer
will be deleted, and the next one in the tabline selected. If the current
buffer has unsaved changes, you'll be prompted to confirm.

Of course, you can adapt the snippet to your needs (like using `bwipeout`
instead of `bdelete`) or choose a different key mapping.

==============================================================================
MULTIWINDOW MODE                                  *vem-tabline-multiwindow-mode*

In Vim, tabpages are used to arrange your windows in different layouts.
Buffers are shared across all tabpages and you can have different
visualization arrangements in each one.

Vem Tabline offers a mode to show only relevant buffers depending on the
layout of the current tabpage:

  * If there's only one window in the tab, all buffers are shown in the
    tabline.

  * If there's more than one window in the tab, only the displayed buffers
    are listed.

For example, if you have 3 buffers: `buffer1`, `buffer2`, `buffer3` and the
tab has two windows showing the first 2 then you will see:
>
    | buffer1 | buffer2 | +1 more                                | 1 | 2 | 3 |
>
However, if there's only one window you'll see the three of them.

This allows you to have a cleaner list of buffers depending on the tab that is
active and goes well with Vim's philosophy of using tabs as workspaces to
arrange windows in different configurations.

To enable this mode, set `g:vem_tabline_multiwindow_mode` to 1.


==============================================================================
COLORS                                                      *vem-tabline-colors*

Vem Tabline uses the default colors of your color scheme for rendering the
tabline. However you may change them using the following highlighting groups:

    Highlighting Group          Default        Meaning~
    *VemTablineNormal*            |TabLine|        Non-selected buffers
    *VemTablineLocation*          |TabLine|        Directory name (when present)
    *VemTablineNumber*            |TabLine|        Buffer number (when present)
    *VemTablineSelected*          |TabLineSel|     Currently selected buffer
    *VemTablineLocationSelected*  |TabLineSel|     Directory name (when present)
    *VemTablineNumberSelected*    |TabLineSel|     Buffer number (when present)
    *VemTablineShown*             |TabLine|        Buffer displayed in window
    *VemTablineLocationShown*     |TabLine|        Directory name (when present)
    *VemTablineNumberShown*       |TabLine|        Directory name (when present)
    *VemTablineSeparator*         |TabLineFill|    '+X more' text
    *VemTablinePartialName*       |TabLine|        Partially shown buffer
    *VemTablineTabSelected*       |TabLineSel|     Selected tab
    *VemTablineTabNormal*         |TabLineFill|    Non selected tab

For example, to set the selected buffer background to blue in the gui
version of Vim, you could do something like:
>
    highlight VemTablineSelected guifg=White guibg=DarkBlue gui=bold
<
And this is a complete example for a grey colored tabline:
>
    highlight VemTablineNormal           term=reverse cterm=none ctermfg=0   ctermbg=251 guifg=#242424 guibg=#cdcdcd gui=none
    highlight VemTablineLocation         term=reverse cterm=none ctermfg=239 ctermbg=251 guifg=#666666 guibg=#cdcdcd gui=none
    highlight VemTablineNumber           term=reverse cterm=none ctermfg=239 ctermbg=251 guifg=#666666 guibg=#cdcdcd gui=none
    highlight VemTablineSelected         term=bold    cterm=bold ctermfg=0   ctermbg=255 guifg=#242424 guibg=#ffffff gui=bold
    highlight VemTablineLocationSelected term=bold    cterm=none ctermfg=239 ctermbg=255 guifg=#666666 guibg=#ffffff gui=bold
    highlight VemTablineNumberSelected   term=bold    cterm=none ctermfg=239 ctermbg=255 guifg=#666666 guibg=#ffffff gui=bold
    highlight VemTablineShown            term=reverse cterm=none ctermfg=0   ctermbg=251 guifg=#242424 guibg=#cdcdcd gui=none
    highlight VemTablineLocationShown    term=reverse cterm=none ctermfg=0   ctermbg=251 guifg=#666666 guibg=#cdcdcd gui=none
    highlight VemTablineNumberShown      term=reverse cterm=none ctermfg=0   ctermbg=251 guifg=#666666 guibg=#cdcdcd gui=none
    highlight VemTablineSeparator        term=reverse cterm=none ctermfg=246 ctermbg=251 guifg=#888888 guibg=#cdcdcd gui=none
    highlight VemTablinePartialName      term=reverse cterm=none ctermfg=246 ctermbg=251 guifg=#888888 guibg=#cdcdcd gui=none
    highlight VemTablineTabNormal        term=reverse cterm=none ctermfg=0   ctermbg=251 guifg=#242424 guibg=#4a4a4a gui=none
    highlight VemTablineTabSelected      term=bold    cterm=bold ctermfg=0   ctermbg=255 guifg=#242424 guibg=#ffffff gui=bold
<
==============================================================================
FILETYPE ICONS                                      *vem-tabline-filetype-icons*

Vem Tabline integrates with the vim-devicons plugin to show, next to each
filename, an icon that displays its file type.

You can get vim-devicons at:

https://github.com/ryanoasis/vim-devicons

By default, once the plugin is installed, the file type icons will be
displayed automatically. To prevent that behavior can add this to your |vimrc|
file:
>
    let g:vem_tabline_show_icon = 0
<
==============================================================================
SETTINGS                                                  *vem-tabline-settings*

You can set these variables to configure Vem Tabline in your |vimrc| file:

*g:vem_tabline_show*                boolean (default: 1)

    The value of this option specifies how the tabline will be shown:

        0: never shown
        1: shown when there's more than one tab or buffer open
        2: always shown

    Vim option `showtabline` takes these same values but only checks the
    number of tabs and ignores the number of buffers when it is set to 1.
    Please, use `g:vem_tabline_show` instead of `showtabline` since the plugin
    will override the value of the option to fix this behavior.

*g:vem_tabline_multiwindow_mode*    boolean (default: 0)

    When this mode is active, for layouts of multiple windows in the tabpage,
    only the buffers that are displayed in those windows are listed in the
    tabline. That only applies to multi-window layouts, if there is only one
    window in the tabpage, all buffers are listed.

    If this mode is set to 0, all buffers are listed in the tabline regardless
    of the window layout.

*g:vem_tabline_show_number*         string (default: none)

    Show a number in front of each buffer. The possible values are:

        none: no number is shown
        buffnr: Vim's buffer number is shown
        index: displayed buffers are numbered sequentially starting from 1

    See |vem-tabline-selecting-buffers| for more info.

*g:vem_tabline_show_icon*         boolean (default: 1)

    Show an icon next to each buffer displaying its file type.

    It requires the vim-devicons plugin to be installed.

    See |vem-tabline-filetype-icons| for more info.

*g:vem_tabline_number_symbol*     string (default: :)

    Symbol to use to separate a buffer number from the buffer name (eg.
    `1:my-file.txt`). Only shown if `g:vem_tabline_show_number` is not 'none'.

*g:vem_tabline_location_symbol*     string (default: @)

    Symbol to use to separate a buffer name from the directory name (eg.
    `buffername@directory`). Only shown in buffers with identical names.

*g:vem_tabline_left_arrow*          string (default: < in terminal, ◀ in gui)

    Symbol to use when there are more buffers to the left of the tabline than
    the ones that fit in it.

*g:vem_tabline_right_arrow*         string (default: > in terminal, ▶ in gui)

    Symbol to use when there are more buffers to the right of the tabline than
    the ones that fit in it.

*g:vem_unnamed_buffer_label*        string (default: [No Name])

    Label to use for new, unnamed buffers that are not associated to a file
    yet.

==============================================================================
SOURCE                                                      *vem-tabline-source*

https://github.com/pacha/vem-tabline

vim:tw=78:et:ft=help:norl: