gui_w32.txt (21421B)
1 *gui_w32.txt* For Vim version 9.2. Last change: 2026 May 25 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 Vim's Win32 Graphical User Interface *gui-w32* *win32-gui* 8 9 1. Starting the GUI |gui-w32-start| 10 2. Vim as default editor |vim-default-editor| 11 3. Using the clipboard |gui-clipboard| 12 4. Shell Commands |gui-shell-win32| 13 5. Special colors |win32-colors| 14 6. Windows dialogs & browsers |gui-w32-dialogs| 15 7. Command line arguments |gui-w32-cmdargs| 16 8. Various |gui-w32-various| 17 18 Other relevant documentation: 19 |gui.txt| For generic items of the GUI. 20 |os_win32.txt| For Win32 specific items. 21 22 23 ============================================================================== 24 1. Starting the GUI *gui-w32-start* 25 26 The Win32 GUI version of Vim will always start the GUI, no matter how you 27 start it or what it's called. 28 29 The GUI will always run in the Windows subsystem. Mostly shells automatically 30 return with a command prompt after starting gvim. If not, you should use the 31 "start" command: > 32 start gvim [options] file .. 33 < *E988* 34 The console version with the |-g| option may also start the GUI by executing 35 gvim.exe: > 36 vim -g [options] file .. 37 To make this work, gvim.exe must exist in the same directory as the vim.exe, 38 and this feature must be enabled at compile time. 39 40 One may also use `:gui` from the console version. However, this is an 41 experimental feature and this feature must be enabled at compile time. 42 It uses a session file to recreate the current state of the console Vim in the 43 GUI Vim. 44 45 Note: All fonts (bold, italic) must be of the same size!!! If you don't do 46 this, text will disappear or mess up the display. Vim does not check the font 47 sizes. It's the size in screen pixels that must be the same. Note that some 48 fonts that have the same point size don't have the same pixel size! 49 Additionally, the positioning of the fonts must be the same (ascent and 50 descent). 51 52 The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the 53 standard Windows font selector. 54 55 Setting the menu height doesn't work for the Win32 GUI. 56 57 *gui-win32-maximized* 58 If you want Vim to start with a maximized window, add this command to your 59 vimrc or gvimrc file: > 60 au GUIEnter * simalt ~x 61 < 62 63 Using Vim as a plugin *gui-w32-windowid* 64 65 When gvim starts up normally, it creates its own top level window. If you 66 pass Vim the command-line option |--windowid| with a decimal or hexadecimal 67 value, Vim will create a window that is a child of the window with the given 68 ID. This enables Vim to act as a plugin in another application. This really 69 is a programmer's interface, and is of no use without a supporting application 70 to spawn Vim correctly. 71 72 ============================================================================== 73 2. Vim as default editor *vim-default-editor* 74 75 To set Vim as the default editor for a file type: 76 1. Start a Windows Explorer 77 2. Choose View/Options -> File Types 78 3. Select the path to gvim for every file type that you want to use it for. 79 (you can also use three spaces in the file type field, for files without an 80 extension). 81 In the "open" action, use: > 82 gvim "%1" 83 < The quotes are required for using file names with embedded spaces. 84 You can also use this: > 85 gvim "%L" 86 < This should avoid short (8.3 character) file names in some situations. But 87 I'm not sure if this works everywhere. 88 89 When you open a file in Vim by double clicking it, Vim changes to that 90 file's directory. 91 92 If you want Vim to start full-screen, use this for the Open action: > 93 gvim -c "simalt ~x" "%1" 94 95 Another method, which also works when you put Vim in another directory (e.g., 96 when you have got a new version): 97 1. select a file you want to use Vim with 98 2. <Shift-F10> 99 3. select "Open With..." menu entry 100 4. click "Other..." 101 5. browse to the (new) location of Vim and click "Open" 102 6. make "Always Use this program..." checked 103 7. <OK> 104 105 *send-to-menu* *sendto* 106 You can also install Vim in the "Send To" menu: 107 1. Start a Windows Explorer 108 2. Navigate to your sendto directory: 109 C:\Users\%user%\AppData\Roaming\Microsoft\Windows\SendTo . 110 3. Right-click in the file pane and select New->Shortcut 111 4. Follow the shortcut wizard, using the full path to VIM/GVIM. 112 113 When you 'send a file to Vim', Vim changes to that file's directory. Note, 114 however, that any long directory names will appear in their short (MS-DOS) 115 form on some Windows versions. This is a limitation of the Windows "Send To" 116 mechanism. 117 118 *notepad* 119 You could replace notepad.exe with gvim.exe, but that has a few side effects. 120 Some programs rely on notepad arguments, which are not recognized by Vim. For 121 example "notepad -p" is used by some applications to print a file. It's 122 better to leave notepad where it is and use another way to start Vim. 123 124 *win32-popup-menu* 125 A more drastic approach is to install an "Edit with Vim" entry in the popup 126 menu for the right mouse button. With this you can edit any file with Vim. 127 128 This can co-exist with the file associations mentioned above. The difference 129 is that the file associations will make starting Vim the default action. With 130 the "Edit with Vim" menu entry you can keep the existing file association for 131 double clicking on the file, and edit the file with Vim when you want. For 132 example, you can associate "*.mak" with your make program. You can execute 133 the makefile by double clicking it and use the "Edit with Vim" entry to edit 134 the makefile. 135 136 You can select any files and right-click to see a menu option called "Edit 137 with gvim". Choosing this menu option will invoke gvim with the file you have 138 selected. If you select multiple files, you will find two gvim-related menu 139 options: 140 "Edit with multiple gvims" -- one gvim for each file in the selection 141 "Edit with single gvim" -- one gvim for all the files in the selection 142 And if there already is a gvim running: 143 "Edit with existing gvim" -- edit the file with the running gvim 144 145 The "edit with existing Vim" entries can be disabled by adding an entry in the 146 registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with 147 any value. 148 *install-registry* 149 You can add the "Edit with Vim" menu entry in an easy way by using the 150 "install.exe" program. It will add several registry entries for you. 151 152 You can also do this by hand. This is complicated! Use the install.exe if 153 you can. 154 155 1. Start the registry editor with "regedit". 156 2. Add these keys: 157 key value name value ~ 158 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99} 159 {default} Vim Shell Extension 160 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32 161 {default} {path}\gvimext.dll 162 ThreadingModel Apartment 163 HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim 164 {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99} 165 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved 166 {51EEE242-AD87-11d3-9C1E-0090278BBD99} 167 Vim Shell Extension 168 HKEY_LOCAL_MACHINE\Software\Vim\Gvim 169 path {path}\gvim.exe 170 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 8.2 171 DisplayName Vim 8.2: Edit with Vim popup menu entry 172 UninstallString {path}\uninstall.exe 173 174 Replace {path} with the path that leads to the executable. 175 Don't type {default}, this is the value for the key itself. 176 177 To remove "Edit with Vim" from the popup menu, just remove the registry 178 entries mentioned above. The "uninstall.exe" program can do this for you. 179 You can also use the entry in the Windows standard "Add/Remove Programs" list. 180 181 If you notice that this entry overrules other file type associations, set 182 those associations again by hand (using Windows Explorer, see above). This 183 only seems to happen on some Windows NT versions (Windows bug?). Procedure: 184 1. Find the name of the file type. This can be done by starting the registry 185 editor, and searching for the extension in \\HKEY_CLASSES_ROOT 186 2. In a Windows Explorer, use View/Options/File Types. Search for the file 187 type in the list and click "Edit". In the actions list, you can select on 188 to be used as the default (normally the "open" action) and click on the 189 "Set Default" button. 190 191 192 Vim in the "Open With..." context menu *win32-open-with-menu* 193 194 If you use the Vim install program you have the choice to add Vim to the "Open 195 With..." menu. This means you can use Vim to edit many files. Not every file 196 (for unclear reasons...), thus the "Edit with Vim" menu entry is still useful. 197 198 One reason to add this is to be able to edit HTML files directly from Internet 199 Explorer. To enable this use the "Tools" menu, "Internet Options..." entry. 200 In the dialog select the "Programs" tab and select Vim in the "HTML editor" 201 choice. If it's not there then installing didn't work properly. 202 203 Doing this manually can be done with this script: 204 205 ---------------------------------------------------------- 206 REGEDIT4 207 208 [HKEY_CLASSES_ROOT\Applications\gvim.exe] 209 210 [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell] 211 212 [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit] 213 214 [HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command] 215 @="c:\\vim\\vim82\\gvim.exe \"%1\"" 216 217 [HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe] 218 219 [HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe] 220 221 ---------------------------------------------------------- 222 223 Change the "c:\\vim\\vim82" bit to where gvim.exe is actually located. 224 225 To uninstall this run the Vim uninstall program or manually delete the 226 registry entries with "regedit". 227 228 ============================================================================== 229 3. Using the clipboard *gui-clipboard* 230 231 Windows has a clipboard, where you can copy text to, and paste text from. Vim 232 supports this in several ways. For other systems see |gui-selections|. 233 234 The "* register reflects the contents of the clipboard. |quotestar| 235 236 When the "unnamed" string is included in the 'clipboard' option, the unnamed 237 register is the same. Thus you can yank to and paste from the clipboard 238 without prepending "* to commands. If this doesn't work use the "unnamedplus" 239 string in the 'clipboard' option. 240 241 The 'a' flag in 'guioptions' is not included by default. This means that text 242 is only put on the clipboard when an operation is performed on it. Just 243 Visually selecting text doesn't put it on the clipboard. When the 'a' flag is 244 included, the text is copied to the clipboard even when it is not operated 245 upon. 246 247 *mswin.vim* 248 To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the 249 $VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: > 250 source $VIMRUNTIME/mswin.vim 251 252 Since CTRL-C is used to copy the text to the clipboard, it can't be used to 253 cancel an operation. Use CTRL-Break for that. 254 255 CTRL-Z is used for undo. This means you can't suspend Vim with this key, use 256 |:suspend| instead (if it's supported at all). 257 258 *CTRL-V-alternative* *CTRL-Q* 259 Since CTRL-V is used to paste, you can't use it to start a blockwise Visual 260 selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert 261 mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q 262 doesn't work for terminals when it's used for control flow. 263 264 NOTE: The clipboard support still has a number of bugs. See |todo|. 265 266 ============================================================================== 267 4. Shell Commands *gui-shell-win32* 268 269 Vim uses another window for external commands, to make it possible to run any 270 command. The external command gets its own environment for running, just like 271 it was started from a DOS prompt. 272 273 *win32-vimrun* 274 Executing an external command is done indirectly by the "vimrun" command. The 275 "vimrun.exe" must be in the path for this to work. Or it must be in the same 276 directory as the Vim executable. If "vimrun" cannot be found, the command is 277 executed directly, but then the DOS window closes immediately after the 278 external command has finished. 279 WARNING: If you close this window with the "X" button, and confirm the 280 question if you really want to kill the application, Vim may be killed too! 281 (This does not apply to commands run asynchronously with ":!start".) 282 283 The window in which the commands are executed will be the default you have set 284 up for "Console" in Control Panel. 285 286 *win32-!start* 287 Normally, Vim waits for a command to complete before continuing (this makes 288 sense for most shell commands which produce output for Vim to use). If you 289 want Vim to start a program and return immediately, you can use the following 290 syntax: > 291 :!start [/min] {command} 292 The optional "/min" causes the window to be minimized. 293 294 ============================================================================== 295 5. Special colors *win32-colors* 296 297 On Win32, the normal DOS colors can be used. See |dos-colors|. 298 299 Additionally the system configured colors can also be used. These are known 300 by the names Sys_XXX, where XXX is the appropriate system color name, from the 301 following list (see the Win32 documentation for full descriptions). Case is 302 ignored. 303 304 Sys_3DDKShadow Sys_3DFace Sys_BTNFace 305 Sys_3DHilight Sys_3DHighlight Sys_BTNHilight 306 Sys_BTNHighlight Sys_3DLight Sys_3DShadow 307 Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption 308 Sys_AppWorkspace Sys_Background Sys_Desktop 309 Sys_BTNText Sys_CaptionText Sys_GrayText 310 Sys_Highlight Sys_HighlightText Sys_InactiveBorder 311 Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK 312 Sys_InfoText Sys_Menu Sys_MenuText 313 Sys_ScrollBar Sys_Window Sys_WindowFrame 314 Sys_WindowText 315 316 Probably the most useful values are 317 Sys_Window Normal window background 318 Sys_WindowText Normal window text 319 Sys_Highlight Highlighted background 320 Sys_HighlightText Highlighted text 321 322 These extra colors are also available: 323 Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, 324 325 *rgb.txt* 326 Additionally, colors defined by a default color list can be used. For more 327 info see |:colorscheme|. These colors used to be defined in 328 $VIMRUNTIME/rgb.txt, now they are in |v:colornames| which is initialized from 329 $VIMRUNTIME/colors/lists/default.vim. 330 331 ============================================================================== 332 *gui-w32-dialogs* *dialog* 333 6. Windows dialogs & browsers 334 335 The Win32 GUI can use familiar Windows components for some operations, as well 336 as the traditional interface shared with the console version. 337 338 339 6.1 Dialogs 340 341 The dialogs displayed by the "confirm" family (i.e. the 'confirm' option, 342 |:confirm| command and |confirm()| function) are GUI-based rather than the 343 console-based ones used by other versions. The 'c' flag in 'guioptions' 344 changes this. 345 346 347 6.2 File Browsers 348 349 When prepending ":browse" before file editing commands, a file requester is 350 used to allow you to select an existing file. See |:browse|. 351 352 353 6.3 Tearoff Menus 354 355 The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you 356 will see a small graphic "rip here" sign. Selecting it will cause a floating 357 window to be created with the same menu entries on it. The floating menu can 358 then be accessed just as if it was the original (including sub-menus), but 359 without having to go to the menu bar each time. 360 This is most useful if you find yourself using a command buried in a sub-menu 361 over and over again. 362 The tearoff menus can be positioned where you like, and always stay just above 363 the Main Vim window. You can get rid of them by closing them as usual; they 364 also of course close when you exit Vim. 365 366 *:tearoff* *:te* 367 :te[aroff] {name} Tear-off the menu {name}. The menu named must have at 368 least one subentry, but need not appear on the 369 menu-bar (see |win32-hidden-menus|). 370 371 Example: > 372 :tearoff File 373 will make the "File" menu (if there is one) appear as a tearoff menu. > 374 375 :amenu ]Toolbar.Make :make<CR> 376 :tearoff ]Toolbar 377 This creates a floating menu that doesn't exist on the main menu-bar. 378 379 Note that a menu that starts with ']' will not be displayed. 380 381 ============================================================================== 382 7. Command line arguments *gui-w32-cmdargs* 383 384 Command line arguments behave the same way as with the console application, 385 see |win32-cmdargs|. 386 387 ============================================================================== 388 8. Various *gui-w32-various* 389 390 *gui-w32-printing* 391 The "File/Print" menu prints the text with syntax highlighting, see 392 |:hardcopy|. If you just want to print the raw text and have a default 393 printer installed this should also work: > 394 :w >>prn 395 396 Vim supports a number of standard MS-Windows features. Some of these are 397 detailed elsewhere: see 'mouse', |win32-hidden-menus|. 398 399 *drag-n-drop-win32* 400 You can drag and drop one or more files into the Vim window, where they will 401 be opened as normal. See |drag-n-drop|. 402 403 *:simalt* *:sim* 404 :sim[alt] {key} simulate pressing {key} while holding Alt pressed. 405 {only for Win32 versions} 406 Note: ":si" means ":s" with the "i" flag. 407 408 Normally, Vim takes control of all Alt-<Key> combinations, to increase the 409 number of possible mappings. This clashes with the standard use of Alt as the 410 key for accessing menus. 411 The quick way of getting standard behavior is to set the 'winaltkeys' option 412 to "yes". This however prevents you from mapping Alt keys at all. 413 Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then 414 handled by windows, other ALT keys can be mapped. This doesn't allow a 415 dependency on the current state though. 416 To get round this, the :simalt command allows Vim (when 'winaltkeys' is not 417 "yes") to fake a Windows-style Alt keypress. You can use this to map Alt key 418 combinations (or anything else for that matter) to produce standard Windows 419 actions. Here are some examples: > 420 421 :map <M-f> :simalt f<CR> 422 This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by 423 simulating the keystrokes Alt, F. > 424 :map <M-Space> :simalt ~<CR> 425 This maps Alt-Space to pop down the system menu for the Vim window. Note that 426 ~ is used by simalt to represent the <Space> character. > 427 :map <C-n> :simalt ~n<CR> 428 Maps Control-N to produce the keys Alt-Space followed by N. This minimizes 429 the Vim window via the system menu. 430 431 Note that the key changes depending on the language you are using. 432 433 *intellimouse-wheel-problems* 434 When using the Intellimouse mouse wheel causes Vim to stop accepting input, go 435 to: 436 ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions 437 438 And add gvim to the list of applications. This problem only appears to happen 439 with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on. 440 441 442 XPM support *w32-xpm-support* 443 444 GVim can be built on MS-Windows with support for XPM files. |+xpm_w32| 445 See the Make_mvc.mak file for instructions, search for XPM. 446 447 To try out if XPM support works do this: > 448 :help 449 :let runtime = escape($VIMRUNTIME, ' \') 450 :exe 'sign define vimxpm icon=' .. runtime .. '\\vim16x16.xpm' 451 :exe 'sign place 1 line=1 name=vimxpm file=' .. expand('%:p') 452 < 453 You may need to get the vim16x16.xpm file from github: 454 https://github.com/vim/vim/blob/master/runtime/vim16x16.xpm 455 456 457 Keycode translation strategy *w32-experimental-keycode-trans-strategy* 458 459 In Patch v8.2.4807 W32 GVIM was changed over to experimental keycode 460 translation method with the aim to be able to use more keyboard shortcuts and 461 especially supporting non-standard keyboard layouts. In order to implement 462 this support Win API TranslateMessage() call was dropped, and instead the 463 recognition of keycode was changed over to ToUnicode() Win API call. This 464 approach uncovered numerous corner cases, which are apparently covered by 465 TranslateMessage() implementation, each of it is necessary to be dealt with on 466 an individual basis. Therefore the decision was taken to declare this 467 functionality experimental for the time being and to recover "classic" keycode 468 translation method as default again. 469 470 Discussion about use of "experimental" keycode translation method will 471 probably last some time yet. In the meantime, if you are impacted by this 472 change over back to "classic" keycode translation method in W32 GVIM, you can 473 enable "experimental" translation method again in your vimrc using following 474 snippet: 475 > 476 :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'experimental'}) 477 < 478 Similarly, in case you need to turn back "classic" keycode translation method 479 (for example for testing purposes), please use: 480 > 481 :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'classic'}) 482 < 483 Alternatively (this method is especially useful for the TINY GVIM build, where 484 test_mswin_event() cannot be called), an environment variable 485 VIM_KEYCODE_TRANS_STRATEGY can be set to the desired value ("experimental" or 486 "classic"), to override the default, e.g., type in dos prompt: 487 > 488 set VIM_KEYCODE_TRANS_STRATEGY=experimental 489 gvim.exe 490 < 491 492 Title Bar *gui-w32-title-bar* 493 494 Starting with Windows 11, you can customize the gVim title bar (also known as 495 the caption bar) by enabling the |'go-C'| option. 496 497 Once enabled, the appearance is controlled by two highlighting groups: 498 1. |hl-TitleBar| -- Sets the color of the title bar for the active window. 499 2. |hl-TitleBarNC| -- Sets the color of the title bar for inactive windows. 500 501 To use the system's default title bar colors, set highlighting groups to 502 `NONE`: > 503 504 hi TitleBar guibg=NONE guifg=NONE 505 hi TitleBarNC guibg=NONE guifg=NONE 506 < 507 508 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: