tabpage.txt For Vim version 7.4. Last change: 2014 Nov 27LINK

VIM REFERENCE MANUAL by Bram Moolenaar

Editing with windows in multiple tab pages. tab-page tabpageLINK

The commands which have been added to use multiple tab pages are explained

here. Additionally, there are explanations for commands that work differently

when used in combination with more than one tab page.

1. Introduction tab-page-intro

2. Commands tab-page-commands

3. Other items tab-page-other

4. Setting 'tabline' setting-tabline

5. Setting 'guitablabel' setting-guitablabel

{Vi does not have any of these commands}

{not able to use multiple tab pages when the +windows feature was disabled

at compile time}

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

1. Introduction tab-page-introLINK

A tab page 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 tab page. With the mouse you can click on the label to jump to that tab

page. There are other ways to move between tab pages, see below.

Most commands work only in the current tab page. That includes the CTRL-W

commands, :windo, :all and :ball (when not using the :tab modifier).

The commands that are aware of other tab pages than the current one are

mentioned below.

Tabs are also a nice way to edit a buffer temporarily without changing the

current window layout. Open a new tab page, do whatever you want to do and

close the tab page.

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

2. Commands tab-page-commandsLINK

OPENING A NEW TAB PAGE:

When starting Vim "vim -p filename ..." opens each file argument in a separate

tab page (up to 'tabpagemax'). See -p

A double click with the mouse in the non-GUI tab pages line opens a new, empty

tab page. It is placed left of the position of the click. The first click

may select another tab page first, causing an extra screen update.

This also works in a few GUI versions, esp. Win32 and Motif. But only when

clicking right of the labels.

In the GUI tab pages line you can use the right mouse button to open menu.

tabline-menu.

:[count]tabe[dit] :tabe :tabedit :tabnewLINK

:[count]tabnew

Open a new tab page with an empty window, after the current

tab page. If [count] is given the new tab page appears after

the tab page [count] otherwise the new tab page will appear

after the current one.

:tabnew " opens tabpage after the current one

:.tabnew " as above

:+tabnew " opens tabpage after the next tab page

" note: it is one further than :tabnew

:-tabnew " opens tabpage before the current one

: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 tab page and edit {file}, like with :edit.

For [count] see :tabnew above.

:[count]tabf[ind] [++opt] [+cmd] {file} :tabf :tabfindLINK

Open a new tab page and edit {file} in 'path', like with

:find. For [count] see :tabnew above.

{not available when the +file_in_path feature was disabled

at compile time}

:[count]tab {cmd} :tabLINK

Execute {cmd} and when it opens a new window open a new tab

page instead. Doesn't work for :diffsplit, :diffpatch,

:execute and :normal.

When [count] is omitted the tab page appears after the current

one.

When [count] is specified the new tab page comes after tab

page [count]. Use ":0tab cmd" to get the new tab page as the

first one.

Examples:

:tab split " opens current buffer in new tab page

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

CTRL-W gf Open a new tab page and edit the file name under the cursor.

See CTRL-W_gf.

CTRL-W gF Open a new tab page and edit the file name under the cursor

and jump to the line number following the file name.

See CTRL-W_gF.

CLOSING A TAB PAGE:

Closing the last window of a tab page closes the tab page too, unless there is

only one tab page.

Using the mouse: If the tab page line is displayed you can click in the "X" at

the top right to close the current tab page. A custom 'tabline' may show

something else.

:tabc :tabcloseLINK

:tabc[lose][!] Close current tab page.

This command fails when:

- There is only one tab page on the screen. E784LINK

- 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 tab page

:{count}tabc[lose][!]

:tabc[lose][!] {count}

Close tab page {count}. Fails in the same way as :tabclose

above.

:-tabclose " close the previous tab page

:+tabclose " close the next tab page

:1tabclose " close the first tab page

:$tabclose " close the last tab page

:tabo :tabonlyLINK

:tabo[nly][!] Close all other tab pages.

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 tab pages except the current

:{count}tabo[nly][!]

Close all tab pages except the {count}th one.

:.tabonly " one

:-tabonly " close all tab pages except the previous

" one

:+tabonly " close all tab pages except the next one

:1tabonly " close all tab pages except the first one

:$tabonly " close all tab pages except the last one

SWITCHING TO ANOTHER TAB PAGE:

Using the mouse: If the tab page line is displayed you can click in a tab page

label to switch to that tab page. Click where there is no label to go to the

next tab page. 'tabline'

:tabn[ext] :tabn :tabnext gtLINK

<C-PageDown> CTRL-<PageDown> <C-PageDown>LINK

gt i_CTRL-<PageDown> i_<C-PageDown>LINK

Go to the next tab page. Wraps around from the last to the

first one.

:tabn[ext] {count}

{count}<C-PageDown>

{count}gt Go to tab page {count}. The first tab page has number one.

:tabp[revious] :tabp :tabprevious gT :tabNLINK

:tabN[ext] :tabNext CTRL-<PageUp>LINK

<C-PageUp> <C-PageUp> i_CTRL-<PageUp> i_<C-PageUp>LINK

gT Go to the previous tab page. Wraps around from the first one

to the last one.

:tabp[revious] {count}

:tabN[ext] {count}

{count}<C-PageUp>

{count}gT Go {count} tab pages back. Wraps around from the first one

to the last one.

:tabr[ewind] :tabfir :tabfirst :tabr :tabrewindLINK

:tabfir[st] Go to the first tab page.

:tabl :tablastLINK

:tabl[ast] Go to the last tab page.

Other commands:

:tabsLINK

:tabs List the tab pages and the windows they contain.

Shows a ">" for the current window.

Shows a "+" for modified buffers.

REORDERING TAB PAGES:

:tabm[ove] [N] :tabm :tabmoveLINK

:[N]tabm[ove]

Move the current tab page to after tab page N. Use zero to

make the current tab page the first one. Without N the tab

page is made the last one.

:-tabmove " move the tab page to the left

:tabmove " move the tab page to the right

:.tabmove " as above

:+tabmove " as above

:0tabmove " move the tab page to the begining of the tab

" list

:$tabmove " move the tab page to the end of the tab list

:tabm[ove] +[N]

:tabm[ove] -[N]

Move the current tab page N places to the right (with +) or to

the left (with -).

Note that although it is possible to move a tab behind the N-th one by using

:Ntabmove, it is impossible to move it by N places by using :+Ntabmove. For

clarification what +N means in this context see [range].

LOOPING OVER TAB PAGES:

:tabd :tabdoLINK

:tabd[o] {cmd} Execute {cmd} in each tab page.

It works like doing this:

:tabfirst

:{cmd}

:tabnext

:{cmd}

etc.

This only operates in the current window of each tab page.

When an error is detected on one tab page, further tab pages

will not be visited.

The last tab page (or where an error occurred) becomes the

current tab page.

{cmd} can contain '|' to concatenate several commands.

{cmd} must not open or close tab pages or reorder them.

{not in Vi} {not available when compiled without the

+listcmds feature}

Also see :windo, :argdo and :bufdo.

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

3. Other items tab-page-otherLINK

tabline-menuLINK

The GUI tab pages line has a popup menu. It is accessed with a right click.

The entries are:

Close Close the tab page under the mouse pointer. The

current one if there is no label under the mouse

pointer.

New Tab Open a tab page, 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 tab page. You can see the diffs between several files

within one tab page. Other tab pages can show differences between other

files.

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

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

The TabLeave and TabEnter autocommand events can be used to do something when

switching from one tab page to another. The exact order depends on what you

are doing. When creating a new tab page 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 tab page

TabEnter enter new tab page

WinEnter enter window in new tab page

BufLeave leave current buffer

BufEnter enter new empty buffer

When switching to another tab page the order is:

BufLeave

WinLeave

TabLeave

TabEnter

WinEnter

BufEnter

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

4. Setting 'tabline' setting-tablineLINK

The 'tabline' option specifies what the line with tab pages 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

tab page labels to appear: never, when there is more than one tab page or

always.

The highlighting of the tab pages line is set with the groups TabLine

TabLineSel and TabLineFill. hl-TabLine hl-TabLineSel hl-TabLineFill

A "+" will be shown for a tab page 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 tab pages

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 tab pages 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 tab page.

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 tab page number (for mouse clicks)

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

" the label is made by MyTabLabel()

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

endfor

" after the last tab fill with TabLineFill and reset tab page nr

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

" right-align the label to close the current tab page

if tabpagenr('$') > 1

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

endif

return s

endfunction

Now the MyTabLabel() function is called for each tab page 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 tab pages 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-guitablabelLINK

When the GUI tab pages line is displayed, 'guitablabel' can be used to

specify the label to display for each tab page. Unlike 'tabline', which

specifies the whole tab pages 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 tab page 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 tab page.

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

items are also ignored.

A simple example that puts the tab page 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 tab page 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 tab page is modified

for bufnr in bufnrlist

if getbufvar(bufnr, "&modified")

let label = '+'

break

endif

endfor

" Append the number of windows in the tab page 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 tab page, you might want to use a

tab page local variable. t:var

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