runtime/doc/tabpage.txt

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