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