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