diff options
Diffstat (limited to 'runtime/doc/tabpage.txt')
| -rw-r--r-- | runtime/doc/tabpage.txt | 483 |
1 files changed, 483 insertions, 0 deletions
diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt new file mode 100644 index 0000000..a010e2f --- /dev/null +++ b/runtime/doc/tabpage.txt @@ -0,0 +1,483 @@ +*tabpage.txt* For Vim version 9.0. Last change: 2022 Feb 02 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Editing with windows in multiple tab pages. *tab-page* *tabpage* + +The commands which have been added to use multiple tab pages are explained +here. Additionally, there are explanations for commands that work differently +when used in combination with more than one tab page. + +1. Introduction |tab-page-intro| +2. Commands |tab-page-commands| +3. Other items |tab-page-other| +4. Setting 'tabline' |setting-tabline| +5. Setting 'guitablabel' |setting-guitablabel| + +{not able to use multiple tab pages when the |+windows| feature was disabled +at compile time} + +============================================================================== +1. Introduction *tab-page-intro* + +A tab page holds one or more windows. You can easily switch between tab +pages, so that you have several collections of windows to work on different +things. + +Usually you will see a list of labels at the top of the Vim window, one for +each tab page. With the mouse you can click on the label to jump to that tab +page. There are other ways to move between tab pages, see below. + +Most commands work only in the current tab page. That includes the |CTRL-W| +commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier). +The commands that are aware of other tab pages than the current one are +mentioned below. + +Tabs are also a nice way to edit a buffer temporarily without changing the +current window layout. Open a new tab page, do whatever you want to do and +close the tab page. + +============================================================================== +2. Commands *tab-page-commands* + +OPENING A NEW TAB PAGE: + +When starting Vim "vim -p filename ..." opens each file argument in a separate +tab page (up to 'tabpagemax'). See |-p| + +A double click with the mouse in the non-GUI tab pages line opens a new, empty +tab page. It is placed left of the position of the click. The first click +may select another tab page first, causing an extra screen update. + +This also works in a few GUI versions, esp. Win32 and Motif. But only when +clicking right of the labels. + +In the GUI tab pages line you can use the right mouse button to open menu. +|tabline-menu|. + +For the related autocommands see |tabnew-autocmd|. + +:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew* +:[count]tabnew + Open a new tab page with an empty window, after the current + tab page. If [count] is given the new tab page appears after + the tab page [count] otherwise the new tab page will appear + after the current one. > + :tabnew " opens tabpage after the current one + :.tabnew " as above + :+tabnew " opens tabpage after the next tab page + " note: it is one further than :tabnew + :-tabnew " opens tabpage before the current one + :0tabnew " opens tabpage before the first one + :$tabnew " opens tabpage after the last one + +:[count]tabe[dit] [++opt] [+cmd] {file} +:[count]tabnew [++opt] [+cmd] {file} + Open a new tab page and edit {file}, like with |:edit|. + For [count] see |:tabnew| above. + +:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind* + Open a new tab page and edit {file} in 'path', like with + |:find|. For [count] see |:tabnew| above. + +:[count]tab {cmd} *:tab* + Execute {cmd} and when it opens a new window open a new tab + page instead. Doesn't work for |:diffsplit|, |:diffpatch|, + |:execute| and |:normal|. + If [count] is given the new tab page appears after the tab + page [count] otherwise the new tab page will appear after the + current one. + Examples: > + :tab split " opens current buffer in new tab page + :tab help gt " opens tab page with help for "gt" + :.tab help gt " as above + :+tab help " opens tab page with help after the next + " tab page + :-tab help " opens tab page with help before the + " current one + :0tab help " opens tab page with help before the + " first one + :$tab help " opens tab page with help after the last + " one + +CTRL-W gf Open a new tab page and edit the file name under the cursor. + See |CTRL-W_gf|. + +CTRL-W gF Open a new tab page and edit the file name under the cursor + and jump to the line number following the file name. + See |CTRL-W_gF|. + +CLOSING A TAB PAGE: + +Closing the last window of a tab page closes the tab page too, unless there is +only one tab page. + +Using the mouse: If the tab page line is displayed you can click in the "X" at +the top right to close the current tab page. A custom |'tabline'| may show +something else. + + *:tabc* *:tabclose* +:tabc[lose][!] Close current tab page. + This command fails when: + - There is only one tab page on the screen. *E784* + - When 'hidden' is not set, [!] is not used, a buffer has + changes, and there is no other window on this buffer. + Changes to the buffer are not written and won't get lost, so + this is a "safe" command. > + :tabclose " close the current tab page + +:{count}tabc[lose][!] +:tabc[lose][!] {count} + Close tab page {count}. Fails in the same way as `:tabclose` + above. > + :-tabclose " close the previous tab page + :+tabclose " close the next tab page + :1tabclose " close the first tab page + :$tabclose " close the last tab page + :tabclose -2 " close the 2nd previous tab page + :tabclose + " close the next tab page + :tabclose 3 " close the third tab page + :tabclose $ " close the last tab page + :tabclose # " close the last accessed tab page + +When a tab is closed the next tab page will become the current one. + + *:tabo* *:tabonly* +:tabo[nly][!] Close all other tab pages. + When the 'hidden' option is set, all buffers in closed windows + become hidden. + When 'hidden' is not set, and the 'autowrite' option is set, + modified buffers are written. Otherwise, windows that have + buffers that are modified are not removed, unless the [!] is + given, then they become hidden. But modified buffers are + never abandoned, so changes cannot get lost. > + :tabonly " close all tab pages except the current + " one + +:{count}tabo[nly][!] +:tabo[nly][!] {count} + Close all tab pages except {count} one. > + :.tabonly " as above + :-tabonly " close all tab pages except the previous + " one + :+tabonly " close all tab pages except the next one + :1tabonly " close all tab pages except the first one + :$tabonly " close all tab pages except the last one + :tabonly - " close all tab pages except the previous + " one + :tabonly +2 " close all tab pages except the two next + " one + :tabonly 1 " close all tab pages except the first one + :tabonly $ " close all tab pages except the last one + :tabonly # " close all tab pages except the last + " accessed one + + +SWITCHING TO ANOTHER TAB PAGE: + +Using the mouse: If the tab page line is displayed you can click in a tab page +label to switch to that tab page. Click where there is no label to go to the +next tab page. |'tabline'| + +:tabn[ext] *:tabn* *:tabnext* *gt* +<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>* +gt *i_CTRL-<PageDown>* *i_<C-PageDown>* + Go to the next tab page. Wraps around from the last to the + first one. + +:{count}tabn[ext] +:tabn[ext] {count} + Go to tab page {count}. The first tab page has number one. > + :-tabnext " go to the previous tab page + :+tabnext " go to the next tab page + :+2tabnext " go to the two next tab page + :1tabnext " go to the first tab page + :$tabnext " go to the last tab page + :tabnext $ " as above + :tabnext # " go to the last accessed tab page + :tabnext - " go to the previous tab page + :tabnext -1 " as above + :tabnext + " go to the next tab page + :tabnext +1 " as above + +{count}<C-PageDown> +{count}gt Go to tab page {count}. The first tab page has number one. + + +:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN* +:tabN[ext] *:tabNext* *CTRL-<PageUp>* +<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>* +gT Go to the previous tab page. Wraps around from the first one + to the last one. + +:tabp[revious] {count} +:tabN[ext] {count} +{count}<C-PageUp> +{count}gT Go {count} tab pages back. Wraps around from the first one + to the last one. Note that the use of {count} is different + from |:tabnext|, where it is used as the tab page number. + +:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind* +:tabfir[st] Go to the first tab page. + + *:tabl* *:tablast* +:tabl[ast] Go to the last tab page. + + *g<Tab>* *CTRL-W_g<Tab>* *<C-Tab>* +g<Tab> Go to the last accessed tab page. + +Other commands: + *:tabs* +:tabs List the tab pages and the windows they contain. + Shows a ">" for the current window. + Shows a "+" for modified buffers. + For example: + Tab page 1 ~ + + tabpage.txt ~ + ex_docmd.c ~ + Tab page 2 ~ + > main.c ~ + + +REORDERING TAB PAGES: + +:tabm[ove] [N] *:tabm* *:tabmove* +:[N]tabm[ove] + Move the current tab page to after tab page N. Use zero to + make the current tab page the first one. N is counted before + the move, thus if the second tab is the current one, + `:tabmove 1` and `:tabmove 2` have no effect. + Without N the tab page is made the last one. > + :.tabmove " do nothing + :-tabmove " move the tab page to the left + :+tabmove " move the tab page to the right + :0tabmove " move the tab page to the beginning of the tab + " list + :tabmove 0 " as above + :tabmove " move the tab page to the last + :$tabmove " as above + :tabmove $ " as above + :tabmove # " move the tab page after the last accessed + " tab page + +:tabm[ove] +[N] +:tabm[ove] -[N] + Move the current tab page N places to the right (with +) or to + the left (with -). > + :tabmove - " move the tab page to the left + :tabmove -1 " as above + :tabmove + " move the tab page to the right + :tabmove +1 " as above + + +Note that although it is possible to move a tab behind the N-th one by using +:Ntabmove. And move it by N places by using :+Ntabmove. For clarification what ++N means in this context see |[range]|. + + +LOOPING OVER TAB PAGES: + + *:tabd* *:tabdo* +:[range]tabd[o] {cmd} + Execute {cmd} in each tab page or if [range] is given only in + tab pages which tab page number is in the [range]. It works + like doing this: > + :tabfirst + :{cmd} + :tabnext + :{cmd} + etc. +< This only operates in the current window of each tab page. + When an error is detected on one tab page, further tab pages + will not be visited. + The last tab page (or where an error occurred) becomes the + current tab page. + {cmd} can contain '|' to concatenate several commands. + {cmd} must not open or close tab pages or reorder them. + Also see |:windo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, |:cfdo| + and |:lfdo| + +============================================================================== +3. Other items *tab-page-other* + + *tabline-menu* +The GUI tab pages line has a popup menu. It is accessed with a right click. +The entries are: + Close Close the tab page under the mouse pointer. The + current one if there is no label under the mouse + pointer. + New Tab Open a tab page, editing an empty buffer. It appears + to the left of the mouse pointer. + Open Tab... Like "New Tab" and additionally use a file selector to + select a file to edit. + +Diff mode works per tab page. You can see the diffs between several files +within one tab page. Other tab pages can show differences between other +files. + +Variables local to a tab page start with "t:". |tabpage-variable| + +Currently there is only one option local to a tab page: 'cmdheight'. + + *tabnew-autocmd* +The TabLeave and TabEnter autocommand events can be used to do something when +switching from one tab page to another. The exact order depends on what you +are doing. When creating a new tab page this works as if you create a new +window on the same buffer and then edit another buffer. Thus ":tabnew" +triggers: + WinLeave leave current window + TabLeave leave current tab page + WinEnter enter window in new tab page + TabEnter enter new tab page + BufLeave leave current buffer + BufEnter enter new empty buffer + +When switching to another tab page the order is: + BufLeave + WinLeave + TabLeave + TabEnter + WinEnter + BufEnter + +============================================================================== +4. Setting 'tabline' *setting-tabline* + +The 'tabline' option specifies what the line with tab pages labels looks like. +It is only used when there is no GUI tab line. + +You can use the 'showtabline' option to specify when you want the line with +tab page labels to appear: never, when there is more than one tab page or +always. + +The highlighting of the tab pages line is set with the groups TabLine +TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill| + +A "+" will be shown for a tab page that has a modified window. The number of +windows in a tabpage is also shown. Thus "3+" means three windows and one of +them has a modified buffer. + +The 'tabline' option allows you to define your preferred way to tab pages +labels. This isn't easy, thus an example will be given here. + +For basics see the 'statusline' option. The same items can be used in the +'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and +|tabpagewinnr()| functions are useful. + +Since the number of tab labels will vary, you need to use an expression for +the whole option. Something like: > + :set tabline=%!MyTabLine() + +Then define the MyTabLine() function to list all the tab pages labels. A +convenient method is to split it in two parts: First go over all the tab +pages and define labels for them. Then get the label for each tab page. > + + function MyTabLine() + let s = '' + for i in range(tabpagenr('$')) + " select the highlighting + if i + 1 == tabpagenr() + let s ..= '%#TabLineSel#' + else + let s ..= '%#TabLine#' + endif + + " set the tab page number (for mouse clicks) + let s ..= '%' .. (i + 1) .. 'T' + + " the label is made by MyTabLabel() + let s ..= ' %{MyTabLabel(' .. (i + 1) .. ')} ' + endfor + + " after the last tab fill with TabLineFill and reset tab page nr + let s ..= '%#TabLineFill#%T' + + " right-align the label to close the current tab page + if tabpagenr('$') > 1 + let s ..= '%=%#TabLine#%999Xclose' + endif + + return s + endfunction + +Now the MyTabLabel() function is called for each tab page to get its label. > + + function MyTabLabel(n) + let buflist = tabpagebuflist(a:n) + let winnr = tabpagewinnr(a:n) + return bufname(buflist[winnr - 1]) + endfunction + +This is just a simplistic example that results in a tab pages line that +resembles the default, but without adding a + for a modified buffer or +truncating the names. You will want to reduce the width of labels in a +clever way when there is not enough room. Check the 'columns' option for the +space available. + +============================================================================== +5. Setting 'guitablabel' *setting-guitablabel* + +When the GUI tab pages line is displayed, 'guitablabel' can be used to +specify the label to display for each tab page. Unlike 'tabline', which +specifies the whole tab pages line at once, 'guitablabel' is used for each +label separately. + +'guitabtooltip' is very similar and is used for the tooltip of the same label. +This only appears when the mouse pointer hovers over the label, thus it +usually is longer. Only supported on some systems though. + +See the 'statusline' option for the format of the value. + +The "%N" item can be used for the current tab page number. The |v:lnum| +variable is also set to this number when the option is evaluated. +The items that use a file name refer to the current window of the tab page. + +Note that syntax highlighting is not used for the option. The %T and %X +items are also ignored. + +A simple example that puts the tab page number and the buffer name in the +label: > + :set guitablabel=%N\ %f + +An example that resembles the default 'guitablabel': Show the number of +windows in the tab page and a '+' if there is a modified buffer: > + + function GuiTabLabel() + let label = '' + let bufnrlist = tabpagebuflist(v:lnum) + + " Add '+' if one of the buffers in the tab page is modified + for bufnr in bufnrlist + if getbufvar(bufnr, "&modified") + let label = '+' + break + endif + endfor + + " Append the number of windows in the tab page if more than one + let wincount = tabpagewinnr(v:lnum, '$') + if wincount > 1 + let label ..= wincount + endif + if label != '' + let label ..= ' ' + endif + + " Append the buffer name + return label .. bufname(bufnrlist[tabpagewinnr(v:lnum) - 1]) + endfunction + + set guitablabel=%{GuiTabLabel()} + +Note that the function must be defined before setting the option, otherwise +you get an error message for the function not being known. + +If you want to fall back to the default label, return an empty string. + +If you want to show something specific for a tab page, you might want to use a +tab page local variable. |t:var| + + + vim:tw=78:ts=8:noet:ft=help:norl: |