home *** CD-ROM | disk | FTP | other *** search
/ vim.ftp.fu-berlin.de / 2015-02-03.vim.ftp.fu-berlin.de.tar / vim.ftp.fu-berlin.de / runtime / dos / doc / tabpage.txt < prev    next >
Encoding:
Text File  |  2010-08-15  |  13.3 KB  |  383 lines
  1. *tabpage.txt*   For Vim version 7.3.  Last change: 2010 Jul 31
  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.         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.  
  181. LOOPING 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. ==============================================================================
  203. 3. Other items                        *tab-page-other*
  204.  
  205.                             *tabline-menu*
  206. The GUI tab pages line has a popup menu.  It is accessed with a right click.
  207. The 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.  
  216. Diff mode works per tab page.  You can see the diffs between several files
  217. within one tab page.  Other tab pages can show differences between other
  218. files.
  219.  
  220. Variables local to a tab page start with "t:". |tabpage-variable|
  221.  
  222. Currently there is only one option local to a tab page: 'cmdheight'.
  223.  
  224. The TabLeave and TabEnter autocommand events can be used to do something when
  225. switching from one tab page to another.  The exact order depends on what you
  226. are doing.  When creating a new tab page this works as if you create a new
  227. window on the same buffer and then edit another buffer.  Thus ":tabnew"
  228. triggers:
  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.  
  236. When switching to another tab page the order is:
  237.     BufLeave
  238.     WinLeave
  239.     TabLeave
  240.     TabEnter
  241.     WinEnter
  242.     BufEnter
  243.  
  244. ==============================================================================
  245. 4. Setting 'tabline'                    *setting-tabline*
  246.  
  247. The 'tabline' option specifies what the line with tab pages labels looks like.
  248. It is only used when there is no GUI tab line.
  249.  
  250. You can use the 'showtabline' option to specify when you want the line with
  251. tab page labels to appear: never, when there is more than one tab page or
  252. always.
  253.  
  254. The highlighting of the tab pages line is set with the groups TabLine
  255. TabLineSel and TabLineFill.  |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
  256.  
  257. A "+" will be shown for a tab page that has a modified window.  The number of
  258. windows in a tabpage is also shown.  Thus "3+" means three windows and one of
  259. them has a modified buffer.
  260.  
  261. The 'tabline' option allows you to define your preferred way to tab pages
  262. labels.  This isn't easy, thus an example will be given here.
  263.  
  264. For 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.  
  268. Since the number of tab labels will vary, you need to use an expression for
  269. the whole option.  Something like: >
  270.     :set tabline=%!MyTabLine()
  271.  
  272. Then define the MyTabLine() function to list all the tab pages labels.  A
  273. convenient method is to split it in two parts:  First go over all the tab
  274. pages 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.  
  304. Now 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.  
  312. This is just a simplistic example that results in a tab pages line that
  313. resembles the default, but without adding a + for a modified buffer or
  314. truncating the names.  You will want to reduce the width of labels in a
  315. clever way when there is not enough room.  Check the 'columns' option for the
  316. space available.
  317.  
  318. ==============================================================================
  319. 5. Setting 'guitablabel'                *setting-guitablabel*
  320.  
  321. When the GUI tab pages line is displayed, 'guitablabel' can be used to
  322. specify the label to display for each tab page.  Unlike 'tabline', which
  323. specifies the whole tab pages line at once, 'guitablabel' is used for each
  324. label separately.
  325.  
  326. 'guitabtooltip' is very similar and is used for the tooltip of the same label.
  327. This only appears when the mouse pointer hovers over the label, thus it
  328. usually is longer.  Only supported on some systems though.
  329.  
  330. See the 'statusline' option for the format of the value.
  331.  
  332. The "%N" item can be used for the current tab page number.  The |v:lnum|
  333. variable is also set to this number when the option is evaluated.
  334. The items that use a file name refer to the current window of the tab page.
  335.  
  336. Note that syntax highlighting is not used for the option.  The %T and %X
  337. items are also ignored.
  338.  
  339. A simple example that puts the tab page number and the buffer name in the
  340. label: >
  341.     :set guitablabel=%N\ %f
  342.  
  343. An example that resembles the default 'guitablabel': Show the number of
  344. windows 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.  
  373. Note that the function must be defined before setting the option, otherwise
  374. you get an error message for the function not being known.
  375.  
  376. If you want to fall back to the default label, return an empty string.
  377.  
  378. If you want to show something specific for a tab page, you might want to use a
  379. tab page local variable. |t:var|
  380.  
  381.  
  382.  vim:tw=78:ts=8:ft=help:norl:
  383.