Tabpage

Nvim :help pages, generated from source using the tree-sitter-vimdoc parser.

Editing with windows in multiple tabpages. tabpage

The commands which have been added to use multiple tabpages are explained here. Additionally, there are explanations for commands that work differently when used in combination with more than one tabpage.

1. Introduction tabpage-intro

A tabpage holds one or more windows. You can easily switch between tab pages, so that you have several collections of windows to work on different things.

Usually you will see a list of labels at the top of the Vim window, one for each tabpage. With the mouse you can click on the label to jump to that tab page. There are other ways to move between tabpages, see below.

Most commands work only in the current tabpage. That includes the CTRL-W commands, :windo, :all and :ball (when not using the :tab modifier). The commands that are aware of other tabpages than the current one are mentioned below.

Tabpages are also a nice way to edit a buffer temporarily without changing the current window layout. Open a new tabpage, do whatever you want to do and close the tabpage.

tab-ID tabid tabpageid Each tabpage has an unique identifier which will not change, even after rearranging tabs. nvim_get_current_tabpage() returns the tab-id and nvim_list_tabpages() lists tab-ids in the order they're displayed. tabpage-number
Tabpages are numbered from left to right starting at 1: this tab "number" is returned by tabpagenr(). Unlike the tab-id, the tab number may change when tabs are opened, closed, or rearranged. nvim_tabpage_get_number() converts a tab-id to a tab number.

2. Commands tabpage-commands

OPENING A NEW TABPAGE:

When starting Vim "vim -p filename ..." opens each file argument in a separate tabpage (up to 'tabpagemax'). See -p

A double click with the mouse in the non-GUI tabpages line opens a new, empty tabpage. It is placed left of the position of the click. The first click may select another tabpage first, causing an extra screen update.

This also works in a few GUI versions, esp. Win32. But only when clicking right of the labels.

In the GUI tabpages line you can use the right mouse button to open menu. tabline-menu.

For the related autocommands see tabnew-autocmd.

:[count]tabe[dit] :tabe :tabedit :tabnew :[count]tabnew Open a new tabpage with an empty window, after the current tabpage. If [count] is given the new tabpage appears after the tabpage [count] otherwise the new tabpage will appear after the current one.

:tabnew     " opens tabpage after the current one

:.tabnew    " as above

:+tabnew    " opens tabpage after the next tabpage

            " note: it is one further than :tabnew

:-tabnew    " opens tabpage before the current

:0tabnew    " opens tabpage before the first one

:$tabnew    " opens tabpage after the last one

:[count]tabe[dit] [++opt] [+cmd] {file} :[count]tabnew [++opt] [+cmd] {file} Open a new tabpage and edit {file}, like with :edit. For [count] see :tabnew above.

:[count]tabf[ind] [++opt] [+cmd] {file} :tabf :tabfind Open a new tabpage and edit {file} in 'path', like with :find. For [count] see :tabnew above.

:[count]tab {cmd} :tab
Execute {cmd} and when it opens a new window open a new tab page instead. Doesn't work for :diffsplit, :diffpatch, :execute and :normal. If [count] is given the new tabpage appears after the tab page [count] otherwise the new tabpage will appear after the current one. Examples:

:tab split	    " opens current buffer in new tabpage

:tab help gt    " opens tabpage with help for "gt"

:.tab help gt   " as above

:+tab help	    " opens tabpage with help after the next

                " tabpage

:-tab help	    " opens tabpage with help before the

                " current one

:0tab help	    " opens tabpage with help before the

                " first one

:$tab help	    " opens tabpage with help after the last

                " one

CTRL-W gf Open a new tabpage and edit the file name under the cursor. See CTRL-W_gf.

CTRL-W gF Open a new tabpage and edit the file name under the cursor and jump to the line number following the file name. See CTRL-W_gF.

CLOSING A TABPAGE:

Closing the last window of a tabpage closes the tabpage too, unless there is only one tabpage.

Using the mouse: If the tabpage line is displayed you can click in the "X" at the top right to close the current tabpage. A custom 'tabline' may show something else.

:tabc :tabclose :tabc[lose][!] Close current tabpage. This command fails when:

There is only one tabpage on the screen. E784

When 'hidden' is not set, [!] is not used, a buffer has changes, and there is no other window on this buffer. Changes to the buffer are not written and won't get lost, so this is a "safe" command.

:tabclose   " close the current tabpage

:{count}tabc[lose][!] :tabc[lose][!] {count} Close tabpage {count}. Fails in the same way as :tabclose above.

:-tabclose	    " close the previous tabpage

:+tabclose	    " close the next tabpage

:1tabclose	    " close the first tabpage

:$tabclose	    " close the last tabpage

:tabclose -2    " close the 2nd previous tabpage

:tabclose +	    " close the next tabpage

:tabclose 3	    " close the third tabpage

:tabclose $	    " close the last tabpage

:tabclose #     " close the last accessed tabpage

When a tabpage is closed the next tabpage will become the current one. This behaviour can be customized using the 'tabclose' option.

:tabo :tabonly :tabo[nly][!] Close all other tabpages. When the 'hidden' option is set, all buffers in closed windows become hidden. When 'hidden' is not set, and the 'autowrite' option is set, modified buffers are written. Otherwise, windows that have buffers that are modified are not removed, unless the [!] is given, then they become hidden. But modified buffers are never abandoned, so changes cannot get lost.

:tabonly " close all tabpages except the current one

:tabo[nly][!] {count} Close all tabpages except {count} one.

:.tabonly	    " as above

:-tabonly	    " close all tabpages except the previous

                " one

:+tabonly	    " close all tabpages except the next one

:1tabonly	    " close all tabpages except the first one

:$tabonly	    " close all tabpages except the last one

:tabonly -	    " close all tabpages except the previous

                " one

:tabonly +2     " close all tabpages except the two next

                " one

:tabonly 1	    " close all tabpages except the first one

:tabonly $	    " close all tabpages except the last one

:tabonly #	    " close all tabpages except the last

                " accessed one

SWITCHING TO ANOTHER TABPAGE:

Using the mouse: If the tabpage line is displayed you can click in a tabpage label to switch to that tabpage. Click where there is no label to go to the next tabpage. 'tabline'

:tabn[ext] :tabn :tabnext gt <C-PageDown> CTRL-<PageDown> <C-PageDown> gt i_CTRL-<PageDown> i_<C-PageDown> Go to the next tabpage. Wraps around from the last to the first one.

:{count}tabn[ext] :tabn[ext] {count} Go to tabpage {count}. The first tabpage has number one.

:-tabnext	" go to the previous tabpage

:+tabnext	" go to the next tabpage

:+2tabnext	" go to the two next tabpage

:1tabnext	" go to the first tabpage

:$tabnext	" go to the last tabpage

:tabnext $	" as above

:tabnext #	" go to the last accessed tabpage

:tabnext -	" go to the previous tabpage

:tabnext -1	" as above

:tabnext +	" go to the next tabpage

:tabnext +1	" as above

{count}<C-PageDown> {count}gt Go to tabpage {count}. The first tabpage has number one.

:tabp[revious] :tabp :tabprevious gT :tabN :tabN[ext] :tabNext CTRL-<PageUp> <C-PageUp> <C-PageUp> i_CTRL-<PageUp> i_<C-PageUp> gT Go to the previous tabpage. Wraps around from the first one to the last one.

:tabp[revious] {count} :tabN[ext] {count} {count}<C-PageUp> {count}gT Go {count} tabpages back. Wraps around from the first one to the last one. Note that the use of {count} is different from :tabnext, where it is used as the tabpage number.

:tabr[ewind] :tabfir :tabfirst :tabr :tabrewind :tabfir[st] Go to the first tabpage.

:tabl :tablast :tabl[ast] Go to the last tabpage.

<C-Tab> CTRL-<Tab> <C-Tab> g<Tab> g<Tab> CTRL-W_g<Tab> CTRL-W g<Tab> Go to the last accessed tabpage.

Other commands: :tabs
:tabs List the tabpages and the windows they contain. Shows a ">" for the current window. Shows a "+" for modified buffers. For example:

Tabpage 1

+ tabpage.txt

ex_docmd.c

Tabpage 2

> main.c

REORDERING TABPAGES:

:tabm[ove] [N] :tabm :tabmove :[N]tabm[ove] Move the current tabpage to after tabpage N. Use zero to make the current tabpage the first one. N is counted before the move, thus if the second tabpage is the current one, :tabmove 1 and :tabmove 2 have no effect. Without N the tabpage is made the last one.

:.tabmove	" do nothing

:-tabmove	" move the tabpage to the left

:+tabmove	" move the tabpage to the right

:0tabmove	" move the tabpage to the first

:tabmove 0	" as above

:tabmove	" move the tabpage to the last

:$tabmove	" as above

:tabmove $	" as above

:tabmove #	" move the tabpage after the last accessed

            " tabpage

:tabm[ove] +[N] :tabm[ove] -[N] Move the current tabpage N places to the right (with +) or to the left (with -).

:tabmove -	" move the tabpage to the left

:tabmove -1	" as above

:tabmove +	" move the tabpage to the right

:tabmove +1	" as above

Note that although it is possible to move a tabpage behind the N-th one by using :Ntabmove. And move it by N places by using :+Ntabmove. For clarification what +N means in this context see [range].

LOOPING OVER TABPAGES:

:tabd :tabdo :[range]tabd[o] {cmd} Execute {cmd} in each tabpage or, if [range] is given, only in tabpages which tabpage number is in the [range]. It works like doing this:

:tabfirst

:{cmd}

:tabnext

:{cmd}

etc.

This only operates in the current window of each tabpage. When an error is detected on one tabpage, further tabpages will not be visited. The last tabpage (or where an error occurred) becomes the current tabpage. {cmd} can contain '|' to concatenate several commands. {cmd} must not open or close tabpages or reorder them. Also see :windo, :argdo, :bufdo, :cdo, :ldo, :cfdo and :lfdo.

3. Other items tabpage-other

The GUI tabpages line has a popup menu. It is accessed with a right click. The entries are: Close Close the tabpage under the mouse pointer. The current one if there is no label under the mouse pointer. New Tab Open a tabpage, editing an empty buffer. It appears to the left of the mouse pointer. Open Tab... Like "New Tab" and additionally use a file selector to select a file to edit.

Diff mode works per tabpage. You can see the diffs between several files within one tabpage. Other tabpages can show differences between other files.

Variables local to a tabpage start with "t:". tabpage-variable

Currently there is only one option local to a tabpage: 'cmdheight'.

tabnew-autocmd
The TabLeave and TabEnter autocommand events can be used to do something when switching from one tabpage to another. The exact order depends on what you are doing. When creating a new tabpage this works as if you create a new window on the same buffer and then edit another buffer. Thus ":tabnew" triggers: WinLeave leave current window TabLeave leave current tabpage WinEnter enter window in new tabpage TabEnter enter new tabpage BufLeave leave current buffer BufEnter enter new empty buffer

When switching to another tabpage the order is: BufLeave WinLeave TabLeave WinEnter TabEnter BufEnter

When entering a new tabpage (:tabnew), TabNew is triggered before TabEnter and after WinEnter.

4. Setting 'tabline' setting-tabline

The 'tabline' option specifies what the line with tabpages labels looks like. It is only used when there is no GUI tab line.

You can use the 'showtabline' option to specify when you want the line with tabpage labels to appear: never, when there is more than one tabpage or always.

The highlighting of the tabpages line is set with the groups TabLine TabLineSel and TabLineFill. hl-TabLine hl-TabLineSel hl-TabLineFill

A "+" will be shown for a tabpage that has a modified window. The number of windows in a tabpage is also shown. Thus "3+" means three windows and one of them has a modified buffer.

The 'tabline' option allows you to define your preferred way to tabpages labels. This isn't easy, thus an example will be given here.

For basics see the 'statusline' option. The same items can be used in the 'tabline' option. Additionally, the tabpagebuflist(), tabpagenr() and tabpagewinnr() functions are useful.

Since the number of tab labels will vary, you need to use an expression for the whole option. Something like:

:set tabline=%!MyTabLine()

Then define the MyTabLine() function to list all the tabpages labels. A convenient method is to split it in two parts: First go over all the tab pages and define labels for them. Then get the label for each tabpage.


function MyTabLine()

  let s = ''

  for i in range(tabpagenr('$'))

    " select the highlighting

    if i + 1 == tabpagenr()

      let s ..= '%#TabLineSel#'

    else

      let s ..= '%#TabLine#'

    endif



    " set the tabpage number (for mouse clicks)

    let s ..= '%' .. (i + 1) .. 'T'



    " the label is made by MyTabLabel()

    let s ..= ' %{MyTabLabel(' .. (i + 1) .. ')} '

  endfor



  " after the last tabpage fill with TabLineFill and reset tabpage nr

  let s ..= '%#TabLineFill#%T'



  " right-align the label to close the current tabpage

  if tabpagenr('$') > 1

    let s ..= '%=%#TabLine#%999Xclose'

  endif



  return s

endfunction

Now the MyTabLabel() function is called for each tabpage to get its label.


function MyTabLabel(n)

  let buflist = tabpagebuflist(a:n)

  let winnr = tabpagewinnr(a:n)

  return bufname(buflist[winnr - 1])

endfunction

This is just a simplistic example that results in a tabpages line that resembles the default, but without adding a + for a modified buffer or truncating the names. You will want to reduce the width of labels in a clever way when there is not enough room. Check the 'columns' option for the space available.

5. Setting 'guitablabel' setting-guitablabel

When the GUI tabpages line is displayed, 'guitablabel' can be used to specify the label to display for each tabpage. Unlike 'tabline', which specifies the whole tabpages line at once, 'guitablabel' is used for each label separately.

'guitabtooltip' is very similar and is used for the tooltip of the same label. This only appears when the mouse pointer hovers over the label, thus it usually is longer. Only supported on some systems though.

See the 'statusline' option for the format of the value.

The "%N" item can be used for the current tabpage number. The v:lnum variable is also set to this number when the option is evaluated. The items that use a file name refer to the current window of the tabpage.

Note that syntax highlighting is not used for the option. The %T and %X items are also ignored.

A simple example that puts the tabpage number and the buffer name in the label:

:set guitablabel=%N\ %f

An example that resembles the default 'guitablabel': Show the number of windows in the tabpage and a '+' if there is a modified buffer:


function GuiTabLabel()

  let label = ''

  let bufnrlist = tabpagebuflist(v:lnum)



  " Add '+' if one of the buffers in the tabpage is modified

  for bufnr in bufnrlist

    if getbufvar(bufnr, "&modified")

      let label = '+'

      break

    endif

  endfor



  " Append the number of windows in the tabpage if more than one

  let wincount = tabpagewinnr(v:lnum, '$')

  if wincount > 1

    let label ..= wincount

  endif

  if label != ''

    let label ..= ' '

  endif



  " Append the buffer name

  return label .. bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])

endfunction



set guitablabel=%{GuiTabLabel()}

Note that the function must be defined before setting the option, otherwise you get an error message for the function not being known.

If you want to fall back to the default label, return an empty string.

If you want to show something specific for a tabpage, you might want to use a tabpage local variable. t:var