1*tabpage.txt* For Vim version 8.2. Last change: 2020 Oct 14 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Editing with windows in multiple tab pages. *tab-page* *tabpage* 8 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 131. Introduction |tab-page-intro| 142. Commands |tab-page-commands| 153. Other items |tab-page-other| 164. Setting 'tabline' |setting-tabline| 175. Setting 'guitablabel' |setting-guitablabel| 18 19{not able to use multiple tab pages when the |+windows| feature was disabled 20at compile time} 21 22============================================================================== 231. Introduction *tab-page-intro* 24 25A tab page holds one or more windows. You can easily switch between tab 26pages, so that you have several collections of windows to work on different 27things. 28 29Usually you will see a list of labels at the top of the Vim window, one for 30each tab page. With the mouse you can click on the label to jump to that tab 31page. There are other ways to move between tab pages, see below. 32 33Most commands work only in the current tab page. That includes the |CTRL-W| 34commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier). 35The commands that are aware of other tab pages than the current one are 36mentioned below. 37 38Tabs are also a nice way to edit a buffer temporarily without changing the 39current window layout. Open a new tab page, do whatever you want to do and 40close the tab page. 41 42============================================================================== 432. Commands *tab-page-commands* 44 45OPENING A NEW TAB PAGE: 46 47When starting Vim "vim -p filename ..." opens each file argument in a separate 48tab page (up to 'tabpagemax'). See |-p| 49 50A double click with the mouse in the non-GUI tab pages line opens a new, empty 51tab page. It is placed left of the position of the click. The first click 52may select another tab page first, causing an extra screen update. 53 54This also works in a few GUI versions, esp. Win32 and Motif. But only when 55clicking right of the labels. 56 57In the GUI tab pages line you can use the right mouse button to open menu. 58|tabline-menu|. 59 60For the related autocommands see |tabnew-autocmd|. 61 62:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* 63:[count]tabnew 64 Open a new tab page with an empty window, after the current 65 tab page. If [count] is given the new tab page appears after 66 the tab page [count] otherwise the new tab page will appear 67 after the current one. > 68 :tabnew " opens tabpage after the current one 69 :.tabnew " as above 70 :+tabnew " opens tabpage after the next tab page 71 " note: it is one further than :tabnew 72 :-tabnew " opens tabpage before the current one 73 :0tabnew " opens tabpage before the first one 74 :$tabnew " opens tabpage after the last one 75 76:[count]tabe[dit] [++opt] [+cmd] {file} 77:[count]tabnew [++opt] [+cmd] {file} 78 Open a new tab page and edit {file}, like with |:edit|. 79 For [count] see |:tabnew| above. 80 81:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind* 82 Open a new tab page and edit {file} in 'path', like with 83 |:find|. For [count] see |:tabnew| above. 84 {not available when the |+file_in_path| feature was disabled 85 at compile time} 86 87:[count]tab {cmd} *:tab* 88 Execute {cmd} and when it opens a new window open a new tab 89 page instead. Doesn't work for |:diffsplit|, |:diffpatch|, 90 |:execute| and |:normal|. 91 If [count] is given the new tab page appears after the tab 92 page [count] otherwise the new tab page will appear after the 93 current one. 94 Examples: > 95 :tab split " opens current buffer in new tab page 96 :tab help gt " opens tab page with help for "gt" 97 :.tab help gt " as above 98 :+tab help " opens tab page with help after the next 99 " tab page 100 :-tab help " opens tab page with help before the 101 " current one 102 :0tab help " opens tab page with help before the 103 " first one 104 :$tab help " opens tab page with help after the last 105 " one 106 107CTRL-W gf Open a new tab page and edit the file name under the cursor. 108 See |CTRL-W_gf|. 109 110CTRL-W gF Open a new tab page and edit the file name under the cursor 111 and jump to the line number following the file name. 112 See |CTRL-W_gF|. 113 114CLOSING A TAB PAGE: 115 116Closing the last window of a tab page closes the tab page too, unless there is 117only one tab page. 118 119Using the mouse: If the tab page line is displayed you can click in the "X" at 120the top right to close the current tab page. A custom |'tabline'| may show 121something else. 122 123 *:tabc* *:tabclose* 124:tabc[lose][!] Close current tab page. 125 This command fails when: 126 - There is only one tab page on the screen. *E784* 127 - When 'hidden' is not set, [!] is not used, a buffer has 128 changes, and there is no other window on this buffer. 129 Changes to the buffer are not written and won't get lost, so 130 this is a "safe" command. > 131 :tabclose " close the current tab page 132 133:{count}tabc[lose][!] 134:tabc[lose][!] {count} 135 Close tab page {count}. Fails in the same way as `:tabclose` 136 above. > 137 :-tabclose " close the previous tab page 138 :+tabclose " close the next tab page 139 :1tabclose " close the first tab page 140 :$tabclose " close the last tab page 141 :tabclose -2 " close the 2nd previous tab page 142 :tabclose + " close the next tab page 143 :tabclose 3 " close the third tab page 144 :tabclose $ " close the last tab page 145 :tabclose # " close the last accessed tab page 146< 147 *:tabo* *:tabonly* 148:tabo[nly][!] Close all other tab pages. 149 When the 'hidden' option is set, all buffers in closed windows 150 become hidden. 151 When 'hidden' is not set, and the 'autowrite' option is set, 152 modified buffers are written. Otherwise, windows that have 153 buffers that are modified are not removed, unless the [!] is 154 given, then they become hidden. But modified buffers are 155 never abandoned, so changes cannot get lost. > 156 :tabonly " close all tab pages except the current 157 " one 158 159:{count}tabo[nly][!] 160:tabo[nly][!] {count} 161 Close all tab pages except {count} one. > 162 :.tabonly " as above 163 :-tabonly " close all tab pages except the previous 164 " one 165 :+tabonly " close all tab pages except the next one 166 :1tabonly " close all tab pages except the first one 167 :$tabonly " close all tab pages except the last one 168 :tabonly - " close all tab pages except the previous 169 " one 170 :tabonly +2 " close all tab pages except the two next 171 " one 172 :tabonly 1 " close all tab pages except the first one 173 :tabonly $ " close all tab pages except the last one 174 :tabonly # " close all tab pages except the last 175 " accessed one 176 177 178SWITCHING TO ANOTHER TAB PAGE: 179 180Using the mouse: If the tab page line is displayed you can click in a tab page 181label to switch to that tab page. Click where there is no label to go to the 182next tab page. |'tabline'| 183 184:tabn[ext] *:tabn* *:tabnext* *gt* 185<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>* 186gt *i_CTRL-<PageDown>* *i_<C-PageDown>* 187 Go to the next tab page. Wraps around from the last to the 188 first one. 189 190:{count}tabn[ext] 191:tabn[ext] {count} 192 Go to tab page {count}. The first tab page has number one. > 193 :-tabnext " go to the previous tab page 194 :+tabnext " go to the next tab page 195 :+2tabnext " go to the two next tab page 196 :1tabnext " go to the first tab page 197 :$tabnext " go to the last tab page 198 :tabnext $ " as above 199 :tabnext # " go to the last accessed tab page 200 :tabnext - " go to the previous tab page 201 :tabnext -1 " as above 202 :tabnext + " go to the next tab page 203 :tabnext +1 " as above 204 205{count}<C-PageDown> 206{count}gt Go to tab page {count}. The first tab page has number one. 207 208 209:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* 210:tabN[ext] *:tabNext* *CTRL-<PageUp>* 211<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>* 212gT Go to the previous tab page. Wraps around from the first one 213 to the last one. 214 215:tabp[revious] {count} 216:tabN[ext] {count} 217{count}<C-PageUp> 218{count}gT Go {count} tab pages back. Wraps around from the first one 219 to the last one. Note that the use of {count} is different 220 from |:tabnext|, where it is used as the tab page number. 221 222:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind* 223:tabfir[st] Go to the first tab page. 224 225 *:tabl* *:tablast* 226:tabl[ast] Go to the last tab page. 227 228 *g<Tab>* *CTRL-W_g<Tab>* *<C-Tab>* 229g<Tab> Go to the last accessed tab page. 230 231Other commands: 232 *:tabs* 233:tabs List the tab pages and the windows they contain. 234 Shows a ">" for the current window. 235 Shows a "+" for modified buffers. 236 For example: 237 Tab page 1 ~ 238 + tabpage.txt ~ 239 ex_docmd.c ~ 240 Tab page 2 ~ 241 > main.c ~ 242 243 244REORDERING TAB PAGES: 245 246:tabm[ove] [N] *:tabm* *:tabmove* 247:[N]tabm[ove] 248 Move the current tab page to after tab page N. Use zero to 249 make the current tab page the first one. N is counted before 250 the move, thus if the second tab is the current one, 251 `:tabmove 1` and `:tabmove 2` have no effect. 252 Without N the tab page is made the last one. > 253 :.tabmove " do nothing 254 :-tabmove " move the tab page to the left 255 :+tabmove " move the tab page to the right 256 :0tabmove " move the tab page to the beginning of the tab 257 " list 258 :tabmove 0 " as above 259 :tabmove " move the tab page to the last 260 :$tabmove " as above 261 :tabmove $ " as above 262 :tabmove # " move the tab page after the last accessed 263 " tab page 264 265:tabm[ove] +[N] 266:tabm[ove] -[N] 267 Move the current tab page N places to the right (with +) or to 268 the left (with -). > 269 :tabmove - " move the tab page to the left 270 :tabmove -1 " as above 271 :tabmove + " move the tab page to the right 272 :tabmove +1 " as above 273 274 275Note that although it is possible to move a tab behind the N-th one by using 276:Ntabmove. And move it by N places by using :+Ntabmove. For clarification what 277+N means in this context see |[range]|. 278 279 280LOOPING OVER TAB PAGES: 281 282 *:tabd* *:tabdo* 283:[range]tabd[o] {cmd} 284 Execute {cmd} in each tab page or if [range] is given only in 285 tab pages which tab page number is in the [range]. It works 286 like doing this: > 287 :tabfirst 288 :{cmd} 289 :tabnext 290 :{cmd} 291 etc. 292< This only operates in the current window of each tab page. 293 When an error is detected on one tab page, further tab pages 294 will not be visited. 295 The last tab page (or where an error occurred) becomes the 296 current tab page. 297 {cmd} can contain '|' to concatenate several commands. 298 {cmd} must not open or close tab pages or reorder them. 299 Also see |:windo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, |:cfdo| 300 and |:lfdo| 301 302============================================================================== 3033. Other items *tab-page-other* 304 305 *tabline-menu* 306The GUI tab pages line has a popup menu. It is accessed with a right click. 307The entries are: 308 Close Close the tab page under the mouse pointer. The 309 current one if there is no label under the mouse 310 pointer. 311 New Tab Open a tab page, editing an empty buffer. It appears 312 to the left of the mouse pointer. 313 Open Tab... Like "New Tab" and additionally use a file selector to 314 select a file to edit. 315 316Diff mode works per tab page. You can see the diffs between several files 317within one tab page. Other tab pages can show differences between other 318files. 319 320Variables local to a tab page start with "t:". |tabpage-variable| 321 322Currently there is only one option local to a tab page: 'cmdheight'. 323 324 *tabnew-autocmd* 325The TabLeave and TabEnter autocommand events can be used to do something when 326switching from one tab page to another. The exact order depends on what you 327are doing. When creating a new tab page this works as if you create a new 328window on the same buffer and then edit another buffer. Thus ":tabnew" 329triggers: 330 WinLeave leave current window 331 TabLeave leave current tab page 332 WinEnter enter window in new tab page 333 TabEnter enter new tab page 334 BufLeave leave current buffer 335 BufEnter enter new empty buffer 336 337When switching to another tab page the order is: 338 BufLeave 339 WinLeave 340 TabLeave 341 TabEnter 342 WinEnter 343 BufEnter 344 345============================================================================== 3464. Setting 'tabline' *setting-tabline* 347 348The 'tabline' option specifies what the line with tab pages labels looks like. 349It is only used when there is no GUI tab line. 350 351You can use the 'showtabline' option to specify when you want the line with 352tab page labels to appear: never, when there is more than one tab page or 353always. 354 355The highlighting of the tab pages line is set with the groups TabLine 356TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill| 357 358A "+" will be shown for a tab page that has a modified window. The number of 359windows in a tabpage is also shown. Thus "3+" means three windows and one of 360them has a modified buffer. 361 362The 'tabline' option allows you to define your preferred way to tab pages 363labels. This isn't easy, thus an example will be given here. 364 365For basics see the 'statusline' option. The same items can be used in the 366'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and 367|tabpagewinnr()| functions are useful. 368 369Since the number of tab labels will vary, you need to use an expression for 370the whole option. Something like: > 371 :set tabline=%!MyTabLine() 372 373Then define the MyTabLine() function to list all the tab pages labels. A 374convenient method is to split it in two parts: First go over all the tab 375pages and define labels for them. Then get the label for each tab page. > 376 377 function MyTabLine() 378 let s = '' 379 for i in range(tabpagenr('$')) 380 " select the highlighting 381 if i + 1 == tabpagenr() 382 let s .= '%#TabLineSel#' 383 else 384 let s .= '%#TabLine#' 385 endif 386 387 " set the tab page number (for mouse clicks) 388 let s .= '%' . (i + 1) . 'T' 389 390 " the label is made by MyTabLabel() 391 let s .= ' %{MyTabLabel(' . (i + 1) . ')} ' 392 endfor 393 394 " after the last tab fill with TabLineFill and reset tab page nr 395 let s .= '%#TabLineFill#%T' 396 397 " right-align the label to close the current tab page 398 if tabpagenr('$') > 1 399 let s .= '%=%#TabLine#%999Xclose' 400 endif 401 402 return s 403 endfunction 404 405Now the MyTabLabel() function is called for each tab page to get its label. > 406 407 function MyTabLabel(n) 408 let buflist = tabpagebuflist(a:n) 409 let winnr = tabpagewinnr(a:n) 410 return bufname(buflist[winnr - 1]) 411 endfunction 412 413This is just a simplistic example that results in a tab pages line that 414resembles the default, but without adding a + for a modified buffer or 415truncating the names. You will want to reduce the width of labels in a 416clever way when there is not enough room. Check the 'columns' option for the 417space available. 418 419============================================================================== 4205. Setting 'guitablabel' *setting-guitablabel* 421 422When the GUI tab pages line is displayed, 'guitablabel' can be used to 423specify the label to display for each tab page. Unlike 'tabline', which 424specifies the whole tab pages line at once, 'guitablabel' is used for each 425label separately. 426 427'guitabtooltip' is very similar and is used for the tooltip of the same label. 428This only appears when the mouse pointer hovers over the label, thus it 429usually is longer. Only supported on some systems though. 430 431See the 'statusline' option for the format of the value. 432 433The "%N" item can be used for the current tab page number. The |v:lnum| 434variable is also set to this number when the option is evaluated. 435The items that use a file name refer to the current window of the tab page. 436 437Note that syntax highlighting is not used for the option. The %T and %X 438items are also ignored. 439 440A simple example that puts the tab page number and the buffer name in the 441label: > 442 :set guitablabel=%N\ %f 443 444An example that resembles the default 'guitablabel': Show the number of 445windows in the tab page and a '+' if there is a modified buffer: > 446 447 function GuiTabLabel() 448 let label = '' 449 let bufnrlist = tabpagebuflist(v:lnum) 450 451 " Add '+' if one of the buffers in the tab page is modified 452 for bufnr in bufnrlist 453 if getbufvar(bufnr, "&modified") 454 let label = '+' 455 break 456 endif 457 endfor 458 459 " Append the number of windows in the tab page if more than one 460 let wincount = tabpagewinnr(v:lnum, '$') 461 if wincount > 1 462 let label .= wincount 463 endif 464 if label != '' 465 let label .= ' ' 466 endif 467 468 " Append the buffer name 469 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1]) 470 endfunction 471 472 set guitablabel=%{GuiTabLabel()} 473 474Note that the function must be defined before setting the option, otherwise 475you get an error message for the function not being known. 476 477If you want to fall back to the default label, return an empty string. 478 479If you want to show something specific for a tab page, you might want to use a 480tab page local variable. |t:var| 481 482 483 vim:tw=78:ts=8:noet:ft=help:norl: 484