1*tabpage.txt* For Vim version 7.4. Last change: 2015 Jan 04 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{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| 35commands, |: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. 38 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 49tab page (up to 'tabpagemax'). See |-p| 50 51A 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 55This also works in a few GUI versions, esp. Win32 and Motif. But only when 56clicking right of the labels. 57 58In the GUI tab pages line you can use the right mouse button to open menu. 59|tabline-menu|. 60 61:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* 62:[count]tabnew 63 Open a new tab page with an empty window, after the current 64 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 74 75:[count]tabe[dit] [++opt] [+cmd] {file} 76:[count]tabnew [++opt] [+cmd] {file} 77 Open a new tab page and edit {file}, like with |:edit|. 78 For [count] see |:tabnew| above. 79 80:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind* 81 Open a new tab page and edit {file} in 'path', like with 82 |:find|. For [count] see |:tabnew| above. 83 {not available when the |+file_in_path| feature was disabled 84 at compile time} 85 86:[count]tab {cmd} *:tab* 87 Execute {cmd} and when it opens a new window open a new tab 88 page instead. Doesn't work for |:diffsplit|, |:diffpatch|, 89 |:execute| and |:normal|. 90 When [count] is omitted the tab page appears after the current 91 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: > 96 :tab split " opens current buffer in new tab page 97 :tab help gt " opens tab page with help for "gt" 98 99CTRL-W gf Open a new tab page and edit the file name under the cursor. 100 See |CTRL-W_gf|. 101 102CTRL-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|. 105 106CLOSING A TAB PAGE: 107 108Closing the last window of a tab page closes the tab page too, unless there is 109only one tab page. 110 111Using the mouse: If the tab page line is displayed you can click in the "X" at 112the top right to close the current tab page. A custom |'tabline'| may show 113something else. 114 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 122 this is a "safe" command. > 123 :tabclose " close the current tab page 124 125:{count}tabc[lose][!] 126:tabc[lose][!] {count} 127 Close tab page {count}. Fails in the same way as `:tabclose` 128 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< 134 *: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 142 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 153 154 155SWITCHING TO ANOTHER TAB PAGE: 156 157Using the mouse: If the tab page line is displayed you can click in a tab page 158label to switch to that tab page. Click where there is no label to go to the 159next tab page. |'tabline'| 160 161:tabn[ext] *:tabn* *:tabnext* *gt* 162<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>* 163gt *i_CTRL-<PageDown>* *i_<C-PageDown>* 164 Go to the next tab page. Wraps around from the last to the 165 first one. 166 167:tabn[ext] {count} 168{count}<C-PageDown> 169{count}gt Go to tab page {count}. The first tab page has number one. 170 171 172:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* 173:tabN[ext] *:tabNext* *CTRL-<PageUp>* 174<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>* 175gT 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} 180{count}<C-PageUp> 181{count}gT Go {count} tab pages back. Wraps around from the first one 182 to the last one. 183 184:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind* 185:tabfir[st] Go to the first tab page. 186 187 *:tabl* *:tablast* 188:tabl[ast] Go to the last tab page. 189 190 191Other commands: 192 *:tabs* 193: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 200:tabm[ove] [N] *:tabm* *:tabmove* 201:[N]tabm[ove] 202 Move the current tab page to after tab page N. Use zero to 203 make the current tab page the first one. Without N the tab 204 page is made the last one. > 205 :.tabmove " do nothing 206 :-tabmove " move the tab page to the left 207 :+tabmove " move the tab page to the right 208 :0tabmove " move the tab page to the beginning of the tab 209 " list 210 :tabmove 0 " as above 211 :tabmove " move the tab page to the last 212 :$tabmove " as above 213 :tabmove $ " as above 214 215:tabm[ove] +[N] 216:tabm[ove] -[N] 217 Move the current tab page N places to the right (with +) or to 218 the left (with -). > 219 :tabmove - " move the tab page to the left 220 :tabmove -1 " as above 221 :tabmove + " move the tab page to the right 222 :tabmove +1 " as above 223 224 225Note that although it is possible to move a tab behind the N-th one by using 226:Ntabmove. And move it by N places by using :+Ntabmove. For clarification what 227+N means in this context see |[range]|. 228 229 230LOOPING OVER TAB PAGES: 231 232 *:tabd* *:tabdo* 233:[range]tabd[o] {cmd} 234 Execute {cmd} in each tab page or if [range] is given only in 235 tab pages which tab page number is in the [range]. It works 236 like doing this: > 237 :tabfirst 238 :{cmd} 239 :tabnext 240 :{cmd} 241 etc. 242< This only operates in the current window of each tab page. 243 When an error is detected on one tab page, further tab pages 244 will not be visited. 245 The last tab page (or where an error occurred) becomes the 246 current tab page. 247 {cmd} can contain '|' to concatenate several commands. 248 {cmd} must not open or close tab pages or reorder them. 249 {not in Vi} {not available when compiled without the 250 |+listcmds| feature} 251 Also see |:windo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, |:cfdo| 252 and |:lfdo| 253 254============================================================================== 2553. Other items *tab-page-other* 256 257 *tabline-menu* 258The GUI tab pages line has a popup menu. It is accessed with a right click. 259The entries are: 260 Close Close the tab page under the mouse pointer. The 261 current one if there is no label under the mouse 262 pointer. 263 New Tab Open a tab page, editing an empty buffer. It appears 264 to the left of the mouse pointer. 265 Open Tab... Like "New Tab" and additionally use a file selector to 266 select a file to edit. 267 268Diff mode works per tab page. You can see the diffs between several files 269within one tab page. Other tab pages can show differences between other 270files. 271 272Variables local to a tab page start with "t:". |tabpage-variable| 273 274Currently there is only one option local to a tab page: 'cmdheight'. 275 276The TabLeave and TabEnter autocommand events can be used to do something when 277switching from one tab page to another. The exact order depends on what you 278are doing. When creating a new tab page this works as if you create a new 279window on the same buffer and then edit another buffer. Thus ":tabnew" 280triggers: 281 WinLeave leave current window 282 TabLeave leave current tab page 283 WinEnter enter window in new tab page 284 TabEnter enter new tab page 285 BufLeave leave current buffer 286 BufEnter enter new empty buffer 287 288When switching to another tab page the order is: 289 BufLeave 290 WinLeave 291 TabLeave 292 TabEnter 293 WinEnter 294 BufEnter 295 296============================================================================== 2974. Setting 'tabline' *setting-tabline* 298 299The 'tabline' option specifies what the line with tab pages labels looks like. 300It is only used when there is no GUI tab line. 301 302You can use the 'showtabline' option to specify when you want the line with 303tab page labels to appear: never, when there is more than one tab page or 304always. 305 306The highlighting of the tab pages line is set with the groups TabLine 307TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill| 308 309A "+" will be shown for a tab page that has a modified window. The number of 310windows in a tabpage is also shown. Thus "3+" means three windows and one of 311them has a modified buffer. 312 313The 'tabline' option allows you to define your preferred way to tab pages 314labels. This isn't easy, thus an example will be given here. 315 316For basics see the 'statusline' option. The same items can be used in the 317'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and 318|tabpagewinnr()| functions are useful. 319 320Since the number of tab labels will vary, you need to use an expression for 321the whole option. Something like: > 322 :set tabline=%!MyTabLine() 323 324Then define the MyTabLine() function to list all the tab pages labels. A 325convenient method is to split it in two parts: First go over all the tab 326pages and define labels for them. Then get the label for each tab page. > 327 328 function MyTabLine() 329 let s = '' 330 for i in range(tabpagenr('$')) 331 " select the highlighting 332 if i + 1 == tabpagenr() 333 let s .= '%#TabLineSel#' 334 else 335 let s .= '%#TabLine#' 336 endif 337 338 " set the tab page number (for mouse clicks) 339 let s .= '%' . (i + 1) . 'T' 340 341 " the label is made by MyTabLabel() 342 let s .= ' %{MyTabLabel(' . (i + 1) . ')} ' 343 endfor 344 345 " after the last tab fill with TabLineFill and reset tab page nr 346 let s .= '%#TabLineFill#%T' 347 348 " right-align the label to close the current tab page 349 if tabpagenr('$') > 1 350 let s .= '%=%#TabLine#%999Xclose' 351 endif 352 353 return s 354 endfunction 355 356Now the MyTabLabel() function is called for each tab page to get its label. > 357 358 function MyTabLabel(n) 359 let buflist = tabpagebuflist(a:n) 360 let winnr = tabpagewinnr(a:n) 361 return bufname(buflist[winnr - 1]) 362 endfunction 363 364This is just a simplistic example that results in a tab pages line that 365resembles the default, but without adding a + for a modified buffer or 366truncating the names. You will want to reduce the width of labels in a 367clever way when there is not enough room. Check the 'columns' option for the 368space available. 369 370============================================================================== 3715. Setting 'guitablabel' *setting-guitablabel* 372 373When the GUI tab pages line is displayed, 'guitablabel' can be used to 374specify the label to display for each tab page. Unlike 'tabline', which 375specifies the whole tab pages line at once, 'guitablabel' is used for each 376label separately. 377 378'guitabtooltip' is very similar and is used for the tooltip of the same label. 379This only appears when the mouse pointer hovers over the label, thus it 380usually is longer. Only supported on some systems though. 381 382See the 'statusline' option for the format of the value. 383 384The "%N" item can be used for the current tab page number. The |v:lnum| 385variable is also set to this number when the option is evaluated. 386The items that use a file name refer to the current window of the tab page. 387 388Note that syntax highlighting is not used for the option. The %T and %X 389items are also ignored. 390 391A simple example that puts the tab page number and the buffer name in the 392label: > 393 :set guitablabel=%N\ %f 394 395An example that resembles the default 'guitablabel': Show the number of 396windows in the tab page and a '+' if there is a modified buffer: > 397 398 function GuiTabLabel() 399 let label = '' 400 let bufnrlist = tabpagebuflist(v:lnum) 401 402 " Add '+' if one of the buffers in the tab page is modified 403 for bufnr in bufnrlist 404 if getbufvar(bufnr, "&modified") 405 let label = '+' 406 break 407 endif 408 endfor 409 410 " Append the number of windows in the tab page if more than one 411 let wincount = tabpagewinnr(v:lnum, '$') 412 if wincount > 1 413 let label .= wincount 414 endif 415 if label != '' 416 let label .= ' ' 417 endif 418 419 " Append the buffer name 420 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1]) 421 endfunction 422 423 set guitablabel=%{GuiTabLabel()} 424 425Note that the function must be defined before setting the option, otherwise 426you get an error message for the function not being known. 427 428If you want to fall back to the default label, return an empty string. 429 430If you want to show something specific for a tab page, you might want to use a 431tab page local variable. |t:var| 432 433 434 vim:tw=78:ts=8:ft=help:norl: 435