blob: e0e8b17ede2bbf11d95a8982bd0cec61515051ed [file] [log] [blame]
Bram Moolenaar030f0df2006-02-21 22:02:53 +00001*tabpage.txt* For Vim version 7.0aa. Last change: 2006 Feb 21
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 Moolenaar7e8fd632006-02-18 22:14:51 +000017
18{Vi does not have any of these commands}
19{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|
34commands, |:windo|, |:all| and |:ball|. The commands that are aware of
35other tab pages than the current one are mentioned below.
36
37Tabs are also a nice way to edit a buffer temporarily without changing the
38current window layout. Open a new tab page, do whatever you want to do and
39close the tab page.
40
41==============================================================================
422. Commands *tab-page-commands*
43
44OPENING A NEW TAB PAGE:
45
46When starting Vim "vim -p filename ..." opens each file argument in a separate
47tab page (up to 10). |-p|
48
Bram Moolenaar2a0449d2006-02-20 21:27:21 +000049:tabe[dit] *:tabe* *:tabedit* *:tabn* *:tabnew*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000050:tabn[ew] Open a new tab page with an empty window.
51
52:tabe[dit] [++opt] [+cmd] {file}
53:tabn[ew] [++opt] [+cmd] {file}
54 Open a new tab page and edit {file}, like with |:edit|.
55
Bram Moolenaar2a0449d2006-02-20 21:27:21 +000056:tabf[ind] [++opt] [+cmd] {file} *:tabf* *:tabfind*
Bram Moolenaar7e8fd632006-02-18 22:14:51 +000057 Open a new tab page and edit {file} in 'path', like with
58 |:find|.
59 {not available when the |+file_in_path| feature was disabled
60 at compile time}
61
62
63CLOSING A TAB PAGE:
64
65Using |:close| in the last window of a tab page closes it.
66
67Using the mouse: If the tab page line is displayed you can click in the "X" at
68the top right to close the current tab page. |'tabline'|
69
70 *:tabc* *:tabclose*
71:tabc[lose][!] Close current tab page.
72 This command fails when:
73 - There is only one tab page on the screen. *E784*
74 - When 'hidden' is not set, [!] is not used, a buffer has
75 changes, and there is no other window on this buffer.
76 Changes to the buffer are not written and won't get lost, so
77 this is a "safe" command.
78
79:tabc[lose][!] {count}
80 Close tab page {count}. Fails in the same way as ':tabclose"
81 above.
82
83 *:tabo* *:tabonly*
84:tabo[nly][!] Close all other tab pages.
85 When the 'hidden' option is set, all buffers in closed windows
86 become hidden.
87 When 'hidden' is not set, and the 'autowrite' option is set,
88 modified buffers are written. Otherwise, windows that have
89 buffers that are modified are not removed, unless the [!] is
90 given, then they become hidden. But modified buffers are
91 never abandoned, so changes cannot get lost.
92
93
94SWITCHING TO ANOTHER TAB PAGE:
95
96Using the mouse: If the tab page line is displayed you can click in a tab page
97label to switch to that tab page. |'tabline'|
98
99:tab *:tab* *gt*
100gt Go to the next tab page. Wraps around from the last to the
101 first one.
102
103:tab {count}
104{count}gt Go to tab page {count}. The first tab page has number one.
105
106
107Other commands:
108 *:tabs*
109:tabs List the tab pages and the windows they contain. Shows a "+"
110 for modified buffers.
111
112==============================================================================
1133. Other items *tab-page-other*
114
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000115Diff mode works per tab page. You can see the diffs between several files
116within one tab page. Other tab pages can show differences between other
117files.
118
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000119The TabLeave and TabEnter autocommand events can be used to do something when
120switching from one tab page to another. The exact order depends on what you
121are doing. When creating a new tab page this works as if you create a new
122window on the same buffer and then edit another buffer. Thus ":tabnew"
123triggers:
124 WinLeave leave current window
125 TabLeave leave current tab page
126 TabEnter enter new tab page
127 WinEnter enter window in new tab page
128 BufLeave leave current buffer
129 BufEnter enter new empty buffer
130
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000131When switching to another tab page the order is:
Bram Moolenaar2a0449d2006-02-20 21:27:21 +0000132 BufLeave
133 WinLeave
134 TabLeave
135 TabEnter
136 WinEnter
137 BufEnter
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000138
Bram Moolenaar030f0df2006-02-21 22:02:53 +0000139==============================================================================
1404. Setting 'tabline' *setting-tabline*
141
142You can use the 'showtabline' option to specify when you want the line with
143tab page labels to appear: never, when there is more than one tab page or
144always.
145
146The highlighting of the tab pages line is set with the groups TabLine
147TabLineSel and TabLineFill. |hl-TabLine| |hl-TabLineSel| |hl-TabLineFill|
148
149The 'tabline' option allows you to define your preferred way to tab pages
150labels. This isn't easy, thus an example will be given here.
151
152For basics see the 'statusline' option. The same items can be used in the
153'tabline' option. Additionally, the |tabpagebuflist()|, |tabpagenr()| and
154|tabpagewinnr()| functions are useful.
155
156Since the number of tab labels will vary, you need to use an expresion for the
157whole option. Something like: >
158 :set tabline=%!MyTabLine()
159
160Then define the MyTabLine() function to list all the tab pages labels. A
161convenient method is to split it in two parts: First go over all the tab
162pages and define labels for them. Then get the label for each tab page. >
163
164 function MyTabLine()
165 let s = ''
166 for i in range(tabpagenr('$'))
167 if i + 1 == tabpagenr()
168 let s .= '%#TabLineSel#'
169 else
170 let s .= '%#TabLine#'
171 endif
172 let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
173 endfor
174 let s .= '%#TabLineFill#'
175 return s
176 endfunction
177
178Now the MyTabLabel() function is called for each tab page to get its label. >
179
180 function MyTabLabel(n)
181 let buflist = tabpagebuflist(a:n)
182 let winnr = tabpagewinnr(a:n)
183 return bufname(buflist[winnr - 1])
184 endfunction
185
186This is just a simplistic example that results in a tab pages line that
187resembles the default, but without adding a + for a modified buffer or
188trunctating the names. You will want to reduce the width of labels in a
189clever way when there is not enough room. Check the 'columns' option for the
190space available, keeping in mind that the "X" at the right will take one more
191position.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000192
193 vim:tw=78:ts=8:ft=help:norl: