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: