1*tabpage.txt* For Vim version 7.3. Last change: 2010 Jul 31 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. For [count] see |:tab| below. 65 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. 70 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 75 at compile time} 76 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 82 one. 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 85 first one. 86 Examples: > 87 :tab split " opens current buffer in new tab page 88 :tab help gt " opens tab page with help for "gt" 89 90CTRL-W gf Open a new tab page and edit the file name under the cursor. 91 See |CTRL-W_gf|. 92 93CTRL-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. 95 See |CTRL-W_gF|. 96 97CLOSING A TAB PAGE: 98 99Closing the last window of a tab page closes the tab page too, unless there is 100only one tab page. 101 102Using the mouse: If the tab page line is displayed you can click in the "X" at 103the top right to close the current tab page. A custom |'tabline'| may show 104something else. 105 106 *:tabc* *:tabclose* 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. 114 115:tabc[lose][!] {count} 116 Close tab page {count}. Fails in the same way as ':tabclose" 117 above. 118 119 *:tabo* *:tabonly* 120:tabo[nly][!] Close all other tab pages. 121 When the 'hidden' option is set, all buffers in closed windows 122 become hidden. 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. 128 129 130SWITCHING TO ANOTHER TAB PAGE: 131 132Using the mouse: If the tab page line is displayed you can click in a tab page 133label to switch to that tab page. Click where there is no label to go to the 134next tab page. |'tabline'| 135 136:tabn[ext] *:tabn* *:tabnext* *gt* 137<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>* 138gt *i_CTRL-<PageDown>* *i_<C-PageDown>* 139 Go to the next tab page. Wraps around from the last to the 140 first one. 141 142:tabn[ext] {count} 143{count}<C-PageDown> 144{count}gt Go to tab page {count}. The first tab page has number one. 145 146 147:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* 148:tabN[ext] *:tabNext* *CTRL-<PageUp>* 149<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>* 150gT Go to the previous tab page. Wraps around from the first one 151 to the last one. 152 153:tabp[revious] {count} 154:tabN[ext] {count} 155{count}<C-PageUp> 156{count}gT Go {count} tab pages back. Wraps around from the first one 157 to the last one. 158 159:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind* 160:tabfir[st] Go to the first tab page. 161 162 *:tabl* *:tablast* 163:tabl[ast] Go to the last tab page. 164 165 166Other commands: 167 *:tabs* 168:tabs List the tab pages and the windows they contain. 169 Shows a ">" for the current window. 170 Shows a "+" for modified buffers. 171 172 173REORDERING TAB PAGES: 174 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. 179 180 181LOOPING OVER TAB PAGES: 182 183 *:tabd* *:tabdo* 184:tabd[o] {cmd} Execute {cmd} in each tab page. 185 It works like doing this: > 186 :tabfirst 187 :{cmd} 188 :tabnext 189 :{cmd} 190 etc. 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 193 will not be visited. 194 The last tab page (or where an error occurred) becomes the 195 current tab page. 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 199 |+listcmds| feature} 200 Also see |:windo|, |:argdo| and |:bufdo|. 201 202============================================================================== 2033. Other items *tab-page-other* 204 205 *tabline-menu* 206The GUI tab pages line has a popup menu. It is accessed with a right click. 207The entries are: 208 Close Close the tab page under the mouse pointer. The 209 current one if there is no label under the mouse 210 pointer. 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. 215 216Diff mode works per tab page. You can see the diffs between several files 217within one tab page. Other tab pages can show differences between other 218files. 219 220Variables local to a tab page start with "t:". |tabpage-variable| 221 222Currently there is only one option local to a tab page: 'cmdheight'. 223 224The TabLeave and TabEnter autocommand events can be used to do something when 225switching from one tab page to another. The exact order depends on what you 226are doing. When creating a new tab page this works as if you create a new 227window on the same buffer and then edit another buffer. Thus ":tabnew" 228triggers: 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 235 236When switching to another tab page the order is: 237 BufLeave 238 WinLeave 239 TabLeave 240 TabEnter 241 WinEnter 242 BufEnter 243 244============================================================================== 2454. Setting 'tabline' *setting-tabline* 246 247The 'tabline' option specifies what the line with tab pages labels looks like. 248It is only used when there is no GUI tab line. 249 250You can use the 'showtabline' option to specify when you want the line with 251tab page labels to appear: never, when there is more than one tab page or 252always. 253 254The highlighting of the tab pages line is set with the groups TabLine 255TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill| 256 257A "+" will be shown for a tab page that has a modified window. The number of 258windows in a tabpage is also shown. Thus "3+" means three windows and one of 259them has a modified buffer. 260 261The 'tabline' option allows you to define your preferred way to tab pages 262labels. This isn't easy, thus an example will be given here. 263 264For 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. 267 268Since the number of tab labels will vary, you need to use an expression for 269the whole option. Something like: > 270 :set tabline=%!MyTabLine() 271 272Then define the MyTabLine() function to list all the tab pages labels. A 273convenient method is to split it in two parts: First go over all the tab 274pages and define labels for them. Then get the label for each tab page. > 275 276 function MyTabLine() 277 let s = '' 278 for i in range(tabpagenr('$')) 279 " select the highlighting 280 if i + 1 == tabpagenr() 281 let s .= '%#TabLineSel#' 282 else 283 let s .= '%#TabLine#' 284 endif 285 286 " set the tab page number (for mouse clicks) 287 let s .= '%' . (i + 1) . 'T' 288 289 " the label is made by MyTabLabel() 290 let s .= ' %{MyTabLabel(' . (i + 1) . ')} ' 291 endfor 292 293 " after the last tab fill with TabLineFill and reset tab page nr 294 let s .= '%#TabLineFill#%T' 295 296 " right-align the label to close the current tab page 297 if tabpagenr('$') > 1 298 let s .= '%=%#TabLine#%999Xclose' 299 endif 300 301 return s 302 endfunction 303 304Now the MyTabLabel() function is called for each tab page to get its label. > 305 306 function MyTabLabel(n) 307 let buflist = tabpagebuflist(a:n) 308 let winnr = tabpagewinnr(a:n) 309 return bufname(buflist[winnr - 1]) 310 endfunction 311 312This is just a simplistic example that results in a tab pages line that 313resembles the default, but without adding a + for a modified buffer or 314truncating the names. You will want to reduce the width of labels in a 315clever way when there is not enough room. Check the 'columns' option for the 316space available. 317 318============================================================================== 3195. Setting 'guitablabel' *setting-guitablabel* 320 321When the GUI tab pages line is displayed, 'guitablabel' can be used to 322specify the label to display for each tab page. Unlike 'tabline', which 323specifies the whole tab pages line at once, 'guitablabel' is used for each 324label separately. 325 326'guitabtooltip' is very similar and is used for the tooltip of the same label. 327This only appears when the mouse pointer hovers over the label, thus it 328usually is longer. Only supported on some systems though. 329 330See the 'statusline' option for the format of the value. 331 332The "%N" item can be used for the current tab page number. The |v:lnum| 333variable is also set to this number when the option is evaluated. 334The items that use a file name refer to the current window of the tab page. 335 336Note that syntax highlighting is not used for the option. The %T and %X 337items are also ignored. 338 339A simple example that puts the tab page number and the buffer name in the 340label: > 341 :set guitablabel=%N\ %f 342 343An example that resembles the default 'guitablabel': Show the number of 344windows in the tab page and a '+' if there is a modified buffer: > 345 346 function GuiTabLabel() 347 let label = '' 348 let bufnrlist = tabpagebuflist(v:lnum) 349 350 " Add '+' if one of the buffers in the tab page is modified 351 for bufnr in bufnrlist 352 if getbufvar(bufnr, "&modified") 353 let label = '+' 354 break 355 endif 356 endfor 357 358 " Append the number of windows in the tab page if more than one 359 let wincount = tabpagewinnr(v:lnum, '$') 360 if wincount > 1 361 let label .= wincount 362 endif 363 if label != '' 364 let label .= ' ' 365 endif 366 367 " Append the buffer name 368 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1]) 369 endfunction 370 371 set guitablabel=%{GuiTabLabel()} 372 373Note that the function must be defined before setting the option, otherwise 374you get an error message for the function not being known. 375 376If you want to fall back to the default label, return an empty string. 377 378If you want to show something specific for a tab page, you might want to use a 379tab page local variable. |t:var| 380 381 382 vim:tw=78:ts=8:ft=help:norl: 383