share/vim/vim74/doc/tabpage.txt

   1 *tabpage.txt*   For Vim version 7.4.  Last change: 2012 Aug 08
   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 '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
  21 at compile time}
  22
  23 ==============================================================================
  24 1. Introduction                                         *tab-page-intro*
  25
  26 A tab page holds one or more windows.  You can easily switch between tab
  27 pages, so that you have several collections of windows to work on different
  28 things.
  29
  30 Usually you will see a list of labels at the top of the Vim window, one for
  31 each tab page.  With the mouse you can click on the label to jump to that tab
  32 page.  There are other ways to move between tab pages, see below.
  33
  34 Most commands work only in the current tab page.  That includes the |CTRL-W|
  35 commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier).
  36 The commands that are aware of other tab pages than the current one are
  37 mentioned below.
  38
  39 Tabs are also a nice way to edit a buffer temporarily without changing the
  40 current window layout.  Open a new tab page, do whatever you want to do and
  41 close the tab page.
  42
  43 ==============================================================================
  44 2. Commands                                             *tab-page-commands*
  45
  46 OPENING A NEW TAB PAGE:
  47
  48 When starting Vim "vim -p filename ..." opens each file argument in a separate
  49 tab page (up to 'tabpagemax').  See |-p|
  50
  51 A double click with the mouse in the non-GUI tab pages line opens a new, empty
  52 tab page.  It is placed left of the position of the click.  The first click
  53 may select another tab page first, causing an extra screen update.
  54
  55 This also works in a few GUI versions, esp. Win32 and Motif.  But only when
  56 clicking right of the labels.
  57
  58 In 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
  90 CTRL-W gf       Open a new tab page and edit the file name under the cursor.
  91                 See |CTRL-W_gf|.
  92
  93 CTRL-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
  97 CLOSING A TAB PAGE:
  98
  99 Closing the last window of a tab page closes the tab page too, unless there is
 100 only one tab page.
 101
 102 Using the mouse: If the tab page line is displayed you can click in the "X" at
 103 the top right to close the current tab page.  A custom |'tabline'| may show
 104 something 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
 130 SWITCHING TO ANOTHER TAB PAGE:
 131
 132 Using the mouse: If the tab page line is displayed you can click in a tab page
 133 label to switch to that tab page.  Click where there is no label to go to the
 134 next tab page.  |'tabline'|
 135
 136 :tabn[ext]                              *:tabn* *:tabnext* *gt*
 137 <C-PageDown>                            *CTRL-<PageDown>* *<C-PageDown>*
 138 gt                                      *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>*
 150 gT              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
 166 Other 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
 173 REORDERING TAB PAGES:
 174
 175 :tabm[ove] [N]                                          *:tabm* *:tabmove*
 176 :[N]tabm[ove]
 177                 Move the current tab page to after tab page N.  Use zero to
 178                 make the current tab page the first one.  Without N the tab
 179                 page is made the last one.
 180
 181 :tabm[ove] +[N]
 182 :tabm[ove] -[N]
 183                 Move the current tab page N places to the right (with +) or to
 184                 the left (with -).
 185
 186 Note that although it is possible to move a tab behind the N-th one by using
 187 :Ntabmove, it is impossible to move it by N places by using :+Ntabmove. For
 188 clarification what +N means in this context see |[range]|.
 189
 190
 191 LOOPING OVER TAB PAGES:
 192
 193                                                         *:tabd* *:tabdo*
 194 :tabd[o] {cmd}  Execute {cmd} in each tab page.
 195                 It works like doing this: >
 196                         :tabfirst
 197                         :{cmd}
 198                         :tabnext
 199                         :{cmd}
 200                         etc.
 201 <               This only operates in the current window of each tab page.
 202                 When an error is detected on one tab page, further tab pages
 203                 will not be visited.
 204                 The last tab page (or where an error occurred) becomes the
 205                 current tab page.
 206                 {cmd} can contain '|' to concatenate several commands.
 207                 {cmd} must not open or close tab pages or reorder them.
 208                 {not in Vi} {not available when compiled without the
 209                 |+listcmds| feature}
 210                 Also see |:windo|, |:argdo| and |:bufdo|.
 211
 212 ==============================================================================
 213 3. Other items                                          *tab-page-other*
 214
 215                                                         *tabline-menu*
 216 The GUI tab pages line has a popup menu.  It is accessed with a right click.
 217 The entries are:
 218         Close           Close the tab page under the mouse pointer.  The
 219                         current one if there is no label under the mouse
 220                         pointer.
 221         New Tab         Open a tab page, editing an empty buffer.  It appears
 222                         to the left of the mouse pointer.
 223         Open Tab...     Like "New Tab" and additionally use a file selector to
 224                         select a file to edit.
 225
 226 Diff mode works per tab page.  You can see the diffs between several files
 227 within one tab page.  Other tab pages can show differences between other
 228 files.
 229
 230 Variables local to a tab page start with "t:". |tabpage-variable|
 231
 232 Currently there is only one option local to a tab page: 'cmdheight'.
 233
 234 The TabLeave and TabEnter autocommand events can be used to do something when
 235 switching from one tab page to another.  The exact order depends on what you
 236 are doing.  When creating a new tab page this works as if you create a new
 237 window on the same buffer and then edit another buffer.  Thus ":tabnew"
 238 triggers:
 239         WinLeave                leave current window
 240         TabLeave                leave current tab page
 241         TabEnter                enter new tab page
 242         WinEnter                enter window in new tab page
 243         BufLeave                leave current buffer
 244         BufEnter                enter new empty buffer
 245
 246 When switching to another tab page the order is:
 247         BufLeave
 248         WinLeave
 249         TabLeave
 250         TabEnter
 251         WinEnter
 252         BufEnter
 253
 254 ==============================================================================
 255 4. Setting 'tabline'                                    *setting-tabline*
 256
 257 The 'tabline' option specifies what the line with tab pages labels looks like.
 258 It is only used when there is no GUI tab line.
 259
 260 You can use the 'showtabline' option to specify when you want the line with
 261 tab page labels to appear: never, when there is more than one tab page or
 262 always.
 263
 264 The highlighting of the tab pages line is set with the groups TabLine
 265 TabLineSel and TabLineFill.  |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
 266
 267 A "+" will be shown for a tab page that has a modified window.  The number of
 268 windows in a tabpage is also shown.  Thus "3+" means three windows and one of
 269 them has a modified buffer.
 270
 271 The 'tabline' option allows you to define your preferred way to tab pages
 272 labels.  This isn't easy, thus an example will be given here.
 273
 274 For basics see the 'statusline' option.  The same items can be used in the
 275 'tabline' option.  Additionally, the |tabpagebuflist()|, |tabpagenr()| and
 276 |tabpagewinnr()| functions are useful.
 277
 278 Since the number of tab labels will vary, you need to use an expression for
 279 the whole option.  Something like: >
 280         :set tabline=%!MyTabLine()
 281
 282 Then define the MyTabLine() function to list all the tab pages labels.  A
 283 convenient method is to split it in two parts:  First go over all the tab
 284 pages and define labels for them.  Then get the label for each tab page. >
 285
 286         function MyTabLine()
 287           let s = ''
 288           for i in range(tabpagenr('$'))
 289             " select the highlighting
 290             if i + 1 == tabpagenr()
 291               let s .= '%#TabLineSel#'
 292             else
 293               let s .= '%#TabLine#'
 294             endif
 295
 296             " set the tab page number (for mouse clicks)
 297             let s .= '%' . (i + 1) . 'T'
 298
 299             " the label is made by MyTabLabel()
 300             let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
 301           endfor
 302
 303           " after the last tab fill with TabLineFill and reset tab page nr
 304           let s .= '%#TabLineFill#%T'
 305
 306           " right-align the label to close the current tab page
 307           if tabpagenr('$') > 1
 308             let s .= '%=%#TabLine#%999Xclose'
 309           endif
 310
 311           return s
 312         endfunction
 313
 314 Now the MyTabLabel() function is called for each tab page to get its label. >
 315
 316         function MyTabLabel(n)
 317           let buflist = tabpagebuflist(a:n)
 318           let winnr = tabpagewinnr(a:n)
 319           return bufname(buflist[winnr - 1])
 320         endfunction
 321
 322 This is just a simplistic example that results in a tab pages line that
 323 resembles the default, but without adding a + for a modified buffer or
 324 truncating the names.  You will want to reduce the width of labels in a
 325 clever way when there is not enough room.  Check the 'columns' option for the
 326 space available.
 327
 328 ==============================================================================
 329 5. Setting 'guitablabel'                                *setting-guitablabel*
 330
 331 When the GUI tab pages line is displayed, 'guitablabel' can be used to
 332 specify the label to display for each tab page.  Unlike 'tabline', which
 333 specifies the whole tab pages line at once, 'guitablabel' is used for each
 334 label separately.
 335
 336 'guitabtooltip' is very similar and is used for the tooltip of the same label.
 337 This only appears when the mouse pointer hovers over the label, thus it
 338 usually is longer.  Only supported on some systems though.
 339
 340 See the 'statusline' option for the format of the value.
 341
 342 The "%N" item can be used for the current tab page number.  The |v:lnum|
 343 variable is also set to this number when the option is evaluated.
 344 The items that use a file name refer to the current window of the tab page.
 345
 346 Note that syntax highlighting is not used for the option.  The %T and %X
 347 items are also ignored.
 348
 349 A simple example that puts the tab page number and the buffer name in the
 350 label: >
 351         :set guitablabel=%N\ %f
 352
 353 An example that resembles the default 'guitablabel': Show the number of
 354 windows in the tab page and a '+' if there is a modified buffer: >
 355
 356         function GuiTabLabel()
 357           let label = ''
 358           let bufnrlist = tabpagebuflist(v:lnum)
 359
 360           " Add '+' if one of the buffers in the tab page is modified
 361           for bufnr in bufnrlist
 362             if getbufvar(bufnr, "&modified")
 363               let label = '+'
 364               break
 365             endif
 366           endfor
 367
 368           " Append the number of windows in the tab page if more than one
 369           let wincount = tabpagewinnr(v:lnum, '$')
 370           if wincount > 1
 371             let label .= wincount
 372           endif
 373           if label != ''
 374             let label .= ' '
 375           endif
 376
 377           " Append the buffer name
 378           return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])
 379         endfunction
 380
 381         set guitablabel=%{GuiTabLabel()}
 382
 383 Note that the function must be defined before setting the option, otherwise
 384 you get an error message for the function not being known.
 385
 386 If you want to fall back to the default label, return an empty string.
 387
 388 If you want to show something specific for a tab page, you might want to use a
 389 tab page local variable. |t:var|
 390
 391
 392  vim:tw=78:ts=8:ft=help:norl: