diff options
author | Justin M. Keyes <justinkz@gmail.com> | 2018-09-21 14:59:02 +0200 |
---|---|---|
committer | Justin M. Keyes <justinkz@gmail.com> | 2018-10-11 19:32:44 +0200 |
commit | ea12efa66b177fc1cfd58ad9c9c33f4163b7f5ab (patch) | |
tree | 40f03cbdbec9b3430be047bd2c88012c282ab0c8 | |
parent | ab6994497818e54c9e53c6aac0055051344c4b22 (diff) | |
download | rneovim-ea12efa66b177fc1cfd58ad9c9c33f4163b7f5ab.tar.gz rneovim-ea12efa66b177fc1cfd58ad9c9c33f4163b7f5ab.tar.bz2 rneovim-ea12efa66b177fc1cfd58ad9c9c33f4163b7f5ab.zip |
doc: mouse: cleanup, fixup
- 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
-rw-r--r-- | runtime/doc/gui.txt | 236 | ||||
-rw-r--r-- | runtime/doc/options.txt | 76 | ||||
-rw-r--r-- | runtime/doc/provider.txt | 12 | ||||
-rw-r--r-- | runtime/doc/term.txt | 94 |
4 files changed, 85 insertions, 333 deletions
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt index 904c4be19c..0c2cc9c865 100644 --- a/runtime/doc/gui.txt +++ b/runtime/doc/gui.txt @@ -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: diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 2f2db844e8..f2962f0822 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -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. diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt index ce946aa009..0e26dc4515 100644 --- a/runtime/doc/provider.txt +++ b/runtime/doc/provider.txt @@ -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: diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt index 418623687f..9de5745e92 100644 --- a/runtime/doc/term.txt +++ b/runtime/doc/term.txt @@ -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: |