blob: 2d44fe2ff53dcc4269eadb2bc7cf6814389f0ab0 [file] [log] [blame]
Bram Moolenaara162bc52015-01-07 16:54:21 +01001*tabpage.txt* For Vim version 7.4. Last change: 2015 Jan 04
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar2a0449d2006-02-20 21:27:21 +00007Editing with windows in multiple tab pages. *tab-page* *tabpage*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008
9The commands which have been added to use multiple tab pages are explained
10here. Additionally, there are explanations for commands that work differently
11when used in combination with more than one tab page.
12
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000131. Introduction |tab-page-intro|
142. Commands |tab-page-commands|
153. Other items |tab-page-other|
164. Setting 'tabline' |setting-tabline|
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000175. Setting 'guitablabel' |setting-guitablabel|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000018
19{Vi does not have any of these commands}
20{not able to use multiple tab pages when the |+windows| feature was disabled
21at compile time}
22
23==============================================================================
241. Introduction *tab-page-intro*
25
26A tab page holds one or more windows. You can easily switch between tab
27pages, so that you have several collections of windows to work on different
28things.
29
30Usually you will see a list of labels at the top of the Vim window, one for
31each tab page. With the mouse you can click on the label to jump to that tab
32page. There are other ways to move between tab pages, see below.
33
34Most commands work only in the current tab page. That includes the |CTRL-W|
Bram Moolenaare1438bb2006-03-01 22:01:55 +000035commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier).
36The commands that are aware of other tab pages than the current one are
37mentioned below.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000038
39Tabs are also a nice way to edit a buffer temporarily without changing the
40current window layout. Open a new tab page, do whatever you want to do and
41close the tab page.
42
43==============================================================================
442. Commands *tab-page-commands*
45
46OPENING A NEW TAB PAGE:
47
48When starting Vim "vim -p filename ..." opens each file argument in a separate
Bram Moolenaar58f0a1f2010-07-17 16:30:42 +020049tab page (up to 'tabpagemax'). See |-p|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000050
Bram Moolenaarbfb2d402006-03-03 22:50:42 +000051A double click with the mouse in the non-GUI tab pages line opens a new, empty
52tab page. It is placed left of the position of the click. The first click
53may select another tab page first, causing an extra screen update.
54
Bram Moolenaarf193fff2006-04-27 00:02:13 +000055This also works in a few GUI versions, esp. Win32 and Motif. But only when
56clicking right of the labels.
57
Bram Moolenaarbfb2d402006-03-03 22:50:42 +000058In the GUI tab pages line you can use the right mouse button to open menu.
59|tabline-menu|.
Bram Moolenaar80a94a52006-02-23 21:26:58 +000060
Bram Moolenaara26559b2010-07-31 14:59:19 +020061:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew*
62:[count]tabnew
63 Open a new tab page with an empty window, after the current
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010064 tab page. If [count] is given the new tab page appears after
65 the tab page [count] otherwise the new tab page will appear
66 after the current one. >
67 :tabnew " opens tabpage after the current one
68 :.tabnew " as above
69 :+tabnew " opens tabpage after the next tab page
70 " note: it is one further than :tabnew
71 :-tabnew " opens tabpage before the current one
72 :0tabnew " opens tabpage before the first one
73 :$tabnew " opens tabpage after the last one
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000074
Bram Moolenaara26559b2010-07-31 14:59:19 +020075:[count]tabe[dit] [++opt] [+cmd] {file}
76:[count]tabnew [++opt] [+cmd] {file}
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000077 Open a new tab page and edit {file}, like with |:edit|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010078 For [count] see |:tabnew| above.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000079
Bram Moolenaara26559b2010-07-31 14:59:19 +020080:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000081 Open a new tab page and edit {file} in 'path', like with
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010082 |:find|. For [count] see |:tabnew| above.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000083 {not available when the |+file_in_path| feature was disabled
84 at compile time}
85
Bram Moolenaar80a94a52006-02-23 21:26:58 +000086:[count]tab {cmd} *:tab*
87 Execute {cmd} and when it opens a new window open a new tab
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +000088 page instead. Doesn't work for |:diffsplit|, |:diffpatch|,
89 |:execute| and |:normal|.
Bram Moolenaar80a94a52006-02-23 21:26:58 +000090 When [count] is omitted the tab page appears after the current
Bram Moolenaara26559b2010-07-31 14:59:19 +020091 one.
92 When [count] is specified the new tab page comes after tab
93 page [count]. Use ":0tab cmd" to get the new tab page as the
94 first one.
95 Examples: >
Bram Moolenaar80a94a52006-02-23 21:26:58 +000096 :tab split " opens current buffer in new tab page
97 :tab help gt " opens tab page with help for "gt"
98
Bram Moolenaar8dff8182006-04-06 20:18:50 +000099CTRL-W gf Open a new tab page and edit the file name under the cursor.
100 See |CTRL-W_gf|.
101
Bram Moolenaar57657d82006-04-21 22:12:41 +0000102CTRL-W gF Open a new tab page and edit the file name under the cursor
103 and jump to the line number following the file name.
104 See |CTRL-W_gF|.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000105
106CLOSING A TAB PAGE:
107
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000108Closing the last window of a tab page closes the tab page too, unless there is
109only one tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000110
111Using the mouse: If the tab page line is displayed you can click in the "X" at
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000112the top right to close the current tab page. A custom |'tabline'| may show
113something else.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000114
115 *:tabc* *:tabclose*
116:tabc[lose][!] Close current tab page.
117 This command fails when:
118 - There is only one tab page on the screen. *E784*
119 - When 'hidden' is not set, [!] is not used, a buffer has
120 changes, and there is no other window on this buffer.
121 Changes to the buffer are not written and won't get lost, so
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100122 this is a "safe" command. >
123 :tabclose " close the current tab page
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000124
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100125:{count}tabc[lose][!]
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000126:tabc[lose][!] {count}
Bram Moolenaar9b451252012-08-15 17:43:31 +0200127 Close tab page {count}. Fails in the same way as `:tabclose`
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100128 above. >
129 :-tabclose " close the previous tab page
130 :+tabclose " close the next tab page
131 :1tabclose " close the first tab page
132 :$tabclose " close the last tab page
133<
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000134 *:tabo* *:tabonly*
135:tabo[nly][!] Close all other tab pages.
136 When the 'hidden' option is set, all buffers in closed windows
137 become hidden.
138 When 'hidden' is not set, and the 'autowrite' option is set,
139 modified buffers are written. Otherwise, windows that have
140 buffers that are modified are not removed, unless the [!] is
141 given, then they become hidden. But modified buffers are
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100142 never abandoned, so changes cannot get lost. >
143 :tabonly " close all tab pages except the current
144
145:{count}tabo[nly][!]
146 Close all tab pages except the {count}th one. >
147 :.tabonly " one
148 :-tabonly " close all tab pages except the previous
149 " one
150 :+tabonly " close all tab pages except the next one
151 :1tabonly " close all tab pages except the first one
152 :$tabonly " close all tab pages except the last one
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000153
154
155SWITCHING TO ANOTHER TAB PAGE:
156
157Using the mouse: If the tab page line is displayed you can click in a tab page
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000158label to switch to that tab page. Click where there is no label to go to the
159next tab page. |'tabline'|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000160
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000161:tabn[ext] *:tabn* *:tabnext* *gt*
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000162<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>*
163gt *i_CTRL-<PageDown>* *i_<C-PageDown>*
Bram Moolenaar7fc904b2006-04-13 20:37:35 +0000164 Go to the next tab page. Wraps around from the last to the
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000165 first one.
166
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000167:tabn[ext] {count}
168{count}<C-PageDown>
169{count}gt Go to tab page {count}. The first tab page has number one.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000170
171
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000172:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN*
173:tabN[ext] *:tabNext* *CTRL-<PageUp>*
174<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>*
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000175gT Go to the previous tab page. Wraps around from the first one
176 to the last one.
177
178:tabp[revious] {count}
179:tabN[ext] {count}
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000180{count}<C-PageUp>
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000181{count}gT Go {count} tab pages back. Wraps around from the first one
182 to the last one.
183
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000184:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind*
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000185:tabfir[st] Go to the first tab page.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000186
187 *:tabl* *:tablast*
188:tabl[ast] Go to the last tab page.
189
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000190
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000191Other commands:
192 *:tabs*
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000193:tabs List the tab pages and the windows they contain.
194 Shows a ">" for the current window.
195 Shows a "+" for modified buffers.
196
197
198REORDERING TAB PAGES:
199
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000200:tabm[ove] [N] *:tabm* *:tabmove*
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200201:[N]tabm[ove]
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000202 Move the current tab page to after tab page N. Use zero to
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000203 make the current tab page the first one. Without N the tab
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100204 page is made the last one. >
205 :-tabmove " move the tab page to the left
206 :tabmove " move the tab page to the right
207 :.tabmove " as above
208 :+tabmove " as above
Bram Moolenaara162bc52015-01-07 16:54:21 +0100209 :0tabmove " move the tab page to the beginning of the tab
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100210 " list
211 :$tabmove " move the tab page to the end of the tab list
212<
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000213
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200214:tabm[ove] +[N]
215:tabm[ove] -[N]
216 Move the current tab page N places to the right (with +) or to
217 the left (with -).
218
219Note that although it is possible to move a tab behind the N-th one by using
220:Ntabmove, it is impossible to move it by N places by using :+Ntabmove. For
221clarification what +N means in this context see |[range]|.
222
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000223
224LOOPING OVER TAB PAGES:
225
226 *:tabd* *:tabdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100227:[range]tabd[o] {cmd}
228 Execute {cmd} in each tab page or if [range] is given only in
229 tab pages which tab page number is in the [range]. It works
230 like doing this: >
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000231 :tabfirst
232 :{cmd}
233 :tabnext
234 :{cmd}
235 etc.
236< This only operates in the current window of each tab page.
237 When an error is detected on one tab page, further tab pages
238 will not be visited.
239 The last tab page (or where an error occurred) becomes the
240 current tab page.
241 {cmd} can contain '|' to concatenate several commands.
242 {cmd} must not open or close tab pages or reorder them.
243 {not in Vi} {not available when compiled without the
244 |+listcmds| feature}
245 Also see |:windo|, |:argdo| and |:bufdo|.
246
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000247==============================================================================
2483. Other items *tab-page-other*
249
Bram Moolenaarbfb2d402006-03-03 22:50:42 +0000250 *tabline-menu*
251The GUI tab pages line has a popup menu. It is accessed with a right click.
252The entries are:
253 Close Close the tab page under the mouse pointer. The
254 current one if there is no label under the mouse
255 pointer.
256 New Tab Open a tab page, editing an empty buffer. It appears
257 to the left of the mouse pointer.
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000258 Open Tab... Like "New Tab" and additionally use a file selector to
Bram Moolenaarbfb2d402006-03-03 22:50:42 +0000259 select a file to edit.
260
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000261Diff mode works per tab page. You can see the diffs between several files
262within one tab page. Other tab pages can show differences between other
263files.
264
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000265Variables local to a tab page start with "t:". |tabpage-variable|
266
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000267Currently there is only one option local to a tab page: 'cmdheight'.
268
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000269The TabLeave and TabEnter autocommand events can be used to do something when
270switching from one tab page to another. The exact order depends on what you
271are doing. When creating a new tab page this works as if you create a new
272window on the same buffer and then edit another buffer. Thus ":tabnew"
273triggers:
274 WinLeave leave current window
275 TabLeave leave current tab page
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000276 WinEnter enter window in new tab page
Bram Moolenaara162bc52015-01-07 16:54:21 +0100277 TabEnter enter new tab page
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000278 BufLeave leave current buffer
279 BufEnter enter new empty buffer
280
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000281When switching to another tab page the order is:
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000282 BufLeave
283 WinLeave
284 TabLeave
285 TabEnter
286 WinEnter
287 BufEnter
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000288
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000289==============================================================================
2904. Setting 'tabline' *setting-tabline*
291
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000292The 'tabline' option specifies what the line with tab pages labels looks like.
293It is only used when there is no GUI tab line.
294
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000295You can use the 'showtabline' option to specify when you want the line with
296tab page labels to appear: never, when there is more than one tab page or
297always.
298
299The highlighting of the tab pages line is set with the groups TabLine
300TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
301
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000302A "+" will be shown for a tab page that has a modified window. The number of
303windows in a tabpage is also shown. Thus "3+" means three windows and one of
304them has a modified buffer.
305
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000306The 'tabline' option allows you to define your preferred way to tab pages
307labels. This isn't easy, thus an example will be given here.
308
309For basics see the 'statusline' option. The same items can be used in the
310'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and
311|tabpagewinnr()| functions are useful.
312
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000313Since the number of tab labels will vary, you need to use an expression for
314the whole option. Something like: >
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000315 :set tabline=%!MyTabLine()
316
317Then define the MyTabLine() function to list all the tab pages labels. A
318convenient method is to split it in two parts: First go over all the tab
319pages and define labels for them. Then get the label for each tab page. >
320
321 function MyTabLine()
322 let s = ''
323 for i in range(tabpagenr('$'))
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000324 " select the highlighting
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000325 if i + 1 == tabpagenr()
326 let s .= '%#TabLineSel#'
327 else
328 let s .= '%#TabLine#'
329 endif
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000330
331 " set the tab page number (for mouse clicks)
332 let s .= '%' . (i + 1) . 'T'
333
334 " the label is made by MyTabLabel()
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000335 let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
336 endfor
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000337
338 " after the last tab fill with TabLineFill and reset tab page nr
339 let s .= '%#TabLineFill#%T'
340
341 " right-align the label to close the current tab page
342 if tabpagenr('$') > 1
343 let s .= '%=%#TabLine#%999Xclose'
344 endif
345
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000346 return s
347 endfunction
348
349Now the MyTabLabel() function is called for each tab page to get its label. >
350
351 function MyTabLabel(n)
352 let buflist = tabpagebuflist(a:n)
353 let winnr = tabpagewinnr(a:n)
354 return bufname(buflist[winnr - 1])
355 endfunction
356
357This is just a simplistic example that results in a tab pages line that
358resembles the default, but without adding a + for a modified buffer or
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000359truncating the names. You will want to reduce the width of labels in a
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000360clever way when there is not enough room. Check the 'columns' option for the
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000361space available.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000362
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000363==============================================================================
3645. Setting 'guitablabel' *setting-guitablabel*
365
366When the GUI tab pages line is displayed, 'guitablabel' can be used to
367specify the label to display for each tab page. Unlike 'tabline', which
368specifies the whole tab pages line at once, 'guitablabel' is used for each
369label separately.
370
Bram Moolenaar57657d82006-04-21 22:12:41 +0000371'guitabtooltip' is very similar and is used for the tooltip of the same label.
372This only appears when the mouse pointer hovers over the label, thus it
373usually is longer. Only supported on some systems though.
374
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000375See the 'statusline' option for the format of the value.
376
377The "%N" item can be used for the current tab page number. The |v:lnum|
Bram Moolenaar57657d82006-04-21 22:12:41 +0000378variable is also set to this number when the option is evaluated.
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000379The items that use a file name refer to the current window of the tab page.
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000380
Bram Moolenaar57657d82006-04-21 22:12:41 +0000381Note that syntax highlighting is not used for the option. The %T and %X
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000382items are also ignored.
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000383
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000384A simple example that puts the tab page number and the buffer name in the
385label: >
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000386 :set guitablabel=%N\ %f
387
Bram Moolenaar57657d82006-04-21 22:12:41 +0000388An example that resembles the default 'guitablabel': Show the number of
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000389windows in the tab page and a '+' if there is a modified buffer: >
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000390
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000391 function GuiTabLabel()
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000392 let label = ''
393 let bufnrlist = tabpagebuflist(v:lnum)
394
395 " Add '+' if one of the buffers in the tab page is modified
396 for bufnr in bufnrlist
397 if getbufvar(bufnr, "&modified")
398 let label = '+'
399 break
400 endif
401 endfor
402
403 " Append the number of windows in the tab page if more than one
404 let wincount = tabpagewinnr(v:lnum, '$')
405 if wincount > 1
406 let label .= wincount
407 endif
408 if label != ''
409 let label .= ' '
410 endif
411
412 " Append the buffer name
413 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])
414 endfunction
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000415
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000416 set guitablabel=%{GuiTabLabel()}
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000417
418Note that the function must be defined before setting the option, otherwise
419you get an error message for the function not being known.
420
Bram Moolenaard68071d2006-05-02 22:08:30 +0000421If you want to fall back to the default label, return an empty string.
422
423If you want to show something specific for a tab page, you might want to use a
424tab page local variable. |t:var|
425
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000426
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000427 vim:tw=78:ts=8:ft=help:norl: