vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

gui.txt (55111B)


      1 *gui.txt*	For Vim version 9.2.  Last change: 2026 Aug 04
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Vim's Graphical User Interface				*gui* *GUI*
      8 
      9 1. Starting the GUI		|gui-start|
     10 2. Scrollbars			|gui-scrollbars|
     11 3. Mouse Control		|gui-mouse|
     12 4. Making GUI Selections	|gui-selections|
     13 5. Menus			|menus|
     14 6. Font				|gui-font|
     15 7. Extras			|gui-extras|
     16 8. Shell Commands		|gui-shell|
     17 
     18 Other GUI documentation:
     19 |gui_x11.txt|	For specific items of the X11 GUI.
     20 |gui_w32.txt|	For specific items of the Win32 GUI.
     21 
     22 
     23 ==============================================================================
     24 1. Starting the GUI				*gui-start* *E229* *E233*
     25 
     26 First you must make sure you actually have a version of Vim with the GUI code
     27 included.  You can check this with the ":version" command, it says "with xxx
     28 GUI", where "xxx" is X11-Motif, Photon, GTK2, GTK3, GTK4, etc., or
     29 "MS-Windows 32 bit GUI version".
     30 
     31 How to start the GUI depends on the system used.  Mostly you can run the
     32 GUI version of Vim with:
     33     gvim [options] [files...]
     34 
     35 The X11 version of Vim can run both in GUI and in non-GUI mode.  See
     36 |gui-x11-start|.
     37 
     38 			*gui-init* *gvimrc* *.gvimrc* *_gvimrc* *$MYGVIMRC*
     39 The gvimrc file is where GUI-specific startup commands should be placed.  It
     40 is always sourced after the |vimrc| file.  If you have one then the $MYGVIMRC
     41 environment variable has its name.
     42 
     43 When the GUI starts up initializations are carried out, in this order:
     44 - The 'term' option is set to "builtin_gui" and terminal options are reset to
     45   their default value for the GUI |terminal-options|.
     46 - If the system menu file exists, it is sourced.  The name of this file is
     47   normally "$VIMRUNTIME/menu.vim".  You can check this with ":version".  Also
     48   see |$VIMRUNTIME|.  To skip loading the system menu include 'M' in
     49   'guioptions'.				*buffers-menu* *no_buffers_menu*
     50   The system menu file includes a "Buffers" menu.  If you don't want this, set
     51   the "no_buffers_menu" variable in your .vimrc (not .gvimrc!): >
     52 	:let no_buffers_menu = 1
     53 < NOTE: Switching on syntax highlighting also loads the menu file, thus
     54   disabling the Buffers menu must be done before ":syntax on".
     55   The path names are truncated to 35 characters.  You can truncate them at a
     56   different length, for example 50, like this: >
     57 	:let bmenu_max_pathlen = 50
     58 - If the "-U {gvimrc}" command-line option has been used when starting Vim,
     59   the {gvimrc} file will be read for initializations.  The following
     60   initializations are skipped.  When {gvimrc} is "NONE" no file will be read
     61   for initializations.
     62 - For Unix and MS-Windows, if the system gvimrc exists, it is sourced.  The
     63   name of this file is normally "$VIM/gvimrc".  You can check this with
     64   ":version".  Also see |$VIM|.
     65 - The following are tried, and only the first one that exists is used:
     66   - If the GVIMINIT environment variable exists and is not empty, it is
     67     executed as an Ex command.
     68   - If the user gvimrc file exists, it is sourced.  The name of this file is
     69     normally "$HOME/.gvimrc".  You can check this with ":version".
     70   - For Win32, $HOME is set by Vim if needed, see |$HOME-windows|.
     71   - When a "_gvimrc" file is not found, ".gvimrc" is tried too.  And vice
     72     versa.
     73   - On Unix, if "~/.config/vim/gvimrc" or "$XDG_CONFIG_HOME/vim/gvimrc"
     74     exists, it is sourced.  You can check this with ":version".
     75   The name of the first file found is stored in $MYGVIMRC, unless it was
     76   already set.
     77 - If the 'exrc' option is set (which is NOT the default) the file ./.gvimrc
     78   is sourced, if it exists and isn't the same file as the system or user
     79   gvimrc file.  If this file is not owned by you, some security restrictions
     80   apply.  When ".gvimrc" is not found, "_gvimrc" is tried too.  For Macintosh
     81   and DOS/Win32 "_gvimrc" is tried first.
     82 
     83 NOTE: All but the first one are not carried out if Vim was started with
     84 "-u NONE" or "-u DEFAULTS" and no "-U" argument was given, or when started
     85 with "-U NONE".
     86 
     87 All this happens AFTER the normal Vim initializations, like reading your
     88 .vimrc file.  See |initialization|.
     89 But the GUI window is only opened after all the initializations have been
     90 carried out.  If you want some commands to be executed just after opening the
     91 GUI window, use the |GUIEnter| autocommand event.  Example: >
     92 	:autocmd GUIEnter * winpos 100 50
     93 
     94 You can use the gvimrc files to set up your own customized menus (see |:menu|)
     95 and initialize other things that you may want to set up differently from the
     96 terminal version.
     97 
     98 Recommended place for your personal GUI initializations:
     99 	Unix		    $HOME/.gvimrc or $HOME/.vim/gvimrc
    100 	Win32		    $HOME/_gvimrc, $HOME/vimfiles/gvimrc
    101 			    or $VIM/_gvimrc
    102 	Amiga		    s:.gvimrc, home:.gvimrc, home:vimfiles:gvimrc
    103 			    or $VIM/.gvimrc
    104 	Haiku		    $HOME/config/settings/vim/gvimrc
    105 
    106 The personal initialization files are searched in the order specified above
    107 and only the first one that is found is read.
    108 
    109 There are a number of options which only have meaning in the GUI version of
    110 Vim.  These are 'guicursor', 'guifont', 'guipty' and 'guioptions'.  They are
    111 documented in |options.txt| with all the other options.
    112 
    113 If using the Motif version of the GUI (but not for the GTK+ or
    114 Win32 version), a number of X resources are available.  See |gui-resources|.
    115 
    116 Another way to set the colors for different occasions is with highlight
    117 groups.  The "Normal" group is used to set the background and foreground
    118 colors.  Example (which looks nice): >
    119 
    120 	:highlight Normal guibg=grey90
    121 
    122 The "guibg" and "guifg" settings override the normal background and
    123 foreground settings.  The other settings for the Normal highlight group are
    124 not used.  Use the 'guifont' option to set the font.
    125 
    126 Also check out the 'guicursor' option, to set the colors for the cursor in
    127 various modes.
    128 
    129 Vim tries to make the window fit on the screen when it starts up.  This avoids
    130 that you can't see part of it.  On the X Window System this requires a bit of
    131 guesswork.  You can change the height that is used for the window title and a
    132 task bar with the 'guiheadroom' option.
    133 
    134 						*:winp* *:winpos* *E188*
    135 :winp[os]
    136 		Display current position of the top left corner of the GUI vim
    137 		window in pixels.  Does not work in all versions.
    138 		Also see |getwinpos()|, |getwinposx()| and |getwinposy()|.
    139 
    140 :winp[os] {X} {Y}							*E466*
    141 		Put the GUI vim window at the given {X} and {Y} coordinates.
    142 		The coordinates should specify the position in pixels of the
    143 		top left corner of the window.  Does not work in all versions.
    144 		Does work in an (new) xterm |xterm-color|.
    145 		When the GUI window has not been opened yet, the values are
    146 		remembered until the window is opened.  The position is
    147 		adjusted to make the window fit on the screen (if possible).
    148 
    149 					    *:wi* *:win* *:winsize* *E465*
    150 :win[size] {width} {height}
    151 		Set the window height to {width} by {height} characters.
    152 		It is recommended to use `:set lines=11 columns=22` instead,
    153 		since it's easy to see what the numbers mean.
    154 		If you get less lines than expected, check the 'guiheadroom'
    155 		option.
    156 
    157 If you are running the X Window System, you can get information about the
    158 window Vim is running in with these commands: >
    159 	:!xwininfo -id $WINDOWID
    160 	:!xprop -id $WINDOWID
    161 	:execute '!xwininfo -id ' .. v:windowid
    162 	:execute '!xprop -id ' .. v:windowid
    163 <
    164 							*gui-IME* *iBus*
    165 Input methods for international characters in X that rely on the XIM
    166 framework, most notably iBus, have been known to produce undesirable results
    167 in gvim.  These may include an inability to enter spaces, or long delays
    168 between typing a character and it being recognized by the application.
    169 
    170 One workaround that has been successful, for unknown reasons, is to prevent
    171 gvim from forking into the background by starting it with the |-f| argument.
    172 
    173 ==============================================================================
    174 2. Scrollbars						*gui-scrollbars*
    175 
    176 There are vertical scrollbars and a horizontal scrollbar.  You may
    177 configure which ones appear with the 'guioptions' option.
    178 
    179 The interface looks like this (with ":set guioptions=mlrb"):
    180 
    181 		       +------------------------------+ `
    182 		       | File  Edit		 Help | <- Menu bar (m) `
    183 		       +-+--------------------------+-+ `
    184 		       |^|			    |^| `
    185 		       |#| Text area.		    |#| `
    186 		       | |			    | | `
    187 		       |v|__________________________|v| `
    188  Normal status line -> |-+ File.c	       5,2  +-| `
    189  between Vim windows   |^|""""""""""""""""""""""""""|^| `
    190 		       | |			    | | `
    191 		       | | Another file buffer.     | | `
    192 		       | |			    | | `
    193 		       |#|			    |#| `
    194  Left scrollbar (l) -> |#|			    |#| <- Right `
    195 		       |#|			    |#|    scrollbar (r) `
    196 		       | |			    | | `
    197 		       |v|			    |v| `
    198 		       +-+--------------------------+-+ `
    199 		       | |< ####		   >| | <- Bottom `
    200 		       +-+--------------------------+-+    scrollbar (b) `
    201 
    202 Any of the scrollbar or menu components may be turned off by not putting the
    203 appropriate letter in the 'guioptions' string.  The bottom scrollbar is
    204 only useful when 'nowrap' is set.
    205 
    206 
    207 VERTICAL SCROLLBARS					*gui-vert-scroll*
    208 
    209 Each Vim window has a scrollbar next to it which may be scrolled up and down
    210 to move through the text in that buffer.  The size of the scrollbar-thumb
    211 indicates the fraction of the buffer which can be seen in the window.
    212 When the scrollbar is dragged all the way down, the last line of the file
    213 will appear in the top of the window.
    214 
    215 If a window is shrunk to zero height (by the growth of another window) its
    216 scrollbar disappears.  It reappears when the window is restored.
    217 
    218 If a window is vertically split, it will get a scrollbar when it is the
    219 current window and when, taking the middle of the current window and drawing a
    220 vertical line, this line goes through the window.
    221 When there are scrollbars on both sides, and the middle of the current window
    222 is on the left half, the right scrollbar column will contain scrollbars for
    223 the rightmost windows.  The same happens on the other side.
    224 
    225 
    226 HORIZONTAL SCROLLBARS					*gui-horiz-scroll*
    227 
    228 The horizontal scrollbar (at the bottom of the Vim GUI) may be used to
    229 scroll text sideways when the 'wrap' option is turned off.  The
    230 scrollbar-thumb size is such that the text of the longest visible line may be
    231 scrolled as far as possible left and right.  The cursor is moved when
    232 necessary, it must remain on a visible character (unless 'virtualedit' is
    233 set).
    234 
    235 Computing the length of the longest visible line takes quite a bit of
    236 computation, and it has to be done every time something changes.  If this
    237 takes too much time or you don't like the cursor jumping to another line,
    238 include the 'h' flag in 'guioptions'.  Then the scrolling is limited by the
    239 text of the current cursor line.
    240 
    241 							*motif-intellimouse*
    242 If you have an Intellimouse and an X server that supports using the wheel,
    243 then you can use the wheel to scroll the text up and down in gvim.  This works
    244 with XFree86 4.0 and later, and with some older versions when you add patches.
    245 See |scroll-mouse-wheel|.
    246 
    247 For older versions of XFree86 you must patch your X server.  The following
    248 page has a bit of information about using the Intellimouse on Linux as well as
    249 links to the patches and X server binaries (may not have the one you need
    250 though):
    251     (dead link) inria.fr/koala/colas/mouse-wheel-scroll/
    252 
    253 ==============================================================================
    254 3. Mouse Control					*gui-mouse*
    255 
    256 The mouse only works if the appropriate flag in the 'mouse' option is set.
    257 When the GUI is switched on, and 'mouse' wasn't set yet, the 'mouse' option is
    258 automatically set to "a", enabling it for all modes except for the
    259 |hit-enter| prompt.  If you don't want this, a good place to change the
    260 'mouse' option is the "gvimrc" file.
    261 
    262 Other options that are relevant:
    263 'mousefocus'	window focus follows mouse pointer |gui-mouse-focus|
    264 'mousemodel'	what mouse button does which action
    265 'mousehide'	hide mouse pointer while typing text
    266 'mousemoveevent' enable mouse move events so that <MouseMove> can be mapped
    267 'selectmode'	whether to start Select mode or Visual mode
    268 
    269 A quick way to set these is with the ":behave" command.
    270 							*:behave* *:be*
    271 :be[have] {model}	Set behavior for mouse and selection.  Valid
    272 			arguments are:
    273 			   mswin	MS-Windows behavior
    274 			   xterm	Xterm behavior
    275 
    276 			Using ":behave" changes these options:
    277 			option		mswin			xterm	~
    278 			'selectmode'	"mouse,key"		""
    279 			'mousemodel'	"popup"			"extend"
    280 			'keymodel'	"startsel,stopsel"	""
    281 			'selection'	"exclusive"		"inclusive"
    282 
    283 In the $VIMRUNTIME directory, there is a script called |mswin.vim|, which will
    284 also map a few keys to the MS-Windows cut/copy/paste commands.  This is NOT
    285 compatible, since it uses the CTRL-V, CTRL-X and CTRL-C keys.  If you don't
    286 mind, use this command: >
    287 	:so $VIMRUNTIME/mswin.vim
    288 
    289 For scrolling with a wheel on a mouse, see |scroll-mouse-wheel|.
    290 
    291 
    292 3.1 Moving Cursor with Mouse				*gui-mouse-move*
    293 
    294 Click the left mouse button somewhere in a text buffer where you want the
    295 cursor to go, and it does!
    296 This works in	    when 'mouse' contains ~
    297 Normal mode	    'n' or 'a'
    298 Visual mode	    'v' or 'a'
    299 Insert mode	    'i' or 'a'
    300 
    301 Select mode is handled like Visual mode.
    302 
    303 You may use this with an operator such as 'd' to delete text from the current
    304 cursor position to the position you point to with the mouse.  That is, you hit
    305 'd' and then click the mouse somewhere.
    306 
    307 							*gui-mouse-focus*
    308 The 'mousefocus' option can be set to make the keyboard focus follow the
    309 mouse pointer.  This means that the window where the mouse pointer is, is the
    310 active window.  Warning: this doesn't work very well when using a menu,
    311 because the menu command will always be applied to the top window.
    312 
    313 If you are on the ':' line (or '/' or '?'), then clicking the left or right
    314 mouse button will position the cursor on the ':' line (if 'mouse' contains
    315 'c' or 'a').
    316 
    317 In any situation the middle mouse button may be clicked to paste the current
    318 selection.
    319 
    320 
    321 3.2 Selection with Mouse				*gui-mouse-select*
    322 
    323 The mouse can be used to start a selection.  How depends on the 'mousemodel'
    324 option:
    325 'mousemodel' is "extend": use the right mouse button
    326 'mousemodel' is "popup":  use the left mouse button, while keeping the Shift
    327 key pressed.
    328 
    329 If there was no selection yet, this starts a selection from the old cursor
    330 position to the position pointed to with the mouse.  If there already is a
    331 selection then the closest end will be extended.
    332 
    333 If 'selectmode' contains "mouse", then the selection will be in Select mode.
    334 This means that typing normal text will replace the selection.  See
    335 |Select-mode|.  Otherwise, the selection will be in Visual mode.
    336 
    337 Double clicking may be done to make the selection word-wise, triple clicking
    338 makes it line-wise, and quadruple clicking makes it rectangular block-wise.
    339 
    340 See |gui-selections| on how the selection is used.
    341 
    342 
    343 3.3 Other Text Selection with Mouse		*gui-mouse-modeless*
    344 						*modeless-selection*
    345 A different kind of selection is used when:
    346 - in Command-line mode
    347 - in the Command-line window and pointing in another window
    348 - at the |hit-enter| prompt
    349 - whenever the current mode is not in the 'mouse' option
    350 - when holding the CTRL and SHIFT keys in the GUI
    351 
    352 Since Vim continues like the selection isn't there, and there is no mode
    353 associated with the selection, this is called modeless selection.  Any text in
    354 the Vim window can be selected.  Select the text by pressing the left mouse
    355 button at the start, drag to the end and release.  To extend the selection,
    356 use the right mouse button when 'mousemodel' is "extend", or the left mouse
    357 button with the shift key pressed when 'mousemodel' is "popup".
    358 The selection is removed when the selected text is scrolled or changed.
    359 
    360 On the command line CTRL-Y can be used to copy the selection into the
    361 clipboard.  To do this from Insert mode, use CTRL-O : CTRL-Y <CR>.  When
    362 'guioptions' contains a or A (default on X11), the selection is automatically
    363 copied to the "* register.
    364 
    365 The middle mouse button can then paste the text.  On non-X11 systems, you can
    366 use CTRL-R +.
    367 
    368 
    369 3.4 Using Mouse on Status Lines				*gui-mouse-status*
    370 
    371 Clicking the left or right mouse button on the status line below a Vim
    372 window makes that window the current window.  This actually happens on button
    373 release (to be able to distinguish a click from a drag action).
    374 
    375 With the left mouse button a status line can be dragged up and down, thus
    376 resizing the windows above and below it.  This does not change window focus.
    377 
    378 The same can be used on the vertical separator: click to give the window left
    379 of it focus, drag left and right to make windows wider and narrower.
    380 
    381 
    382 3.5 Various Mouse Clicks				*gui-mouse-various*
    383 
    384     <S-LeftMouse>	Search forward for the word under the mouse click.
    385 			When 'mousemodel' is "popup" this starts or extends a
    386 			selection.
    387     <S-RightMouse>	Search backward for the word under the mouse click.
    388     <C-LeftMouse>	Jump to the tag name under the mouse click.
    389     <C-RightMouse>	Jump back to position before the previous tag jump
    390 			(same as "CTRL-T")
    391 
    392 
    393 3.6 Mouse Mappings					*gui-mouse-mapping*
    394 
    395 The mouse events, complete with modifiers, may be mapped.  Eg: >
    396    :map <S-LeftMouse>     <RightMouse>
    397    :map <S-LeftDrag>      <RightDrag>
    398    :map <S-LeftRelease>   <RightRelease>
    399    :map <2-S-LeftMouse>   <2-RightMouse>
    400    :map <2-S-LeftDrag>    <2-RightDrag>
    401    :map <2-S-LeftRelease> <2-RightRelease>
    402    :map <3-S-LeftMouse>   <3-RightMouse>
    403    :map <3-S-LeftDrag>    <3-RightDrag>
    404    :map <3-S-LeftRelease> <3-RightRelease>
    405    :map <4-S-LeftMouse>   <4-RightMouse>
    406    :map <4-S-LeftDrag>    <4-RightDrag>
    407    :map <4-S-LeftRelease> <4-RightRelease>
    408 These mappings make selection work the way it probably should in a Motif
    409 application, with shift-left mouse allowing for extending the visual area
    410 rather than the right mouse button.
    411 
    412 <MouseMove> may be mapped, but 'mousemoveevent' must be enabled to use the
    413 mapping.
    414 
    415 Mouse mapping with modifiers does not work for modeless selection.
    416 
    417 
    418 3.7 Drag and drop						*drag-n-drop*
    419 
    420 You can drag and drop one or more files into the Vim window, where they will
    421 be opened as if a |:drop| command was used.  You can check if this is
    422 supported with the *drop_file* feature: `has('drop_file')`.
    423 
    424 If you hold down Shift while doing this, Vim changes to the first dropped
    425 file's directory.  If you hold Ctrl Vim will always split a new window for the
    426 file.  Otherwise it's only done if the current buffer has been changed.
    427 
    428 You can also drop a directory on Vim.  This starts the explorer plugin for
    429 that directory (assuming it was enabled, otherwise you'll get an error
    430 message).  Keep Shift pressed to change to the directory instead.
    431 
    432 If Vim happens to be editing a command line, the names of the dropped files
    433 and directories will be inserted at the cursor.  This allows you to use these
    434 names with any Ex command.  Special characters (space, tab, double quote and
    435 '|'; backslash on non-MS-Windows systems) will be escaped.
    436 
    437 ==============================================================================
    438 4. Making GUI Selections				*gui-selections*
    439 
    440 							*quotestar*
    441 You may make selections with the mouse (see |gui-mouse-select|), or by using
    442 Vim's Visual mode (see |v|).  If 'a' is present in 'guioptions', then
    443 whenever a selection is started (Visual or Select mode), or when the selection
    444 is changed, Vim becomes the owner of the windowing system's primary selection
    445 (on MS-Windows the |gui-clipboard| is used; under X11, the |x11-selection| is
    446 used - you should read whichever of these is appropriate now).
    447 
    448 							*clipboard*
    449 There is a special register for storing this selection, it is the "*
    450 register.  Nothing is put in here unless the information about what text is
    451 selected is about to change (e.g. with a left mouse click somewhere), or when
    452 another application wants to paste the selected text.  Then the text is put
    453 in the "* register.  For example, to cut a line and make it the current
    454 selection/put it on the clipboard: >
    455 
    456 	"*dd
    457 
    458 Similarly, when you want to paste a selection from another application, e.g.,
    459 by clicking the middle mouse button, the selection is put in the "* register
    460 first, and then 'put' like any other register.  For example, to put the
    461 selection (contents of the clipboard): >
    462 
    463 	"*p
    464 
    465 When using this register under X11, also see |x11-selection|.  This also
    466 explains the related "+ register.
    467 
    468 Note that when pasting text from one Vim into another separate Vim, the type
    469 of selection (character, line, or block) will also be copied.  For other
    470 applications the type is always character.  However, if the text gets
    471 transferred via the |x11-cut-buffer|, the selection type is ALWAYS lost.
    472 
    473 When the "unnamed" string is included in the 'clipboard' option, the unnamed
    474 register is the same as the "* register.  Thus you can yank to and paste the
    475 selection without prepending "* to commands.
    476 
    477 See also |W23| and |W24|.
    478 
    479 ==============================================================================
    480 5. Menus						*menus*
    481 
    482 For an introduction see |usr_42.txt| in the user manual.
    483 
    484 
    485 5.1 Using Menus						*using-menus*
    486 
    487 Basically, menus can be used just like mappings.  You can define your own
    488 menus, as many as you like.
    489 Long-time Vim users won't use menus much.  But the power is in adding your own
    490 menus and menu items.  They are most useful for things that you can't remember
    491 what the key sequence was.
    492 
    493 For creating menus in a different language, see |:menutrans|.
    494 If you don't want to use menus at all, see |'go-M'|.
    495 
    496 							*menu.vim*
    497 The default menus are read from the file "$VIMRUNTIME/menu.vim".  See
    498 |$VIMRUNTIME| for where the path comes from.  You can set up your own menus.
    499 Starting off with the default set is a good idea.  You can add more items, or,
    500 if you don't like the defaults at all, start with removing all menus
    501 |:unmenu-all|.  You can also avoid the default menus being loaded by adding
    502 this line to your .vimrc file (NOT your .gvimrc file!): >
    503 	:let g:did_install_default_menus = 1
    504 If you also want to avoid the Syntax menu: >
    505 	:let g:did_install_syntax_menu = 1
    506 The first item in the Syntax menu can be used to show all available filetypes
    507 in the menu (which can take a bit of time to load).  If you want to have all
    508 filetypes already present at startup, add: >
    509 	:let g:do_syntax_sel_menu = 1
    510 <				    *menu-lazyload* *g:do_no_lazyload_menus*
    511 The following menuitems show all available color schemes, keymaps and compiler
    512 settings:
    513 	Edit > Color Scheme ~
    514 	Edit > Keymap ~
    515 	Tools > Set Compiler ~
    516 However, they can also take a bit of time to load, because they search all
    517 related files from the directories in 'runtimepath'.  Therefore they are
    518 loaded lazily (by the |CursorHold| event), or you can also load them manually.
    519 If you want to have all these items already present at startup, add: >
    520 	:let g:do_no_lazyload_menus = 1
    521 
    522 Note that the menu.vim is sourced when `:syntax on` or `:filetype on` is
    523 executed or after your .vimrc file is sourced.  This means that the 'encoding'
    524 option and the language of messages (`:language messages`) must be set before
    525 that (if you want to change them).
    526 
    527 							*console-menus*
    528 Although this documentation is in the GUI section, you can actually use menus
    529 in console mode too.  You will have to load |menu.vim| explicitly then, it is
    530 not done by default.  You can use the |:emenu| command and command-line
    531 completion with 'wildmenu' to access the menu entries almost like a real menu
    532 system.  To do this, put these commands in your .vimrc file: >
    533 	:source $VIMRUNTIME/menu.vim
    534 	:set wildmenu
    535 	:set cpo-=<
    536 	:set wcm=<C-Z>
    537 	:map <F4> :emenu <C-Z>
    538 Pressing <F4> will start the menu.  You can now use the cursor keys to select
    539 a menu entry.  Hit <Enter> to execute it.  Hit <Esc> if you want to cancel.
    540 This does require the |+menu| feature enabled at compile time.
    541 
    542 							*tear-off-menus*
    543 GTK+ 2 and Motif support Tear-off menus.  These are sort of sticky menus or
    544 pop-up menus that are present all the time.  If the resizing does not work
    545 correctly, this may be caused by using something like "Vim*geometry" in the
    546 defaults.  Use "Vim.geometry" instead.
    547 
    548 As to GTK+ 3, tear-off menus have been deprecated since GTK+ 3.4.
    549 Accordingly, they are disabled if gvim is linked against GTK+ 3.4 or later.
    550 
    551 The Win32 GUI version emulates Motif's tear-off menus.  Actually, a Motif user
    552 will spot the differences easily, but hopefully they're just as useful.  You
    553 can also use the |:tearoff| command together with |hidden-menus| to create
    554 floating menus that do not appear on the main menu bar.
    555 
    556 
    557 5.2 Creating New Menus					*creating-menus*
    558 
    559 				*:me*  *:menu*   *:noreme*  *:noremenu*
    560 				*E330* *E327* *E331* *E336* *E333*
    561 				*E328* *E329* *E337* *E792*
    562 To create a new menu item, use the ":menu" commands.  They are mostly like
    563 the ":map" set of commands (see |map-modes|), but the first argument is a menu
    564 item name, given as a path of menus and submenus with a '.' between them,
    565 e.g.: >
    566 
    567    :menu File.Save  :w<CR>
    568    :inoremenu File.Save  <C-O>:w<CR>
    569    :menu Edit.Big\ Changes.Delete\ All\ Spaces  :%s/[ ^I]//g<CR>
    570 
    571 This last one will create a new item in the menu bar called "Edit", holding
    572 the mouse button down on this will pop up a menu containing the item
    573 "Big Changes", which is a sub-menu containing the item "Delete All Spaces",
    574 which when selected, performs the operation.
    575 
    576 To create a menu for terminal mode, use |:tlmenu| instead of |:tmenu| unlike
    577 key mapping (|:tmap|).  This is because |:tmenu| is already used for defining
    578 tooltips for menus.  See |terminal-typing|.
    579 
    580 Special characters in a menu name:
    581 
    582 							*menu-shortcut*
    583 	&	The next character is the shortcut key.  Make sure each
    584 		shortcut key is only used once in a (sub)menu.  If you want to
    585 		insert a literal "&" in the menu name use "&&".
    586 							*menu-text*
    587 	<Tab>	Separates the menu name from right-aligned text.  This can be
    588 		used to show the equivalent typed command.  The text "<Tab>"
    589 		can be used here for convenience.  If you are using a real
    590 		tab, don't forget to put a backslash before it!
    591 Example: >
    592 
    593    :amenu &File.&Open<Tab>:e  :browse e<CR>
    594 
    595 [typed literally]
    596 With the shortcut "F" (while keeping the <Alt> key pressed), and then "O",
    597 this menu can be used.  The second part is shown as "Open     :e".  The ":e"
    598 is right aligned, and the "O" is underlined, to indicate it is the shortcut.
    599 
    600 					*:am*  *:amenu*  *:an*      *:anoremenu*
    601 The ":amenu" command can be used to define menu entries for all modes at once,
    602 except for Terminal mode.  To make the command work correctly, a character is
    603 automatically inserted for some modes:
    604 	mode		inserted	appended	~
    605 	Normal		nothing		nothing
    606 	Visual		<C-C>		<C-\><C-G>
    607 	Insert		<C-\><C-O>
    608 	Cmdline		<C-C>		<C-\><C-G>
    609 	Op-pending	<C-C>		<C-\><C-G>
    610 
    611 Appending CTRL-\ CTRL-G is for going back to insert mode when 'insertmode' is
    612 set. |CTRL-\_CTRL-G|
    613 
    614 Example: >
    615 
    616    :amenu File.Next	:next^M
    617 
    618 is equal to: >
    619 
    620    :nmenu File.Next	:next^M
    621    :vmenu File.Next	^C:next^M^\^G
    622    :imenu File.Next	^\^O:next^M
    623    :cmenu File.Next	^C:next^M^\^G
    624    :omenu File.Next	^C:next^M^\^G
    625 
    626 Careful: In Insert mode this only works for a SINGLE Normal mode command,
    627 because of the CTRL-O.  If you have two or more commands, you will need to use
    628 the ":imenu" command.  For inserting text in any mode, you can use the
    629 expression register: >
    630 
    631    :amenu Insert.foobar   "='foobar'<CR>P
    632 
    633 The special text <Cmd> begins a "command menu", it executes the command
    634 directly without changing modes.  Where you might use ":...<CR>" you can
    635 instead use "<Cmd>...<CR>".  See |<Cmd>| for more info.  Example: >
    636 	anoremenu File.Next <Cmd>next<CR>
    637 
    638 Note that the '<' and 'k' flags in 'cpoptions' also apply here (when
    639 included they make the <> form and raw key codes not being recognized).
    640 
    641 Note that <Esc> in Cmdline mode executes the command, like in a mapping.  This
    642 is Vi compatible.  Use CTRL-C to quit Cmdline mode.
    643 
    644 		*:nme* *:nmenu*  *:nnoreme* *:nnoremenu* *:nunme* *:nunmenu*
    645 Menu commands starting with "n" work in Normal mode. |mapmode-n|
    646 
    647 		*:ome* *:omenu*  *:onoreme* *:onoremenu* *:ounme* *:ounmenu*
    648 Menu commands starting with "o" work in Operator-pending mode. |mapmode-o|
    649 
    650 		*:vme* *:vmenu*  *:vnoreme* *:vnoremenu* *:vunme* *:vunmenu*
    651 Menu commands starting with "v" work in Visual mode. |mapmode-v|
    652 
    653 		*:xme* *:xmenu*  *:xnoreme* *:xnoremenu* *:xunme* *:xunmenu*
    654 Menu commands starting with "x" work in Visual and Select mode. |mapmode-x|
    655 
    656 		*:sme* *:smenu*  *:snoreme* *:snoremenu* *:sunme* *:sunmenu*
    657 Menu commands starting with "s" work in Select mode. |mapmode-s|
    658 
    659 		*:ime* *:imenu*  *:inoreme* *:inoremenu* *:iunme* *:iunmenu*
    660 Menu commands starting with "i" work in Insert mode. |mapmode-i|
    661 
    662 		*:cme* *:cmenu*  *:cnoreme* *:cnoremenu* *:cunme* *:cunmenu*
    663 Menu commands starting with "c" work in Cmdline mode. |mapmode-c|
    664 
    665 		*:tlm* *:tlmenu* *:tln*     *:tlnoremenu* *:tlu*   *:tlunmenu*
    666 Menu commands starting with "tl" work in Terminal mode. |mapmode-t|
    667 
    668 						*:menu-<silent>* *:menu-silent*
    669 To define a menu which will not be echoed on the command line, add
    670 "<silent>" as the first argument.  Example: >
    671 	:menu <silent> Settings.Ignore\ case  :set ic<CR>
    672 The ":set ic" will not be echoed when using this menu.  Messages from the
    673 executed command are still given though.  To shut them up too, add a ":silent"
    674 in the executed command: >
    675 	:menu <silent> Search.Header :exe ":silent normal /Header\r"<CR>
    676 "<silent>" may also appear just after "<special>" or "<script>".
    677 
    678 					*:menu-<special>* *:menu-special*
    679 Define a menu with <> notation for special keys, even though the "<" flag
    680 may appear in 'cpoptions'.  This is useful if the side effect of setting
    681 'cpoptions' is not desired.  Example: >
    682 	:menu <special> Search.Header /Header<CR>
    683 "<special>" must appear as the very first argument to the ":menu" command or
    684 just after "<silent>" or "<script>".
    685 
    686 						*:menu-<script>* *:menu-script*
    687 The "to" part of the menu will be inspected for mappings.  If you don't want
    688 this, use the ":noremenu" command (or the similar one for a specific mode).
    689 If you do want to use script-local mappings, add "<script>" as the very first
    690 argument to the ":menu" command or just after "<silent>" or "<special>".
    691 
    692 							*menu-priority*
    693 You can give a priority to a menu.  Menus with a higher priority go more to
    694 the right.  The priority is given as a number before the ":menu" command.
    695 Example: >
    696 	:80menu Buffer.next :bn<CR>
    697 
    698 The default menus have these priorities:
    699 	File		10
    700 	Edit		20
    701 	Tools		40
    702 	Syntax		50
    703 	Buffers		60
    704 	Window		70
    705 	Help		9999
    706 
    707 When no or zero priority is given, 500 is used.
    708 The priority for the PopUp menu is not used.
    709 
    710 The Help menu will be placed on the far right side of the menu bar on systems
    711 which support this (Motif and GTK+).  For GTK+ 2 and 3, this is not done
    712 anymore because right-aligning the Help menu is now discouraged UI design.
    713 
    714 You can use a priority higher than 9999, to make it go after the Help menu,
    715 but that is non-standard and is discouraged.  The highest possible priority is
    716 about 32000.  The lowest is 1.
    717 
    718 							*sub-menu-priority*
    719 The same mechanism can be used to position a sub-menu.  The priority is then
    720 given as a dot-separated list of priorities, before the menu name: >
    721 	:menu 80.500 Buffer.next :bn<CR>
    722 Giving the sub-menu priority is only needed when the item is not to be put
    723 in a normal position.  For example, to put a sub-menu before the other items: >
    724 	:menu 80.100 Buffer.first :brew<CR>
    725 Or to put a sub-menu after the other items, and further items with default
    726 priority will be put before it: >
    727 	:menu 80.900 Buffer.last :blast<CR>
    728 When a number is missing, the default value 500 will be used: >
    729 	:menu .900 myMenu.test :echo "text"<CR>
    730 The menu priority is only used when creating a new menu.  When it already
    731 existed, e.g., in another mode, the priority will not change.  Thus, the
    732 priority only needs to be given the first time a menu is used.
    733 An exception is the PopUp menu.  There is a separate menu for each mode
    734 (Normal, Op-pending, Visual, Insert, Cmdline).  The order in each of these
    735 menus can be different.  This is different from menu-bar menus, which have
    736 the same order for all modes.
    737 NOTE: sub-menu priorities currently don't work for all versions of the GUI.
    738 
    739 							*menu-separator* *E332*
    740 Menu items can be separated by a special item that inserts some space between
    741 items.  Depending on the system this is displayed as a line or a dotted line.
    742 These items must start with a '-' and end in a '-'.  The part in between is
    743 used to give it a unique name.  Priorities can be used as with normal items.
    744 Example: >
    745 	:menu Example.item1	:do something
    746 	:menu Example.-Sep-	:
    747 	:menu Example.item2	:do something different
    748 Note that the separator also requires a rhs.  It doesn't matter what it is,
    749 because the item will never be selected.  Use a single colon to keep it
    750 simple.
    751 
    752 							*gui-toolbar*
    753 The toolbar is currently available in the Win32, Motif, GTK+ (X11),
    754 and Photon GUI.  It should turn up in other GUIs in due course.  The
    755 default toolbar is setup in menu.vim.
    756 The display of the toolbar is controlled by the 'guioptions' letter 'T'.  You
    757 can thus have menu & toolbar together, or either on its own, or neither.
    758 The appearance is controlled by the 'toolbar' option.  You can choose between
    759 an image, text or both.
    760 
    761 							*toolbar-icon*
    762 The toolbar is defined as a special menu called ToolBar, which only has one
    763 level.  Vim interprets the items in this menu as follows:
    764 1)  If an "icon=" argument was specified, the file with this name is used.
    765     The file can either be specified with the full path or with the base name.
    766     In the last case it is searched for in the "bitmaps" directory in
    767     'runtimepath', like in point 3.  Examples: >
    768 	:amenu icon=/usr/local/pixmaps/foo_icon.xpm ToolBar.Foo :echo "Foo"<CR>
    769 	:amenu icon=FooIcon ToolBar.Foo :echo "Foo"<CR>
    770 <   Note that in the first case the extension is included, while in the second
    771     case it is omitted.
    772     If the file cannot be opened the next points are tried.
    773     A space in the file name must be escaped with a backslash.
    774     A menu priority must come _after_ the icon argument: >
    775 	:amenu icon=foo 1.42 ToolBar.Foo :echo "42!"<CR>
    776 2)  An item called 'BuiltIn##', where ## is a number, is taken as number ## of
    777     the built-in bitmaps available in Vim.  Currently there are 31 numbered
    778     from 0 to 30 which cover most common editing operations |builtin-tools|. >
    779 	:amenu ToolBar.BuiltIn22 :call SearchNext("back")<CR>
    780 3)  An item with another name is first searched for in the directory
    781     "bitmaps" in 'runtimepath'.  If found, the bitmap file is used as the
    782     toolbar button image.  Note that the exact filename is OS-specific: For
    783     example, under Win32 the command >
    784 	:amenu ToolBar.Hello :echo "hello"<CR>
    785 <   would find the file 'hello.bmp'.  Under GTK+/X11 it is 'Hello.xpm'.  With
    786     GTK+ 2 the files 'Hello.png', 'Hello.xpm' and 'Hello.bmp' are checked for
    787     existence, and the first one found would be used.
    788     For MS-Windows and GTK+ 2 the bitmap is scaled to fit the button.  For
    789     MS-Windows a size of 18 by 18 pixels works best.
    790     For MS-Windows the bitmap should have 16 colors with the standard palette.
    791     The light grey pixels will be changed to the Window frame color and the
    792     dark grey pixels to the window shadow color.  More colors might also work,
    793     depending on your system.
    794 4)  If the bitmap is still not found, Vim checks for a match against its list
    795     of built-in names.  Each built-in button image has a name.
    796     So the command >
    797 	:amenu ToolBar.Open :e
    798 <   will show the built-in "open a file" button image if no open.bmp exists.
    799     All the built-in names can be seen used in menu.vim.
    800 5)  If all else fails, a blank, but functioning, button is displayed.
    801 
    802 							*builtin-tools*
    803 nr  Name		Normal action  ~
    804 00  New			open new window
    805 01  Open		browse for file to open in current window
    806 02  Save		write buffer to file
    807 03  Undo		undo last change
    808 04  Redo		redo last undone change
    809 05  Cut			delete selected text to clipboard
    810 06  Copy		copy selected text to clipboard
    811 07  Paste		paste text from clipboard
    812 08  Print		print current buffer
    813 09  Help		open a buffer on Vim's builtin help
    814 10  Find		start a search command
    815 11  SaveAll		write all modified buffers to file
    816 12  SaveSesn		write session file for current situation
    817 13  NewSesn		write new session file
    818 14  LoadSesn		load session file
    819 15  RunScript		browse for file to run as a Vim script
    820 16  Replace		prompt for substitute command
    821 17  WinClose		close current window
    822 18  WinMax		make current window use many lines
    823 19  WinMin		make current window use few lines
    824 20  WinSplit		split current window
    825 21  Shell		start a shell
    826 22  FindPrev		search again, backward
    827 23  FindNext		search again, forward
    828 24  FindHelp		prompt for word to search help for
    829 25  Make		run make and jump to first error
    830 26  TagJump		jump to tag under the cursor
    831 27  RunCtags		build tags for files in current directory
    832 28  WinVSplit		split current window vertically
    833 29  WinMaxWidth		make current window use many columns
    834 30  WinMinWidth		make current window use few columns
    835 
    836 					*hidden-menus* *win32-hidden-menus*
    837 In the Win32 and GTK+ GUI, starting a menu name with ']' excludes that menu
    838 from the main menu bar.  You must then use the |:popup| or |:tearoff| command
    839 to display it.
    840 
    841 					*window-toolbar* *WinBar*
    842 Each window can have a local toolbar.  This uses the first line of the window,
    843 thus reduces the space for the text by one line.  The items in the toolbar
    844 must start with "WinBar".
    845 
    846 Only text can be used.  When using Unicode, special characters can be used to
    847 make the items look like icons.
    848 
    849 If the items do not fit then the last ones cannot be used.  The toolbar does
    850 not wrap.
    851 
    852 Note that Vim may be in any mode when executing these commands.  The menu
    853 should be defined for Normal mode and will be executed without changing the
    854 current mode.  Thus if the current window is in Visual mode and the menu
    855 command does not intentionally change the mode, Vim will remain in Visual
    856 mode.  Best is to use `:nnoremenu` to avoid side effects.
    857 
    858 Example for debugger tools: >
    859 	nnoremenu 1.10 WinBar.Step :Step<CR>
    860 	nnoremenu 1.20 WinBar.Next :Next<CR>
    861 	nnoremenu 1.30 WinBar.Finish :Finish<CR>
    862 	nnoremenu 1.40 WinBar.Cont :Continue<CR>
    863 <					*hl-ToolbarLine* *hl-ToolbarButton*
    864 The window toolbar uses the ToolbarLine and ToolbarButton highlight groups.
    865 
    866 When splitting the window the window toolbar is not copied to the new window.
    867 
    868 							*popup-menu*
    869 In the Win32, GTK+, Motif and Photon GUI, you can define the
    870 special menu "PopUp".  This is the menu that is displayed when the right mouse
    871 button is pressed, if 'mousemodel' is set to popup or popup_setpos.
    872 Example: >
    873     nnoremenu 1.40 PopUp.&Paste	"+gP
    874     menu PopUp
    875 
    876 
    877 5.3 Showing What Menus Are Mapped To			*showing-menus*
    878 
    879 To see what an existing menu is mapped to, use just one argument after the
    880 menu commands (just like you would with the ":map" commands).  If the menu
    881 specified is a submenu, then all menus under that hierarchy will be shown.
    882 If no argument is given after :menu at all, then ALL menu items are shown
    883 for the appropriate mode (e.g., Command-line mode for :cmenu).
    884 
    885 Special characters in the list, just before the rhs:
    886 *	The menu was defined with "nore" to disallow remapping.
    887 &	The menu was defined with "<script>" to allow remapping script-local
    888 	mappings only.
    889 s	The menu was defined with "<silent>" to avoid showing what it is
    890 	mapped to when triggered.
    891 -	The menu was disabled.
    892 
    893 Note that hitting <Tab> while entering a menu name after a menu command may
    894 be used to complete the name of the menu item.
    895 
    896 It is not allowed to change menus while listing them.  *E1310*
    897 This doesn't normally happen, only when, for example, you would have a timer
    898 callback define a menu and the user lists menus in a way it shows
    899 |more-prompt|.
    900 
    901 
    902 5.4 Executing Menus					*execute-menus*
    903 
    904 						*:em*  *:emenu* *E334* *E335*
    905 :[range]em[enu] {menu}		Execute {menu} from the command line.
    906 				The default is to execute the Normal mode
    907 				menu.  If a range is specified, it executes
    908 				the Visual mode menu.
    909 				If used from <c-o>, it executes the
    910 				insert-mode menu Eg: >
    911 	:emenu File.Exit
    912 
    913 :[range]em[enu] {mode} {menu}	Like above, but execute the menu for {mode}:
    914 				    'n': |:nmenu|  Normal mode
    915 				    'v': |:vmenu|  Visual mode
    916 				    's': |:smenu|  Select mode
    917 				    'o': |:omenu|  Operator-pending mode
    918 				    't': |:tlmenu| Terminal mode
    919 				    'i': |:imenu|  Insert mode
    920 				    'c': |:cmenu|  Cmdline mode
    921 
    922 
    923 If the console-mode vim has been compiled with WANT_MENU defined, you can
    924 use :emenu to access useful menu items you may have got used to from GUI
    925 mode.  See 'wildmenu' for an option that works well with this.  See
    926 |console-menus| for an example.
    927 
    928 When using a range, if the lines match with '<,'>, then the menu is executed
    929 using the last visual selection.
    930 
    931 
    932 5.5 Deleting Menus					*delete-menus*
    933 
    934 						*:unme*  *:unmenu*
    935 						*:aun*   *:aunmenu*
    936 To delete a menu item or a whole submenu, use the unmenu commands, which are
    937 analogous to the unmap commands.  Eg: >
    938     :unmenu! Edit.Paste
    939 
    940 This will remove the Paste item from the Edit menu for Insert and
    941 Command-line modes.
    942 
    943 Note that hitting <Tab> while entering a menu name after an umenu command
    944 may be used to complete the name of the menu item for the appropriate mode.
    945 
    946 To remove all menus use:			*:unmenu-all*  >
    947 	:unmenu *	" remove all menus in Normal and visual mode
    948 	:unmenu! *	" remove all menus in Insert and Command-line mode
    949 	:aunmenu *	" remove all menus in all modes, except for Terminal
    950 			" mode
    951 	:tlunmenu *	" remove all menus in Terminal mode
    952 
    953 If you want to get rid of the menu bar: >
    954 	:set guioptions-=m
    955 
    956 
    957 5.6 Disabling Menus					*disable-menus*
    958 
    959 						*:menu-disable* *:menu-enable*
    960 If you do not want to remove a menu, but disable it for a moment, this can be
    961 done by adding the "enable" or "disable" keyword to a ":menu" command.
    962 Examples: >
    963 	:menu disable &File.&Open\.\.\.
    964 	:amenu enable *
    965 	:amenu disable &Tools.*
    966 
    967 The command applies to the modes as used with all menu commands.  Note that
    968 characters like "&" need to be included for translated names to be found.
    969 When the argument is "*", all menus are affected.  Otherwise the given menu
    970 name and all existing submenus below it are affected.
    971 
    972 
    973 5.7 Examples for Menus					*menu-examples*
    974 
    975 Here is an example on how to add menu items with menus.  You can add a menu
    976 item for the keyword under the cursor.  The register "z" is used. >
    977 
    978   :nmenu Words.Add\ Var		wb"zye:menu! Words.<C-R>z <C-R>z<CR>
    979   :nmenu Words.Remove\ Var	wb"zye:unmenu! Words.<C-R>z<CR>
    980   :vmenu Words.Add\ Var		"zy:menu! Words.<C-R>z <C-R>z <CR>
    981   :vmenu Words.Remove\ Var	"zy:unmenu! Words.<C-R>z<CR>
    982   :imenu Words.Add\ Var		<Esc>wb"zye:menu! Words.<C-R>z <C-R>z<CR>a
    983   :imenu Words.Remove\ Var	<Esc>wb"zye:unmenu! Words.<C-R>z<CR>a
    984 
    985 (the rhs is in <> notation, you can copy/paste this text to try out the
    986 mappings, or put these lines in your gvimrc; "<C-R>" is CTRL-R, "<CR>" is
    987 the <CR> key.  |<>|)
    988 
    989 							*tooltips* *menu-tips*
    990 5.8 Tooltips & Menu tips
    991 
    992 See section |42.4| in the user manual.
    993 
    994 							*:tmenu* *:tm*
    995 :tm[enu] {menupath} {rhs}	Define a tip for a menu or tool.  {only in
    996 				X11 and Win32 GUI}
    997 
    998 :tm[enu] [menupath]		List menu tips. {only in X11 and Win32 GUI}
    999 
   1000 							*:tunmenu* *:tu*
   1001 :tu[nmenu] {menupath}		Remove a tip for a menu or tool.
   1002 				{only in X11 and Win32 GUI}
   1003 
   1004 Note: To create menus for terminal mode, use |:tlmenu| instead.
   1005 
   1006 When a tip is defined for a menu item, it appears in the command-line area
   1007 when the mouse is over that item, much like a standard Windows menu hint in
   1008 the status bar.  (Except when Vim is in Command-line mode, when of course
   1009 nothing is displayed.)
   1010 When a tip is defined for a ToolBar item, it appears as a tooltip when the
   1011 mouse pauses over that button, in the usual fashion.  Use the |hl-Tooltip|
   1012 highlight group to change its colors.
   1013 
   1014 A "tip" can be defined for each menu item.  For example, when defining a menu
   1015 item like this: >
   1016 	:amenu MyMenu.Hello :echo "Hello"<CR>
   1017 The tip is defined like this: >
   1018 	:tmenu MyMenu.Hello Displays a greeting.
   1019 And delete it with: >
   1020 	:tunmenu MyMenu.Hello
   1021 
   1022 Tooltips are currently only supported for the X11 and Win32 GUI.  However,
   1023 they should appear for the other gui platforms in the not too distant future.
   1024 
   1025 The ":tmenu" command works just like other menu commands, it uses the same
   1026 arguments.  ":tunmenu" deletes an existing menu tip, in the same way as the
   1027 other unmenu commands.
   1028 
   1029 If a menu item becomes invalid (i.e. its actions in all modes are deleted) Vim
   1030 deletes the menu tip (and the item) for you.  This means that :aunmenu deletes
   1031 a menu item - you don't need to do a :tunmenu as well.
   1032 
   1033 
   1034 5.9 Popup Menus
   1035 
   1036 In the Win32 and GTK+ GUI, you can cause a menu to popup at the cursor.
   1037 This behaves similarly to the PopUp menus except that any menu tree can
   1038 be popped up.
   1039 
   1040 This command is for backwards compatibility, using it is discouraged, because
   1041 it behaves in a strange way.
   1042 
   1043 							*:popup* *:popu*
   1044 :popu[p] {name}			Popup the menu {name}.  The menu named must
   1045 				have at least one subentry, but need not
   1046 				appear on the menu-bar (see |hidden-menus|).
   1047 				{only available for Win32 and GTK GUI or in
   1048 				the terminal}
   1049 
   1050 :popu[p]! {name}		Like above, but use the position of the mouse
   1051 				pointer instead of the cursor.
   1052 				In the terminal this is the last known
   1053 				position, which is usually at the last click
   1054 				or release (mouse movement is irrelevant).
   1055 
   1056 Example: >
   1057 	:popup File
   1058 will make the "File" menu (if there is one) appear at the text cursor (mouse
   1059 pointer if ! was used). >
   1060 
   1061 	:amenu ]Toolbar.Make	:make<CR>
   1062 	:popup ]Toolbar
   1063 This creates a popup menu that doesn't exist on the main menu-bar.
   1064 
   1065 Note that in the GUI the :popup command will return immediately, before a
   1066 selection has been made.  In the terminal the commands waits for the user to
   1067 make a selection.
   1068 
   1069 Note that a menu that starts with ']' will not be displayed.
   1070 
   1071 ==============================================================================
   1072 6. Font
   1073 
   1074 This section describes font related options.
   1075 
   1076 GUIFONT							*gui-font*
   1077 
   1078 'guifont' is the option that tells Vim what font to use.  In its simplest form
   1079 the value is just one font name.  It can also be a list of font names
   1080 separated with commas.  The first valid font is used.  When no valid font can
   1081 be found you will get an error message.
   1082 
   1083 On systems where 'guifontset' is supported (X11) and 'guifontset' is not
   1084 empty, then 'guifont' is not used.  See |xfontset|.
   1085 
   1086 Note: As to the GTK GUIs, no error is given against any invalid names, and the
   1087 first element of the list is always picked up and made use of.  This is
   1088 because, instead of identifying a given name with a font, the GTK GUIs use it
   1089 to construct a pattern and try to look up a font which best matches the
   1090 pattern among available fonts, and this way, the matching never fails.  An
   1091 invalid name doesn't matter because a number of font properties other than
   1092 name will do to get the matching done.
   1093 
   1094 Spaces after a comma are ignored.  To include a comma in a font name precede
   1095 it with a backslash.  Setting an option requires an extra backslash before a
   1096 space and a backslash.  See also |option-backslash|.  For example: >
   1097     :set guifont=Screen15,\ 7x13,font\\,with\\,commas
   1098 will make Vim try to use the font "Screen15" first, and if it fails it will
   1099 try to use "7x13" and then "font,with,commas" instead.
   1100 
   1101 If none of the fonts can be loaded, Vim will keep the current setting.  If an
   1102 empty font list is given, Vim will try using other resource settings (for X,
   1103 it will use the Vim.font resource), and finally it will try some builtin
   1104 default which should always be there ("7x13" in the case of X).  The font
   1105 names given should be "normal" fonts.  Vim will try to find the related bold
   1106 and italic fonts.
   1107 
   1108 For Win32, GTK, Motif, Mac OS and Photon: >
   1109     :set guifont=*
   1110 will bring up a font requester, where you can pick the font you want.
   1111 
   1112 The font name depends on the GUI used.  See |setting-guifont| for a way to set
   1113 'guifont' for various systems.
   1114 
   1115 For the GTK+ 2 and 3 GUIs, the font name looks like this: >
   1116     :set guifont=Andale\ Mono\ 11
   1117 That's all.  XLFDs are not used.  For Chinese this is reported to work well: >
   1118     if has("gui_gtk2")
   1119       set guifont=Bitstream\ Vera\ Sans\ Mono\ 12,Fixed\ 12
   1120       set guifontwide=Microsoft\ Yahei\ 12,WenQuanYi\ Zen\ Hei\ 12
   1121     endif
   1122 <
   1123 (Replace gui_gtk2 with gui_gtk3 for the GTK+ 3 GUI)
   1124 
   1125 For Mac OSX you can use something like this: >
   1126     :set guifont=Monaco:h10
   1127 
   1128 Mono-spaced fonts					*E236*
   1129 
   1130 Note that the fonts must be mono-spaced (all characters have the same width).
   1131 An exception is GTK: all fonts are accepted, but mono-spaced fonts look best.
   1132 
   1133 To preview a font on X11, you might be able to use the "xfontsel" program.
   1134 The "xlsfonts" program gives a list of all available fonts.
   1135 
   1136 For the Win32 GUI					*E244* *E245*
   1137 - Takes these options in the font name (use a ':' to separate the options):
   1138 	hXX - height is XX (points, can be floating-point)
   1139 	wXX - width is XX (points, can be floating-point)
   1140 	WXX - weight is XX (see Note on Weights below)
   1141 	b   - bold. This is equivalent to setting the weight to 700.
   1142 	i   - italic
   1143 	u   - underline
   1144 	s   - strikeout
   1145 	cXX - character set XX.  Valid charsets are: ANSI, ARABIC, BALTIC,
   1146 	      CHINESEBIG5, DEFAULT, EASTEUROPE, GB2312, GREEK, HANGEUL,
   1147 	      HEBREW, JOHAB, MAC, OEM, RUSSIAN, SHIFTJIS, SYMBOL, THAI,
   1148 	      TURKISH and VIETNAMESE.  Normally you would use "cDEFAULT".
   1149 	qXX - quality XX.  Valid quality names are: PROOF, DRAFT, ANTIALIASED,
   1150 	      NONANTIALIASED, CLEARTYPE and DEFAULT.  Normally you would use
   1151 	      "qDEFAULT".
   1152 	      Some quality values are not supported in legacy OSs.
   1153 	fXX - OpenType font feature.  Specify a single feature as
   1154 	      tag=value, where tag is a 4-character OpenType feature
   1155 	      tag and value is the parameter (0 to disable, 1 or
   1156 	      higher to enable/select variant).  Multiple features
   1157 	      can be specified by repeating the ":f" option.
   1158 	      This only takes effect when 'renderoptions' is set to use
   1159 	      DirectWrite (type:directx).  Default features (calt, liga,
   1160 	      etc.) are preserved unless explicitly overridden.
   1161 	      Example: ":fss19=1:fcalt=0" enables Stylistic Set 19
   1162 	      and disables Contextual Alternates.
   1163 - A '_' can be used in the place of a space, so you don't need to use
   1164   backslashes to escape the spaces.
   1165 Examples: >
   1166     :set guifont=courier_new:h12:w5:b:cRUSSIAN
   1167     :set guifont=Andale_Mono:h7.5:w4.5
   1168     :set guifont=Cascadia_Code:h14:fss19=1:fcalt=1:fliga=1
   1169 
   1170 See also |font-sizes|, 'guiligatures' and 'renderoptions' (MS-Windows only).
   1171 
   1172 Note on Weights: Fonts often come with a variety of weights.  "Normal" weights
   1173 in Windows have a value of 400 and, left unspecified, this is the value that
   1174 will be used when attempting to find fonts.  Windows will often match fonts
   1175 based on their weight with higher priority than the font name which means a
   1176 Book or Medium variant of a font might be used despite specifying a Light or
   1177 ExtraLight variant.  If you are experiencing heavier weight substitution, then
   1178 explicitly setting a lower weight value may mitigate against this unwanted
   1179 substitution.
   1180 
   1181 
   1182 GUIFONTWIDE						*gui-fontwide*
   1183 
   1184 When not empty, 'guifontwide' specifies a comma-separated list of fonts to be
   1185 used for double-width characters.  The first font that can be loaded is used.
   1186 
   1187 Note: The size of these fonts must be exactly twice as wide as the one
   1188 specified with 'guifont' and the same height.  If there is a mismatch then the
   1189 text will not be drawn correctly.
   1190 
   1191 All GUI versions but GTK+:
   1192 
   1193 'guifontwide' is only used when 'encoding' is set to "utf-8" and 'guifontset'
   1194 is empty or invalid.
   1195 When 'guifont' is set and a valid font is found in it and 'guifontwide' is
   1196 empty Vim will attempt to find a matching double-width font and set
   1197 'guifontwide' to it.
   1198 
   1199 GTK+ GUI only:				*guifontwide_gtk*
   1200 
   1201 If set and valid, 'guifontwide' is always used for double width characters,
   1202 even if 'encoding' is not set to "utf-8".
   1203 Vim does not attempt to find an appropriate value for 'guifontwide'
   1204 automatically.  If 'guifontwide' is empty Pango/Xft will choose the font for
   1205 characters not available in 'guifont'.  Thus you do not need to set
   1206 'guifontwide' at all unless you want to override the choice made by Pango/Xft.
   1207 
   1208 Windows +multibyte only:		*guifontwide_win_mbyte*
   1209 
   1210 If set and valid, 'guifontwide' is used for IME instead of 'guifont'.
   1211 
   1212 ==============================================================================
   1213 7. Extras						*gui-extras*
   1214 
   1215 This section describes other features which are related to the GUI.
   1216 
   1217 - With the GUI, there is no wait for one second after hitting escape, because
   1218   the key codes don't start with <Esc>.
   1219 
   1220 - Typing ^V followed by a special key in the GUI will insert "<Key>", since
   1221   the internal string used is meaningless.  Modifiers may also be held down to
   1222   get "<Modifiers-Key>".
   1223 
   1224 - In the GUI, the modifiers SHIFT, CTRL, and ALT (or META) may be used within
   1225   mappings of special keys and mouse events.
   1226   E.g.: :map <M-LeftDrag> <LeftDrag>
   1227 
   1228 - In the GUI, several normal keys may have modifiers in mappings etc, these
   1229   are <Space>, <Tab>, <NL>, <CR>, <Esc>.
   1230 
   1231 - To check in a Vim script if the GUI is being used, you can use something
   1232   like this: >
   1233 
   1234 	if has("gui_running")
   1235 	   echo "yes, we have a GUI"
   1236 	else
   1237 	   echo "Boring old console"
   1238 	endif
   1239 <							*setting-guifont*
   1240 - When you use the same vimrc file on various systems, you can use something
   1241   like this to set options specifically for each type of GUI: >
   1242 
   1243 	if has("gui_running")
   1244 	    if has("gui_gtk")
   1245 		:set guifont=Luxi\ Mono\ 12
   1246 	    elseif has("x11")
   1247 		:set guifont=*-lucidatypewriter-medium-r-normal-*-*-180-*-*-m-*-*
   1248 	    elseif has("gui_win32")
   1249 		:set guifont=Luxi_Mono:h12:cANSI
   1250 	    endif
   1251 	endif
   1252 
   1253 A recommended Japanese font is MS Mincho.  You can find info here:
   1254 https://learn.microsoft.com/en-us/typography/font-list/ms-mincho
   1255 It should be distributed with Windows.
   1256 
   1257 
   1258 Full Screen						*gui-fullscreen*
   1259 
   1260 Fullscreen mode is currently only supported in the Windows and GTK GUI
   1261 versions of Vim.
   1262 
   1263 To enable fullscreen mode in the GUI version of Vim, add the "s" flag to the
   1264 'guioptions' setting.
   1265 
   1266 For convenience, you can define a command or mapping to toggle fullscreen
   1267 mode:
   1268 >
   1269 	command ToggleFullscreen {
   1270 	  if &guioptions =~# 's'
   1271 	    set guioptions-=s
   1272 	  else
   1273 	    set guioptions+=s
   1274 	  endif
   1275 	}
   1276 
   1277 	map <expr> <F11> &go =~# 's' ? ":se go-=s<CR>" : ":se go+=s<CR>"
   1278 
   1279 The fullscreen mode will occupy the entire screen area while hiding window
   1280 decorations such as the title bar and borders.
   1281 
   1282 
   1283 ==============================================================================
   1284 8. Shell Commands					*gui-shell*
   1285 
   1286 For the X11 GUI the external commands are executed inside the gvim window.
   1287 See |gui-pty|.
   1288 
   1289 WARNING: Executing an external command from the X11 GUI will not always work.
   1290 "normal" commands like "ls", "grep" and "make" mostly work fine.
   1291 Commands that require an intelligent terminal like "less" and "ispell" won't
   1292 work.  Some may even hang and need to be killed from another terminal.  So be
   1293 careful!
   1294 
   1295 For the Win32 GUI the external commands are executed in a separate window.
   1296 See |gui-shell-win32|.
   1297 
   1298  vim:tw=78:sw=4:ts=8:noet:ft=help:norl: