*windows.txt* For Vim version 9.1. Last change: 2024 Feb 20
VIM REFERENCE MANUAL by Bram Moolenaar
Editing with multiple windows and buffers. *windows* *buffers*
The commands which have been added to use multiple windows and buffers are
explained here. Additionally, there are explanations for commands that work
differently when used in combination with more than one window.
The basics are explained in chapter 7 and 8 of the user manual |usr_07.txt|
|usr_08.txt|.
1. Introduction |windows-intro|
2. Starting Vim |windows-starting|
3. Opening and closing a window |opening-window|
4. Moving cursor to other windows |window-move-cursor|
5. Moving windows around |window-moving|
6. Window resizing |window-resize|
7. Argument and buffer list commands |buffer-list|
8. Do a command in all buffers or windows |list-repeat|
9. Tag or file name under the cursor |window-tag|
10. The preview window |preview-window|
11. Using hidden buffers |buffer-hidden|
12. Special kinds of buffers |special-buffers|
{not able to use multiple windows when the |+windows| feature was disabled at
compile time}
==============================================================================
1. Introduction *windows-intro* *window*
Summary:
A buffer is the in-memory text of a file.
A window is a viewport on a buffer.
A tab page is a collection of windows.
A window is a viewport onto a buffer. You can use multiple windows on one
buffer, or several windows on different buffers.
A buffer is a file loaded into memory for editing. The original file remains
unchanged until you write the buffer to the file.
A buffer can be in one of three states:
*active-buffer*
active: The buffer is displayed in a window. If there is a file for this
buffer, it has been read into the buffer. The buffer may have been
modified since then and thus be different from the file.
*hidden-buffer*
hidden: The buffer is not displayed. If there is a file for this buffer, it
has been read into the buffer. Otherwise it's the same as an active
buffer, you just can't see it.
*inactive-buffer*
inactive: The buffer is not displayed and does not contain anything. Options
for the buffer are remembered if the file was once loaded. It can
contain marks from the |viminfo| file. But the buffer doesn't
contain text.
In a table:
state displayed loaded ":buffers" ~
in window shows ~
active yes yes 'a'
hidden no yes 'h'
inactive no no ' '
Note: All CTRL-W commands can also be executed with |:wincmd|, for those
places where a Normal mode command can't be used or is inconvenient.
The main Vim window can hold several split windows. There are also tab pages
|tab-page|, each of which can hold multiple windows.
*window-ID* *winid* *windowid*
Each window has a unique identifier called the window ID. This identifier
will not change within a Vim session. The |win_getid()| and |win_id2tabwin()|
functions can be used to convert between the window/tab number and the
identifier. There is also the window number, which may change whenever
windows are opened or closed, see |winnr()|.
The window number is only valid in one specific tab. The window ID is valid
across tabs. For most functions that take a window ID or a window number, the
window number only applies to the current tab, while the window ID can refer
to a window in any tab.
Each buffer has a unique number and the number will not change within a Vim
session. The |bufnr()| and |bufname()| functions can be used to convert
between a buffer name and the buffer number.
==============================================================================
2. Starting Vim *windows-starting*
By default, Vim starts with one window, just like Vi.
The "-o" and "-O" arguments to Vim can be used to open a window for each file
in the argument list. The "-o" argument will split the windows horizontally;
the "-O" argument will split the windows vertically. If both "-o" and "-O"
are given, the last one encountered will be used to determine the split
orientation. For example, this will open three windows, split horizontally: >
vim -o file1 file2 file3
"-oN", where N is a decimal number, opens N windows split horizontally. If
there are more file names than windows, only N windows are opened and some
files do not get a window. If there are more windows than file names, the
last few windows will be editing empty buffers. Similarly, "-ON" opens N
windows split vertically, with the same restrictions.
If there are many file names, the windows will become very small. You might
want to set the 'winheight' and/or 'winwidth' options to create a workable
situation.
Buf/Win Enter/Leave |autocommand|s are not executed when opening the new
windows and reading the files, that's only done when they are really entered.
*status-line*
A status line will be used to separate windows. The 'laststatus' option tells
when the last window also has a status line:
'laststatus' = 0 never a status line
'laststatus' = 1 status line if there is more than one window
'laststatus' = 2 always a status line
You can change the contents of the status line with the 'statusline' option.
This option can be local to the window, so that you can have a different
status line in each window.
Normally, inversion is used to display the status line. This can be changed
with the 's' character in the 'highlight' option. For example, "sb" sets it to
bold characters. If no highlighting is used for the status line ("sn"), the
'^' character is used for the current window, and '=' for other windows. If
the mouse is supported and enabled with the 'mouse' option, a status line can
be dragged to resize windows.
Note: If you expect your status line to be in reverse video and it isn't,
check if the 'highlight' option contains "si". In version 3.0, this meant to
invert the status line. Now it should be "sr", reverse the status line, as
"si" now stands for italic! If italic is not available on your terminal, the
status line is inverted anyway; you will only see this problem on terminals
that have termcap codes for italics.
*filler-lines*
The lines after the last buffer line in a window are called filler lines. By
default, these lines start with a tilde (~) character. The 'eob' item in the
'fillchars' optio