1 *tabpage.txt* For Vim version 7.3. Last change: 2010 Jul 31
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Editing with windows in multiple tab pages. *tab-page* *tabpage*
9 The commands which have been added to use multiple tab pages are explained
10 here. Additionally, there are explanations for commands that work differently
11 when used in combination with more than one tab page.
13 1. Introduction |tab-page-intro|
14 2. Commands |tab-page-commands|
15 3. Other items |tab-page-other|
16 4. Setting 'tabline' |setting-tabline|
17 5. Setting 'guitablabel' |setting-guitablabel|
19 {Vi does not have any of these commands}
20 {not able to use multiple tab pages when the |+windows| feature was disabled
23 ==============================================================================
24 1. Introduction *tab-page-intro*
26 A tab page holds one or more windows. You can easily switch between tab
27 pages, so that you have several collections of windows to work on different
30 Usually you will see a list of labels at the top of the Vim window, one for
31 each tab page. With the mouse you can click on the label to jump to that tab
32 page. There are other ways to move between tab pages, see below.
34 Most commands work only in the current tab page. That includes the |CTRL-W|
35 commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier).
36 The commands that are aware of other tab pages than the current one are
39 Tabs are also a nice way to edit a buffer temporarily without changing the
40 current window layout. Open a new tab page, do whatever you want to do and
43 ==============================================================================
44 2. Commands *tab-page-commands*
46 OPENING A NEW TAB PAGE:
48 When starting Vim "vim -p filename ..." opens each file argument in a separate
49 tab page (up to 'tabpagemax'). See |-p|
51 A double click with the mouse in the non-GUI tab pages line opens a new, empty
52 tab page. It is placed left of the position of the click. The first click
53 may select another tab page first, causing an extra screen update.
55 This also works in a few GUI versions, esp. Win32 and Motif. But only when
56 clicking right of the labels.
58 In the GUI tab pages line you can use the right mouse button to open menu.
61 :[count]tabe[dit] *:tabe* *:tabedit* *:tabnew*
63 Open a new tab page with an empty window, after the current
64 tab page. For [count] see |:tab| below.
66 :[count]tabe[dit] [++opt] [+cmd] {file}
67 :[count]tabnew [++opt] [+cmd] {file}
68 Open a new tab page and edit {file}, like with |:edit|.
69 For [count] see |:tab| below.
71 :[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind*
72 Open a new tab page and edit {file} in 'path', like with
73 |:find|. For [count] see |:tab| below.
74 {not available when the |+file_in_path| feature was disabled
77 :[count]tab {cmd} *:tab*
78 Execute {cmd} and when it opens a new window open a new tab
79 page instead. Doesn't work for |:diffsplit|, |:diffpatch|,
80 |:execute| and |:normal|.
81 When [count] is omitted the tab page appears after the current
83 When [count] is specified the new tab page comes after tab
84 page [count]. Use ":0tab cmd" to get the new tab page as the
87 :tab split " opens current buffer in new tab page
88 :tab help gt " opens tab page with help for "gt"
90 CTRL-W gf Open a new tab page and edit the file name under the cursor.
93 CTRL-W gF Open a new tab page and edit the file name under the cursor
94 and jump to the line number following the file name.
99 Closing the last window of a tab page closes the tab page too, unless there is
102 Using the mouse: If the tab page line is displayed you can click in the "X" at
103 the top right to close the current tab page. A custom |'tabline'| may show
107 :tabc[lose][!] Close current tab page.
108 This command fails when:
109 - There is only one tab page on the screen. *E784*
110 - When 'hidden' is not set, [!] is not used, a buffer has
111 changes, and there is no other window on this buffer.
112 Changes to the buffer are not written and won't get lost, so
113 this is a "safe" command.
115 :tabc[lose][!] {count}
116 Close tab page {count}. Fails in the same way as ':tabclose"
120 :tabo[nly][!] Close all other tab pages.
121 When the 'hidden' option is set, all buffers in closed windows
123 When 'hidden' is not set, and the 'autowrite' option is set,
124 modified buffers are written. Otherwise, windows that have
125 buffers that are modified are not removed, unless the [!] is
126 given, then they become hidden. But modified buffers are
127 never abandoned, so changes cannot get lost.
130 SWITCHING TO ANOTHER TAB PAGE:
132 Using the mouse: If the tab page line is displayed you can click in a tab page
133 label to switch to that tab page. Click where there is no label to go to the
134 next tab page. |'tabline'|
136 :tabn[ext] *:tabn* *:tabnext* *gt*
137 <C-PageDown> *CTRL-<PageDown>* *<C-PageDown>*
138 gt *i_CTRL-<PageDown>* *i_<C-PageDown>*
139 Go to the next tab page. Wraps around from the last to the
144 {count}gt Go to tab page {count}. The first tab page has number one.
147 :tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN*
148 :tabN[ext] *:tabNext* *CTRL-<PageUp>*
149 <C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>*
150 gT Go to the previous tab page. Wraps around from the first one
153 :tabp[revious] {count}
156 {count}gT Go {count} tab pages back. Wraps around from the first one
159 :tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind*
160 :tabfir[st] Go to the first tab page.
163 :tabl[ast] Go to the last tab page.
168 :tabs List the tab pages and the windows they contain.
169 Shows a ">" for the current window.
170 Shows a "+" for modified buffers.
173 REORDERING TAB PAGES:
175 :tabm[ove] [N] *:tabm* *:tabmove*
176 Move the current tab page to after tab page N. Use zero to
177 make the current tab page the first one. Without N the tab
178 page is made the last one.
181 LOOPING OVER TAB PAGES:
184 :tabd[o] {cmd} Execute {cmd} in each tab page.
185 It works like doing this: >
191 < This only operates in the current window of each tab page.
192 When an error is detected on one tab page, further tab pages
194 The last tab page (or where an error occurred) becomes the
196 {cmd} can contain '|' to concatenate several commands.
197 {cmd} must not open or close tab pages or reorder them.
198 {not in Vi} {not available when compiled without the
200 Also see |:windo|, |:argdo| and |:bufdo|.
202 ==============================================================================
203 3. Other items *tab-page-other*
206 The GUI tab pages line has a popup menu. It is accessed with a right click.
208 Close Close the tab page under the mouse pointer. The
209 current one if there is no label under the mouse
211 New Tab Open a tab page, editing an empty buffer. It appears
212 to the left of the mouse pointer.
213 Open Tab... Like "New Tab" and additionally use a file selector to
214 select a file to edit.
216 Diff mode works per tab page. You can see the diffs between several files
217 within one tab page. Other tab pages can show differences between other
220 Variables local to a tab page start with "t:". |tabpage-variable|
222 Currently there is only one option local to a tab page: 'cmdheight'.
224 The TabLeave and TabEnter autocommand events can be used to do something when
225 switching from one tab page to another. The exact order depends on what you
226 are doing. When creating a new tab page this works as if you create a new
227 window on the same buffer and then edit another buffer. Thus ":tabnew"
229 WinLeave leave current window
230 TabLeave leave current tab page
231 TabEnter enter new tab page
232 WinEnter enter window in new tab page
233 BufLeave leave current buffer
234 BufEnter enter new empty buffer
236 When switching to another tab page the order is:
244 ==============================================================================
245 4. Setting 'tabline' *setting-tabline*
247 The 'tabline' option specifies what the line with tab pages labels looks like.
248 It is only used when there is no GUI tab line.
250 You can use the 'showtabline' option to specify when you want the line with
251 tab page labels to appear: never, when there is more than one tab page or
254 The highlighting of the tab pages line is set with the groups TabLine
255 TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
257 A "+" will be shown for a tab page that has a modified window. The number of
258 windows in a tabpage is also shown. Thus "3+" means three windows and one of
259 them has a modified buffer.
261 The 'tabline' option allows you to define your preferred way to tab pages
262 labels. This isn't easy, thus an example will be given here.
264 For basics see the 'statusline' option. The same items can be used in the
265 'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and
266 |tabpagewinnr()| functions are useful.
268 Since the number of tab labels will vary, you need to use an expression for
269 the whole option. Something like: >
270 :set tabline=%!MyTabLine()
272 Then define the MyTabLine() function to list all the tab pages labels. A
273 convenient method is to split it in two parts: First go over all the tab
274 pages and define labels for them. Then get the label for each tab page. >
278 for i in range(tabpagenr('$'))
279 " select the highlighting
280 if i + 1 == tabpagenr()
281 let s .= '%#TabLineSel#'
283 let s .= '%#TabLine#'
286 " set the tab page number (for mouse clicks)
287 let s .= '%' . (i + 1) . 'T'
289 " the label is made by MyTabLabel()
290 let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
293 " after the last tab fill with TabLineFill and reset tab page nr
294 let s .= '%#TabLineFill#%T'
296 " right-align the label to close the current tab page
297 if tabpagenr('$') > 1
298 let s .= '%=%#TabLine#%999Xclose'
304 Now the MyTabLabel() function is called for each tab page to get its label. >
306 function MyTabLabel(n)
307 let buflist = tabpagebuflist(a:n)
308 let winnr = tabpagewinnr(a:n)
309 return bufname(buflist[winnr - 1])
312 This is just a simplistic example that results in a tab pages line that
313 resembles the default, but without adding a + for a modified buffer or
314 truncating the names. You will want to reduce the width of labels in a
315 clever way when there is not enough room. Check the 'columns' option for the
318 ==============================================================================
319 5. Setting 'guitablabel' *setting-guitablabel*
321 When the GUI tab pages line is displayed, 'guitablabel' can be used to
322 specify the label to display for each tab page. Unlike 'tabline', which
323 specifies the whole tab pages line at once, 'guitablabel' is used for each
326 'guitabtooltip' is very similar and is used for the tooltip of the same label.
327 This only appears when the mouse pointer hovers over the label, thus it
328 usually is longer. Only supported on some systems though.
330 See the 'statusline' option for the format of the value.
332 The "%N" item can be used for the current tab page number. The |v:lnum|
333 variable is also set to this number when the option is evaluated.
334 The items that use a file name refer to the current window of the tab page.
336 Note that syntax highlighting is not used for the option. The %T and %X
337 items are also ignored.
339 A simple example that puts the tab page number and the buffer name in the
341 :set guitablabel=%N\ %f
343 An example that resembles the default 'guitablabel': Show the number of
344 windows in the tab page and a '+' if there is a modified buffer: >
346 function GuiTabLabel()
348 let bufnrlist = tabpagebuflist(v:lnum)
350 " Add '+' if one of the buffers in the tab page is modified
351 for bufnr in bufnrlist
352 if getbufvar(bufnr, "&modified")
358 " Append the number of windows in the tab page if more than one
359 let wincount = tabpagewinnr(v:lnum, '$')
361 let label .= wincount
367 " Append the buffer name
368 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])
371 set guitablabel=%{GuiTabLabel()}
373 Note that the function must be defined before setting the option, otherwise
374 you get an error message for the function not being known.
376 If you want to fall back to the default label, return an empty string.
378 If you want to show something specific for a tab page, you might want to use a
379 tab page local variable. |t:var|
382 vim:tw=78:ts=8:ft=help:norl: