blob: 2f6d8e9aadf27f92fa456e625946ebbdfc1828ba [file] [log] [blame]
Bram Moolenaar98056532019-12-12 14:18:35 +01001*tabpage.txt* For Vim version 8.2. Last change: 2019 May 05
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar2a0449d2006-02-20 21:27:21 +00007Editing with windows in multiple tab pages. *tab-page* *tabpage*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008
9The commands which have been added to use multiple tab pages are explained
10here. Additionally, there are explanations for commands that work differently
11when used in combination with more than one tab page.
12
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000131. Introduction |tab-page-intro|
142. Commands |tab-page-commands|
153. Other items |tab-page-other|
164. Setting 'tabline' |setting-tabline|
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000175. Setting 'guitablabel' |setting-guitablabel|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000018
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000019{not able to use multiple tab pages when the |+windows| feature was disabled
20at compile time}
21
22==============================================================================
231. Introduction *tab-page-intro*
24
25A tab page holds one or more windows. You can easily switch between tab
26pages, so that you have several collections of windows to work on different
27things.
28
29Usually you will see a list of labels at the top of the Vim window, one for
30each tab page. With the mouse you can click on the label to jump to that tab
31page. There are other ways to move between tab pages, see below.
32
33Most commands work only in the current tab page. That includes the |CTRL-W|
Bram Moolenaare1438bb2006-03-01 22:01:55 +000034commands, |:windo|, |:all| and |:ball| (when not using the |:tab| modifier).
35The commands that are aware of other tab pages than the current one are
36mentioned below.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000037
38Tabs are also a nice way to edit a buffer temporarily without changing the
39current window layout. Open a new tab page, do whatever you want to do and
40close the tab page.
41
42==============================================================================
432. Commands *tab-page-commands*
44
45OPENING A NEW TAB PAGE:
46
47When starting Vim "vim -p filename ..." opens each file argument in a separate
Bram Moolenaar58f0a1f2010-07-17 16:30:42 +020048tab page (up to 'tabpagemax'). See |-p|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000049
Bram Moolenaarbfb2d402006-03-03 22:50:42 +000050A double click with the mouse in the non-GUI tab pages line opens a new, empty
51tab page. It is placed left of the position of the click. The first click
52may select another tab page first, causing an extra screen update.
53
Bram Moolenaarf193fff2006-04-27 00:02:13 +000054This also works in a few GUI versions, esp. Win32 and Motif. But only when
55clicking right of the labels.
56
Bram Moolenaarbfb2d402006-03-03 22:50:42 +000057In the GUI tab pages line you can use the right mouse button to open menu.
58|tabline-menu|.
Bram Moolenaar80a94a52006-02-23 21:26:58 +000059
Bram Moolenaar46fceaa2016-10-23 21:21:08 +020060For the related autocommands see |tabnew-autocmd|.
61
Bram Moolenaara26559b2010-07-31 14:59:19 +020062:[count]tabe[dit] *:tabe* *:tabedit* *:tabnew*
63:[count]tabnew
64 Open a new tab page with an empty window, after the current
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010065 tab page. If [count] is given the new tab page appears after
66 the tab page [count] otherwise the new tab page will appear
67 after the current one. >
68 :tabnew " opens tabpage after the current one
69 :.tabnew " as above
70 :+tabnew " opens tabpage after the next tab page
71 " note: it is one further than :tabnew
72 :-tabnew " opens tabpage before the current one
73 :0tabnew " opens tabpage before the first one
74 :$tabnew " opens tabpage after the last one
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000075
Bram Moolenaara26559b2010-07-31 14:59:19 +020076:[count]tabe[dit] [++opt] [+cmd] {file}
77:[count]tabnew [++opt] [+cmd] {file}
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000078 Open a new tab page and edit {file}, like with |:edit|.
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010079 For [count] see |:tabnew| above.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000080
Bram Moolenaara26559b2010-07-31 14:59:19 +020081:[count]tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000082 Open a new tab page and edit {file} in 'path', like with
Bram Moolenaarb96a7f32014-11-27 16:22:48 +010083 |:find|. For [count] see |:tabnew| above.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000084 {not available when the |+file_in_path| feature was disabled
85 at compile time}
86
Bram Moolenaar80a94a52006-02-23 21:26:58 +000087:[count]tab {cmd} *:tab*
88 Execute {cmd} and when it opens a new window open a new tab
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +000089 page instead. Doesn't work for |:diffsplit|, |:diffpatch|,
90 |:execute| and |:normal|.
Bram Moolenaar9b7f8ce2016-08-21 19:07:17 +020091 If [count] is given the new tab page appears after the tab
92 page [count] otherwise the new tab page will appear after the
93 current one.
Bram Moolenaara26559b2010-07-31 14:59:19 +020094 Examples: >
Bram Moolenaar9b7f8ce2016-08-21 19:07:17 +020095 :tab split " opens current buffer in new tab page
96 :tab help gt " opens tab page with help for "gt"
97 :.tab help gt " as above
98 :+tab help " opens tab page with help after the next
99 " tab page
100 :-tab help " opens tab page with help before the
101 " current one
102 :0tab help " opens tab page with help before the
103 " first one
104 :$tab help " opens tab page with help after the last
105 " one
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000106
Bram Moolenaar8dff8182006-04-06 20:18:50 +0000107CTRL-W gf Open a new tab page and edit the file name under the cursor.
108 See |CTRL-W_gf|.
109
Bram Moolenaar57657d82006-04-21 22:12:41 +0000110CTRL-W gF Open a new tab page and edit the file name under the cursor
111 and jump to the line number following the file name.
112 See |CTRL-W_gF|.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000113
114CLOSING A TAB PAGE:
115
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000116Closing the last window of a tab page closes the tab page too, unless there is
117only one tab page.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000118
119Using the mouse: If the tab page line is displayed you can click in the "X" at
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000120the top right to close the current tab page. A custom |'tabline'| may show
121something else.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000122
123 *:tabc* *:tabclose*
124:tabc[lose][!] Close current tab page.
125 This command fails when:
126 - There is only one tab page on the screen. *E784*
127 - When 'hidden' is not set, [!] is not used, a buffer has
128 changes, and there is no other window on this buffer.
129 Changes to the buffer are not written and won't get lost, so
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100130 this is a "safe" command. >
131 :tabclose " close the current tab page
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000132
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100133:{count}tabc[lose][!]
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000134:tabc[lose][!] {count}
Bram Moolenaar9b451252012-08-15 17:43:31 +0200135 Close tab page {count}. Fails in the same way as `:tabclose`
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100136 above. >
137 :-tabclose " close the previous tab page
138 :+tabclose " close the next tab page
139 :1tabclose " close the first tab page
140 :$tabclose " close the last tab page
Bram Moolenaar3df01732017-02-17 22:47:16 +0100141 :tabclose -2 " close the two previous tab page
142 :tabclose + " close the next tab page
143 :tabclose 3 " close the third tab page
144 :tabclose $ " close the last tab page
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100145<
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000146 *:tabo* *:tabonly*
147:tabo[nly][!] Close all other tab pages.
148 When the 'hidden' option is set, all buffers in closed windows
149 become hidden.
150 When 'hidden' is not set, and the 'autowrite' option is set,
151 modified buffers are written. Otherwise, windows that have
152 buffers that are modified are not removed, unless the [!] is
153 given, then they become hidden. But modified buffers are
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100154 never abandoned, so changes cannot get lost. >
155 :tabonly " close all tab pages except the current
Bram Moolenaar9b7f8ce2016-08-21 19:07:17 +0200156 " one
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100157
158:{count}tabo[nly][!]
Bram Moolenaar3df01732017-02-17 22:47:16 +0100159:tabo[nly][!] {count}
160 Close all tab pages except {count} one. >
Bram Moolenaar9b7f8ce2016-08-21 19:07:17 +0200161 :.tabonly " as above
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100162 :-tabonly " close all tab pages except the previous
163 " one
164 :+tabonly " close all tab pages except the next one
165 :1tabonly " close all tab pages except the first one
166 :$tabonly " close all tab pages except the last one
Bram Moolenaar3df01732017-02-17 22:47:16 +0100167 :tabonly - " close all tab pages except the previous
168 " one
169 :tabonly +2 " close all tab pages except the two next
170 " one
171 :tabonly 1 " close all tab pages except the first one
172 :tabonly $ " close all tab pages except the last one
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000173
174
175SWITCHING TO ANOTHER TAB PAGE:
176
177Using the mouse: If the tab page line is displayed you can click in a tab page
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000178label to switch to that tab page. Click where there is no label to go to the
179next tab page. |'tabline'|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000180
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000181:tabn[ext] *:tabn* *:tabnext* *gt*
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000182<C-PageDown> *CTRL-<PageDown>* *<C-PageDown>*
183gt *i_CTRL-<PageDown>* *i_<C-PageDown>*
Bram Moolenaar7fc904b2006-04-13 20:37:35 +0000184 Go to the next tab page. Wraps around from the last to the
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000185 first one.
186
Bram Moolenaar3df01732017-02-17 22:47:16 +0100187:{count}tabn[ext]
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000188:tabn[ext] {count}
Bram Moolenaar3df01732017-02-17 22:47:16 +0100189 Go to tab page {count}. The first tab page has number one. >
190 :-tabnext " go to the previous tab page
191 :+tabnext " go to the next tab page
192 :+2tabnext " go to the two next tab page
193 :1tabnext " go to the first tab page
194 :$tabnext " go to the last tab page
195 :tabnext $ " as above
196 :tabnext - " go to the previous tab page
197 :tabnext -1 " as above
198 :tabnext + " go to the next tab page
199 :tabnext +1 " as above
200
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000201{count}<C-PageDown>
202{count}gt Go to tab page {count}. The first tab page has number one.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000203
204
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000205:tabp[revious] *:tabp* *:tabprevious* *gT* *:tabN*
206:tabN[ext] *:tabNext* *CTRL-<PageUp>*
207<C-PageUp> *<C-PageUp>* *i_CTRL-<PageUp>* *i_<C-PageUp>*
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000208gT Go to the previous tab page. Wraps around from the first one
209 to the last one.
210
211:tabp[revious] {count}
212:tabN[ext] {count}
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000213{count}<C-PageUp>
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000214{count}gT Go {count} tab pages back. Wraps around from the first one
Bram Moolenaar0b0f0992018-05-22 21:41:30 +0200215 to the last one. Note that the use of {count} is different
216 from |:tabnext|, where it is used as the tab page number.
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000217
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000218:tabr[ewind] *:tabfir* *:tabfirst* *:tabr* *:tabrewind*
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000219:tabfir[st] Go to the first tab page.
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000220
221 *:tabl* *:tablast*
222:tabl[ast] Go to the last tab page.
223
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000224
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000225Other commands:
226 *:tabs*
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000227:tabs List the tab pages and the windows they contain.
228 Shows a ">" for the current window.
229 Shows a "+" for modified buffers.
Bram Moolenaar7e1479b2016-09-11 15:07:27 +0200230 For example:
231 Tab page 1 ~
232 + tabpage.txt ~
233 ex_docmd.c ~
234 Tab page 2 ~
235 > main.c ~
Bram Moolenaar80a94a52006-02-23 21:26:58 +0000236
237
238REORDERING TAB PAGES:
239
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000240:tabm[ove] [N] *:tabm* *:tabmove*
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200241:[N]tabm[ove]
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000242 Move the current tab page to after tab page N. Use zero to
Bram Moolenaard473c8c2018-08-11 18:00:22 +0200243 make the current tab page the first one. N is counted before
244 the move, thus if the second tab is the current one,
Bram Moolenaarfc65cab2018-08-28 22:58:02 +0200245 `:tabmove 1` and `:tabmove 2` have no effect.
Bram Moolenaard473c8c2018-08-11 18:00:22 +0200246 Without N the tab page is made the last one. >
Bram Moolenaar40ce3a42015-04-21 18:08:39 +0200247 :.tabmove " do nothing
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100248 :-tabmove " move the tab page to the left
Bram Moolenaar40ce3a42015-04-21 18:08:39 +0200249 :+tabmove " move the tab page to the right
Bram Moolenaara162bc52015-01-07 16:54:21 +0100250 :0tabmove " move the tab page to the beginning of the tab
Bram Moolenaarb96a7f32014-11-27 16:22:48 +0100251 " list
Bram Moolenaar40ce3a42015-04-21 18:08:39 +0200252 :tabmove 0 " as above
253 :tabmove " move the tab page to the last
254 :$tabmove " as above
255 :tabmove $ " as above
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000256
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200257:tabm[ove] +[N]
258:tabm[ove] -[N]
259 Move the current tab page N places to the right (with +) or to
Bram Moolenaar40ce3a42015-04-21 18:08:39 +0200260 the left (with -). >
261 :tabmove - " move the tab page to the left
262 :tabmove -1 " as above
263 :tabmove + " move the tab page to the right
264 :tabmove +1 " as above
265
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200266
267Note that although it is possible to move a tab behind the N-th one by using
Bram Moolenaar40ce3a42015-04-21 18:08:39 +0200268:Ntabmove. And move it by N places by using :+Ntabmove. For clarification what
269+N means in this context see |[range]|.
Bram Moolenaar8cb8dca2012-07-06 18:27:39 +0200270
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000271
272LOOPING OVER TAB PAGES:
273
274 *:tabd* *:tabdo*
Bram Moolenaara162bc52015-01-07 16:54:21 +0100275:[range]tabd[o] {cmd}
276 Execute {cmd} in each tab page or if [range] is given only in
277 tab pages which tab page number is in the [range]. It works
278 like doing this: >
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000279 :tabfirst
280 :{cmd}
281 :tabnext
282 :{cmd}
283 etc.
284< This only operates in the current window of each tab page.
285 When an error is detected on one tab page, further tab pages
286 will not be visited.
287 The last tab page (or where an error occurred) becomes the
288 current tab page.
289 {cmd} can contain '|' to concatenate several commands.
290 {cmd} must not open or close tab pages or reorder them.
Bram Moolenaaraa23b372015-09-08 18:46:31 +0200291 Also see |:windo|, |:argdo|, |:bufdo|, |:cdo|, |:ldo|, |:cfdo|
292 and |:lfdo|
Bram Moolenaar32466aa2006-02-24 23:53:04 +0000293
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000294==============================================================================
2953. Other items *tab-page-other*
296
Bram Moolenaarbfb2d402006-03-03 22:50:42 +0000297 *tabline-menu*
298The GUI tab pages line has a popup menu. It is accessed with a right click.
299The entries are:
300 Close Close the tab page under the mouse pointer. The
301 current one if there is no label under the mouse
302 pointer.
303 New Tab Open a tab page, editing an empty buffer. It appears
304 to the left of the mouse pointer.
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000305 Open Tab... Like "New Tab" and additionally use a file selector to
Bram Moolenaarbfb2d402006-03-03 22:50:42 +0000306 select a file to edit.
307
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000308Diff mode works per tab page. You can see the diffs between several files
309within one tab page. Other tab pages can show differences between other
310files.
311
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000312Variables local to a tab page start with "t:". |tabpage-variable|
313
Bram Moolenaarc6fe9192006-04-09 21:54:49 +0000314Currently there is only one option local to a tab page: 'cmdheight'.
315
Bram Moolenaar46fceaa2016-10-23 21:21:08 +0200316 *tabnew-autocmd*
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000317The TabLeave and TabEnter autocommand events can be used to do something when
318switching from one tab page to another. The exact order depends on what you
319are doing. When creating a new tab page this works as if you create a new
320window on the same buffer and then edit another buffer. Thus ":tabnew"
321triggers:
322 WinLeave leave current window
323 TabLeave leave current tab page
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000324 WinEnter enter window in new tab page
Bram Moolenaara162bc52015-01-07 16:54:21 +0100325 TabEnter enter new tab page
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000326 BufLeave leave current buffer
327 BufEnter enter new empty buffer
328
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000329When switching to another tab page the order is:
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000330 BufLeave
331 WinLeave
332 TabLeave
333 TabEnter
334 WinEnter
335 BufEnter
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000336
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000337==============================================================================
3384. Setting 'tabline' *setting-tabline*
339
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000340The 'tabline' option specifies what the line with tab pages labels looks like.
341It is only used when there is no GUI tab line.
342
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000343You can use the 'showtabline' option to specify when you want the line with
344tab page labels to appear: never, when there is more than one tab page or
345always.
346
347The highlighting of the tab pages line is set with the groups TabLine
348TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
349
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000350A "+" will be shown for a tab page that has a modified window. The number of
351windows in a tabpage is also shown. Thus "3+" means three windows and one of
352them has a modified buffer.
353
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000354The 'tabline' option allows you to define your preferred way to tab pages
355labels. This isn't easy, thus an example will be given here.
356
357For basics see the 'statusline' option. The same items can be used in the
358'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and
359|tabpagewinnr()| functions are useful.
360
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000361Since the number of tab labels will vary, you need to use an expression for
362the whole option. Something like: >
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000363 :set tabline=%!MyTabLine()
364
365Then define the MyTabLine() function to list all the tab pages labels. A
366convenient method is to split it in two parts: First go over all the tab
367pages and define labels for them. Then get the label for each tab page. >
368
369 function MyTabLine()
370 let s = ''
371 for i in range(tabpagenr('$'))
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000372 " select the highlighting
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000373 if i + 1 == tabpagenr()
374 let s .= '%#TabLineSel#'
375 else
376 let s .= '%#TabLine#'
377 endif
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000378
379 " set the tab page number (for mouse clicks)
380 let s .= '%' . (i + 1) . 'T'
381
382 " the label is made by MyTabLabel()
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000383 let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
384 endfor
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000385
386 " after the last tab fill with TabLineFill and reset tab page nr
387 let s .= '%#TabLineFill#%T'
388
389 " right-align the label to close the current tab page
390 if tabpagenr('$') > 1
391 let s .= '%=%#TabLine#%999Xclose'
392 endif
393
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000394 return s
395 endfunction
396
397Now the MyTabLabel() function is called for each tab page to get its label. >
398
399 function MyTabLabel(n)
400 let buflist = tabpagebuflist(a:n)
401 let winnr = tabpagewinnr(a:n)
402 return bufname(buflist[winnr - 1])
403 endfunction
404
405This is just a simplistic example that results in a tab pages line that
406resembles the default, but without adding a + for a modified buffer or
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000407truncating the names. You will want to reduce the width of labels in a
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000408clever way when there is not enough room. Check the 'columns' option for the
Bram Moolenaard1f56e62006-02-22 21:25:37 +0000409space available.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000410
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000411==============================================================================
4125. Setting 'guitablabel' *setting-guitablabel*
413
414When the GUI tab pages line is displayed, 'guitablabel' can be used to
415specify the label to display for each tab page. Unlike 'tabline', which
416specifies the whole tab pages line at once, 'guitablabel' is used for each
417label separately.
418
Bram Moolenaar57657d82006-04-21 22:12:41 +0000419'guitabtooltip' is very similar and is used for the tooltip of the same label.
420This only appears when the mouse pointer hovers over the label, thus it
421usually is longer. Only supported on some systems though.
422
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000423See the 'statusline' option for the format of the value.
424
425The "%N" item can be used for the current tab page number. The |v:lnum|
Bram Moolenaar57657d82006-04-21 22:12:41 +0000426variable is also set to this number when the option is evaluated.
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000427The items that use a file name refer to the current window of the tab page.
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000428
Bram Moolenaar57657d82006-04-21 22:12:41 +0000429Note that syntax highlighting is not used for the option. The %T and %X
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000430items are also ignored.
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000431
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000432A simple example that puts the tab page number and the buffer name in the
433label: >
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000434 :set guitablabel=%N\ %f
435
Bram Moolenaar57657d82006-04-21 22:12:41 +0000436An example that resembles the default 'guitablabel': Show the number of
Bram Moolenaardd2a3cd2007-05-05 17:10:09 +0000437windows in the tab page and a '+' if there is a modified buffer: >
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000438
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000439 function GuiTabLabel()
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000440 let label = ''
441 let bufnrlist = tabpagebuflist(v:lnum)
442
443 " Add '+' if one of the buffers in the tab page is modified
444 for bufnr in bufnrlist
445 if getbufvar(bufnr, "&modified")
446 let label = '+'
447 break
448 endif
449 endfor
450
451 " Append the number of windows in the tab page if more than one
452 let wincount = tabpagewinnr(v:lnum, '$')
453 if wincount > 1
454 let label .= wincount
455 endif
456 if label != ''
457 let label .= ' '
458 endif
459
460 " Append the buffer name
461 return label . bufname(bufnrlist[tabpagewinnr(v:lnum) - 1])
462 endfunction
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000463
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000464 set guitablabel=%{GuiTabLabel()}
Bram Moolenaara226a6d2006-02-26 23:59:20 +0000465
466Note that the function must be defined before setting the option, otherwise
467you get an error message for the function not being known.
468
Bram Moolenaard68071d2006-05-02 22:08:30 +0000469If you want to fall back to the default label, return an empty string.
470
471If you want to show something specific for a tab page, you might want to use a
472tab page local variable. |t:var|
473
Bram Moolenaarba6c0522006-02-25 21:45:02 +0000474
Bram Moolenaar91f84f62018-07-29 15:07:52 +0200475 vim:tw=78:ts=8:noet:ft=help:norl: