runtime/doc/tabpage.txt

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