kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 03:05:11 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc: mouse: cleanup, fixup

Browse Source 
- Much of the mouse chatter in gui.txt and term.txt is redundant; other
  parts are outdated or irreleveant to Nvim.
- Fix default value of 'mousemodel' for Windows
This commit is contained in:
Justin M. Keyes 2018-09-21 14:59:02 +02:00
parent ab69944978
commit ea12efa66b
4 changed files with 85 additions and 333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
runtime/doc/gui.txt
View File

@ -9,7 +9,7 @@ Vim's Graphical User Interface *gui* *GUI*
Type |gO| to see the table of contents.
==============================================================================
1. Starting the GUI *gui-start* *E229* *E233*
Starting the GUI *gui-start* *E229* *E233*
*ginit.vim* *gui-init* *gvimrc* *$MYGVIMRC*
The gvimrc file is where GUI-specific startup commands should be placed. It
@ -87,7 +87,7 @@ and only the first one that is found is read.
Obsolete, use ":set lines=11 columns=22".
==============================================================================
2. Scrollbars *gui-scrollbars*
Scrollbars *gui-scrollbars*
There are vertical scrollbars and a horizontal scrollbar. You may
configure which ones appear with the 'guioptions' option.
@ -155,167 +155,7 @@ include the 'h' flag in 'guioptions'. Then the scrolling is limited by the
text of the current cursor line.
==============================================================================
3. Mouse Control *gui-mouse*
The mouse only works if the appropriate flag in the 'mouse' option is set.
When the GUI is switched on, and 'mouse' wasn't set yet, the 'mouse' option is
automatically set to "a", enabling it for all modes except for the
|hit-enter| prompt. If you don't want this, a good place to change the
'mouse' option is the "gvimrc" file.
Other options that are relevant:
'mousefocus' window focus follows mouse pointer |gui-mouse-focus|
'mousemodel' what mouse button does which action
'mousehide' hide mouse pointer while typing text
'selectmode' whether to start Select mode or Visual mode
A quick way to set these is with the ":behave" command.
*:behave* *:be*
:be[have] {model} Set behavior for mouse and selection. Valid
arguments are:
mswin MS-Windows behavior
xterm Xterm behavior
Using ":behave" changes these options:
option mswin xterm ~
'selectmode' "mouse,key" ""
'mousemodel' "popup" "extend"
'keymodel' "startsel,stopsel" ""
'selection' "exclusive" "inclusive"
In the $VIMRUNTIME directory, there is a script called |mswin.vim|, which will
also map a few keys to the MS-Windows cut/copy/paste commands. This is NOT
compatible, since it uses the CTRL-V, CTRL-X and CTRL-C keys. If you don't
mind, use this command: >
:so $VIMRUNTIME/mswin.vim
For scrolling with a wheel on a mouse, see |scroll-mouse-wheel|.
3.1 Moving Cursor with Mouse *gui-mouse-move*
Click the left mouse button somewhere in a text buffer where you want the
cursor to go, and it does!
This works in when 'mouse' contains ~
Normal mode 'n' or 'a'
Visual mode 'v' or 'a'
Insert mode 'i' or 'a'
Select mode is handled like Visual mode.
You may use this with an operator such as 'd' to delete text from the current
cursor position to the position you point to with the mouse. That is, you hit
'd' and then click the mouse somewhere.
*gui-mouse-focus*
The 'mousefocus' option can be set to make the keyboard focus follow the
mouse pointer. This means that the window where the mouse pointer is, is the
active window. Warning: this doesn't work very well when using a menu,
because the menu command will always be applied to the top window.
If you are on the ':' line (or '/' or '?'), then clicking the left or right
mouse button will position the cursor on the ':' line (if 'mouse' contains
'c', 'a' or 'A').
In any situation the middle mouse button may be clicked to paste the current
selection.
3.2 Selection with Mouse *gui-mouse-select*
The mouse can be used to start a selection. How depends on the 'mousemodel'
option:
'mousemodel' is "extend": use the right mouse button
'mousemodel' is "popup": use the left mouse button, while keeping the Shift
key pressed.
If there was no selection yet, this starts a selection from the old cursor
position to the position pointed to with the mouse. If there already is a
selection then the closest end will be extended.
If 'selectmode' contains "mouse", then the selection will be in Select mode.
This means that typing normal text will replace the selection. See
|Select-mode|. Otherwise, the selection will be in Visual mode.
Double clicking may be done to make the selection word-wise, triple clicking
makes it line-wise, and quadruple clicking makes it rectangular block-wise.
See |gui-selections| on how the selection is used.
3.3 Other Text Selection with Mouse *gui-mouse-modeless*
*modeless-selection*
A different kind of selection is used when:
- in Command-line mode
- in the Command-line window and pointing in another window
- at the |hit-enter| prompt
- whenever the current mode is not in the 'mouse' option
- when holding the CTRL and SHIFT keys in the GUI
Since Vim continues like the selection isn't there, and there is no mode
associated with the selection, this is called modeless selection. Any text in
the Vim window can be selected. Select the text by pressing the left mouse
button at the start, drag to the end and release. To extend the selection,
use the right mouse button when 'mousemodel' is "extend", or the left mouse
button with the shift key pressed when 'mousemodel' is "popup".
The selection is removed when the selected text is scrolled or changed.
On the command line CTRL-Y can be used to copy the selection into the
clipboard. To do this from Insert mode, use CTRL-O : CTRL-Y <CR>. When
'guioptions' contains a or A (default on X11), the selection is automatically
copied to the "* register.
The middle mouse button can then paste the text. On non-X11 systems, you can
use CTRL-R +.
3.4 Using Mouse on Status Lines *gui-mouse-status*
Clicking the left or right mouse button on the status line below a Vim
window makes that window the current window. This actually happens on button
release (to be able to distinguish a click from a drag action).
With the left mouse button a status line can be dragged up and down, thus
resizing the windows above and below it. This does not change window focus.
The same can be used on the vertical separator: click to give the window left
of it focus, drag left and right to make windows wider and narrower.
3.5 Various Mouse Clicks *gui-mouse-various*
<S-LeftMouse> Search forward for the word under the mouse click.
When 'mousemodel' is "popup" this starts or extends a
selection.
<S-RightMouse> Search backward for the word under the mouse click.
<C-LeftMouse> Jump to the tag name under the mouse click.
<C-RightMouse> Jump back to position before the previous tag jump
(same as "CTRL-T")
3.6 Mouse Mappings *gui-mouse-mapping*
The mouse events, complete with modifiers, may be mapped. Eg: >
:map <S-LeftMouse> <RightMouse>
:map <S-LeftDrag> <RightDrag>
:map <S-LeftRelease> <RightRelease>
:map <2-S-LeftMouse> <2-RightMouse>
:map <2-S-LeftDrag> <2-RightDrag>
:map <2-S-LeftRelease> <2-RightRelease>
:map <3-S-LeftMouse> <3-RightMouse>
:map <3-S-LeftDrag> <3-RightDrag>
:map <3-S-LeftRelease> <3-RightRelease>
:map <4-S-LeftMouse> <4-RightMouse>
:map <4-S-LeftDrag> <4-RightDrag>
:map <4-S-LeftRelease> <4-RightRelease>
These mappings make selection work the way it probably should in a Motif
application, with shift-left mouse allowing for extending the visual area
rather than the right mouse button.
Mouse mapping with modifiers does not work for modeless selection.
3.7 Drag and drop *drag-n-drop*
Drag and drop *drag-n-drop*
You can drag and drop one or more files into the Vim window, where they will
be opened as if a |:drop| command was used.
@ -334,47 +174,12 @@ names with any Ex command. Special characters (space, tab, double quote and
'|'; backslash on non-MS-Windows systems) will be escaped.
==============================================================================
4. Making GUI Selections *gui-selections*
*quotestar*
You may make selections with the mouse (see |gui-mouse-select|), or by using
Vim's Visual mode (see |v|). If 'a' is present in 'guioptions', then
whenever a selection is started (Visual or Select mode), or when the selection
is changed, Vim becomes the owner of the windowing system's primary selection
(on MS-Windows the |clipboard| is used).
*primary-selection*
There is a special register for storing this selection, it is the "*
register. Nothing is put in here unless the information about what text is
selected is about to change (e.g. with a left mouse click somewhere), or when
another application wants to paste the selected text. Then the text is put
in the "* register. For example, to cut a line and make it the current
selection/put it on the clipboard: >
"*dd
Similarly, when you want to paste a selection from another application, e.g.,
by clicking the middle mouse button, the selection is put in the "* register
first, and then 'put' like any other register. For example, to put the
selection (contents of the clipboard): >
"*p
Note that when pasting text from one Vim into another separate Vim, the type
of selection (character, line, or block) will also be copied. For other
applications the type is always character.
When the "unnamed" string is included in the 'clipboard' option, the unnamed
register is the same as the "* register. Thus you can yank to and paste the
selection without prepending "* to commands.
==============================================================================
5. Menus *menus*
Menus *menus*
For an introduction see |usr_42.txt| in the user manual.
5.1 Using Menus *using-menus*
Using Menus *using-menus*
Basically, menus can be used just like mappings. You can define your own
menus, as many as you like.
@ -420,7 +225,7 @@ Pressing <F4> will start the menu. You can now use the cursor keys to select
a menu entry. Hit <Enter> to execute it. Hit <Esc> if you want to cancel.
This does require the |+menu| feature enabled at compile time.
5.2 Creating New Menus *creating-menus*
Creating New Menus *creating-menus*
*:me* *:menu* *:noreme* *:noremenu*
*:am* *:amenu* *:an* *:anoremenu*
@ -662,7 +467,7 @@ when the right mouse button is pressed, if 'mousemodel' is set to popup or
popup_setpos.
5.3 Showing What Menus Are Mapped To *showing-menus*
Showing What Menus Are Mapped To *showing-menus*
To see what an existing menu is mapped to, use just one argument after the
menu commands (just like you would with the ":map" commands). If the menu
@ -680,7 +485,7 @@ Note that hitting <Tab> while entering a menu name after a menu command may
be used to complete the name of the menu item.
5.4 Executing Menus *execute-menus*
Executing Menus *execute-menus*
*:em* *:emenu* *E334* *E335*
:[range]em[enu] {menu} Execute {menu} from the command line.
@ -700,7 +505,7 @@ When using a range, if the lines match with '<,'>, then the menu is executed
using the last visual selection.
5.5 Deleting Menus *delete-menus*
Deleting Menus *delete-menus*
*:unme* *:unmenu*
*:aun* *:aunmenu*
@ -730,7 +535,7 @@ If you want to get rid of the menu bar: >
:set guioptions-=m
5.6 Disabling Menus *disable-menus*
Disabling Menus *disable-menus*
*:menu-disable* *:menu-enable*
If you do not want to remove a menu, but disable it for a moment, this can be
@ -746,7 +551,7 @@ When the argument is "*", all menus are affected. Otherwise the given menu
name and all existing submenus below it are affected.
5.7 Examples for Menus *menu-examples*
Examples for Menus *menu-examples*
Here is an example on how to add menu items with menu's! You can add a menu
item for the keyword under the cursor. The register "z" is used. >
@ -763,7 +568,7 @@ mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
the <CR> key. |<>|)
5.8 Tooltips & Menu tips
Tooltips & Menu tips
See section |42.4| in the user manual.
@ -833,22 +638,5 @@ This creates a popup menu that doesn't exist on the main menu-bar.
Note that a menu that starts with ']' will not be displayed.
==============================================================================
6. Extras *gui-extras*
This section describes other features which are related to the GUI.
- With the GUI, there is no wait for one second after hitting escape, because
the key codes don't start with <Esc>.
- Typing ^V followed by a special key in the GUI will insert "<Key>", since
the internal string used is meaningless. Modifiers may also be held down to
get "<Modifiers-Key>".
- In the GUI, the modifiers SHIFT, CTRL, and ALT (or META) may be used within
mappings of special keys and mouse events. E.g.: :map <M-LeftDrag> <LeftDrag>
- In the GUI, several normal keys may have modifiers in mappings etc, these
are <Space>, <Tab>, <NL>, <CR>, <Esc>.
vim:tw=78:sw=4:ts=8:ft=help:norl:

76
runtime/doc/options.txt
View File

@ -4036,9 +4036,14 @@ A jump table for the options with a short description can be found at |Q_op|.
'mouse' string (default "")
global
Enable the use of the mouse. Only works for certain terminals.
For using the mouse in the GUI, see |gui-mouse|. The mouse can be
enabled for different modes:
Enables mouse support. For example, to enable the mouse in Normal mode
and Visual mode: >
:set mouse=nv
<
To temporarily disable mouse support, hold the shift key while using
the mouse.
Mouse support can be enabled for different modes:
n Normal mode
v Visual mode
i Insert mode
@ -4046,17 +4051,42 @@ A jump table for the options with a short description can be found at |Q_op|.
h all previous modes when editing a help file
a all previous modes
r for |hit-enter| and |more-prompt| prompt
Normally you would enable the mouse in all four modes with: >
:set mouse=a
< When the mouse is not enabled, the GUI will still use the mouse for
modeless selection. This doesn't move the text cursor.
See |mouse-using|. Also see |'clipboard'|.
Left-click anywhere in a text buffer to place the cursor there. This
works with operators too, e.g. type |d| then left-click to delete text
from the current cursor position to the position where you clicked.
Drag the |status-line| or vertical separator of a window to resize it.
If enabled for "v" (Visual mode) then double-click selects word-wise,
triple-click makes it line-wise, and quadruple-click makes it
rectangular block-wise.
For scrolling with a mouse wheel see |scroll-mouse-wheel|.
Note: When enabling the mouse in a terminal, copy/paste will use the
"* register if there is access to an X-server. The xterm handling of
the mouse buttons can still be used by keeping the shift key pressed.
Also see the 'clipboard' option.
"* register if possible. See also 'clipboard'.
Related options:
'mousefocus' window focus follows mouse pointer
'mousemodel' what mouse button does which action
'mousehide' hide mouse pointer while typing text
'selectmode' whether to start Select mode or Visual mode
The :behave command provides some "profiles" for mouse behavior.
*:behave* *:be*
:be[have] {model} Set behavior for mouse and selection. Valid
arguments are:
mswin MS-Windows behavior
xterm Xterm behavior
Using ":behave" changes these options:
option mswin xterm ~
'selectmode' "mouse,key" ""
'mousemodel' "popup" "extend"
'keymodel' "startsel,stopsel" ""
'selection' "exclusive" "inclusive"
*'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'*
'mousefocus' 'mousef' boolean (default off)
@ -4076,7 +4106,7 @@ A jump table for the options with a short description can be found at |Q_op|.
The mouse pointer is restored when the mouse is moved.
*'mousemodel'* *'mousem'*
'mousemodel' 'mousem' string (default "extend", "popup" for Windows)
'mousemodel' 'mousem' string (default "extend")
global
Sets the model to use for the mouse. The name mostly specifies what
the right mouse button is used for:
@ -4105,8 +4135,26 @@ A jump table for the options with a short description can be found at |Q_op|.
You need to define this first, see |popup-menu|.
Note that you can further refine the meaning of buttons with mappings.
See |gui-mouse-mapping|. But mappings are NOT used for modeless
selection (because that's handled in the GUI code directly).
See |mouse-overview|. But mappings are NOT used for modeless selection.
Example: >
:map <S-LeftMouse> <RightMouse>
:map <S-LeftDrag> <RightDrag>
:map <S-LeftRelease> <RightRelease>
:map <2-S-LeftMouse> <2-RightMouse>
:map <2-S-LeftDrag> <2-RightDrag>
:map <2-S-LeftRelease> <2-RightRelease>
:map <3-S-LeftMouse> <3-RightMouse>
:map <3-S-LeftDrag> <3-RightDrag>
:map <3-S-LeftRelease> <3-RightRelease>
:map <4-S-LeftMouse> <4-RightMouse>
:map <4-S-LeftDrag> <4-RightDrag>
:map <4-S-LeftRelease> <4-RightRelease>
<
Mouse commands requiring the CTRL modifier can be simulated by typing
the "g" key before using the mouse:
"g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
"g<RightMouse>" is "<C-RightMouse> ("CTRL-T")
The 'mousemodel' option is set by the |:behave| command.

12
runtime/doc/provider.txt
View File

@ -186,15 +186,15 @@ The contents of selections are held by the originating application (e.g., upon
a copy), and only passed to another application when that other application
requests them (e.g., upon a paste).
*quoteplus* *quote+*
*primary-selection* *quotestar* *quoteplus* *quote+*
There are three documented X11 selections: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`.
`CLIPBOARD` is typically used in X11 applications for copy/paste operations
(`Ctrl-c`/`v`), while `PRIMARY` is used for the last selected text, which is
There are three documented X11 selections: PRIMARY, SECONDARY, and CLIPBOARD.
CLIPBOARD is typically used in X11 applications for copy/paste operations
(CTRL-c/CTRL-v), while PRIMARY is used for the last selected text, which is
generally inserted with the middle mouse button.
Nvim's X11 clipboard providers only utilize the `PRIMARY` and `CLIPBOARD`
selections, used for the '*' and '+' registers, respectively.
Nvim's X11 clipboard providers only use the PRIMARY and CLIPBOARD selections,
for the "*" and "+" registers, respectively.
==============================================================================
vim:tw=78:ts=8:noet:ft=help:norl:

94
runtime/doc/term.txt
View File

@ -257,90 +257,14 @@ effect on some UIs.
==============================================================================
Using the mouse *mouse-using*
This section is about using the mouse on a terminal or a terminal window. How
to use the mouse in a GUI window is explained in |gui-mouse|. For scrolling
with a mouse wheel see |scroll-mouse-wheel|.
These characters in the 'mouse' option tell in which situations the mouse will
be used by Vim:
n Normal mode
v Visual mode
i Insert mode
c Command-line mode
h all previous modes when in a help file
a all previous modes
r for |hit-enter| prompt
If you only want to use the mouse in a few modes or also want to use it for
the two questions you will have to concatenate the letters for those modes.
For example: >
:set mouse=nv
Will make the mouse work in Normal mode and Visual mode. >
:set mouse=h
Will make the mouse work in help files only (so you can use "g<LeftMouse>" to
jump to tags).
Whether the selection that is started with the mouse is in Visual mode or
Select mode depends on whether "mouse" is included in the 'selectmode'
option.
In an xterm, with the currently active mode included in the 'mouse' option,
normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key
pressed go to the xterm. With the currently active mode not included in
'mouse' all mouse clicks go to the xterm.
*xterm-clipboard*
The middle mouse button will insert the unnamed register. In that case, here
is how you copy and paste a piece of text:
Copy/paste with the mouse and Visual mode ('mouse' option must be set, see
above):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button. This will start Visual mode and
highlight the selected area.
2. Press "y" to yank the Visual text in the unnamed register.
3. Click the left mouse button at the insert position.
4. Click the middle mouse button.
Shortcut: If the insert position is on the screen at the same time as the
Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button
at the insert position.
*xterm-copy-paste*
NOTE: In some (older) xterms, it's not possible to move the cursor past column
95 or 223. This is an xterm problem, not Vim's. Get a newer xterm
|color-xterm|.
Copy/paste in xterm with (current mode NOT included in 'mouse'):
1. Press left mouse button on first letter of text, move mouse pointer to last
letter of the text and release the button.
2. Use normal Vim commands to put the cursor at the insert position.
3. Press "a" to start Insert mode.
4. Click the middle mouse button.
5. Press ESC to end Insert mode.
(The same can be done with anything in 'mouse' if you keep the shift key
pressed while using the mouse.)
Note: if you lose the 8th bit when pasting (special characters are translated
into other characters), you may have to do "stty cs8 -istrip -parenb" in your
shell before starting Vim.
Thus in an xterm the shift and ctrl keys cannot be used with the mouse. Mouse
commands requiring the CTRL modifier can be simulated by typing the "g" key
before using the mouse:
"g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click)
"g<RightMouse>" is "<C-RightMouse> ("CTRL-T")
*bracketed-paste-mode*
Bracketed paste mode allows terminal applications to distinguish between typed
text and pasted text. Thus you can paste text without Nvim trying to format or
indent the text. See also https://cirw.in/blog/bracketed-paste
Nvim enables bracketed paste by default. If it does not work in your terminal,
try the 'paste' option instead.
Nvim enables bracketed paste by default. Bracketed paste mode allows terminal
applications to distinguish between typed text and pasted text. Thus you can
paste text without Nvim trying to format or indent the text.
See also https://cirw.in/blog/bracketed-paste
*mouse-mode-table* *mouse-overview*
A short overview of what the mouse buttons do, when 'mousemodel' is "extend":
Overview of what the mouse buttons do, when 'mousemodel' is "extend":
Normal Mode:
event position selection change action ~
@ -451,14 +375,6 @@ In Insert mode, when a selection is started, Vim goes into Normal mode
temporarily. When Visual or Select mode ends, it returns to Insert mode.
This is like using CTRL-O in Insert mode. Select mode is used when the
'selectmode' option contains "mouse".
*drag-status-line*
When working with several windows, the size of the windows can be changed by
dragging the status line with the mouse. Point the mouse at a status line,
press the left button, move the mouse to the new position of the status line,
release the button. Just clicking the mouse in a status line makes that window
the current window, without moving the cursor. If by selecting a window it
will change position or size, the dragging of the status line will look
confusing, but it will work (just try it).
*<MiddleRelease>* *<MiddleDrag>*
Mouse clicks can be mapped. The codes for mouse clicks are: