*tabpage.txt*   Nvim


		  VIM REFERENCE MANUAL	  by Bram Moolenaar


Editing with windows in multiple tabpages.		*tab-page* *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.

                                      Type |gO| to see the table of contents.

==============================================================================
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*

							*tabline-menu*
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|


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