1*gui_w32.txt* For Vim version 8.2. Last change: 2021 Oct 24 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Vim's Win32 Graphical User Interface *gui-w32* *win32-gui* 8 91. Starting the GUI |gui-w32-start| 102. Vim as default editor |vim-default-editor| 113. Using the clipboard |gui-clipboard| 124. Shell Commands |gui-shell-win32| 135. Special colors |win32-colors| 146. Windows dialogs & browsers |gui-w32-dialogs| 157. Command line arguments |gui-w32-cmdargs| 168. Various |gui-w32-various| 17 18Other relevant documentation: 19|gui.txt| For generic items of the GUI. 20|os_win32.txt| For Win32 specific items. 21 22 23============================================================================== 241. Starting the GUI *gui-w32-start* 25 26The Win32 GUI version of Vim will always start the GUI, no matter how you 27start it or what it's called. 28 29The GUI will always run in the Windows subsystem. Mostly shells automatically 30return with a command prompt after starting gvim. If not, you should use the 31"start" command: > 32 start gvim [options] file .. 33< *E988* 34The console version with the |-g| option may also start the GUI by executing 35gvim.exe: > 36 vim -g [options] file .. 37To make this work, gvim.exe must exist in the same directory as the vim.exe, 38and this feature must be enabled at compile time. 39 40One may also use `:gui` from the console version. However, this is an 41experimental feature and this feature must be enabled at compile time. 42It uses a session file to recreate the current state of the console Vim in the 43GUI Vim. 44 45Note: All fonts (bold, italic) must be of the same size!!! If you don't do 46this, text will disappear or mess up the display. Vim does not check the font 47sizes. It's the size in screen pixels that must be the same. Note that some 48fonts that have the same point size don't have the same pixel size! 49Additionally, the positioning of the fonts must be the same (ascent and 50descent). 51 52The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the 53standard Windows font selector. 54 55Setting the menu height doesn't work for the Win32 GUI. 56 57 *gui-win32-maximized* 58If you want Vim to start with a maximized window, add this command to your 59vimrc or gvimrc file: > 60 au GUIEnter * simalt ~x 61< 62 63Using Vim as a plugin *gui-w32-windowid* 64 65When gvim starts up normally, it creates its own top level window. If you 66pass Vim the command-line option |--windowid| with a decimal or hexadecimal 67value, Vim will create a window that is a child of the window with the given 68ID. This enables Vim to act as a plugin in another application. This really 69is a programmer's interface, and is of no use without a supporting application 70to spawn Vim correctly. 71 72============================================================================== 732. Vim as default editor *vim-default-editor* 74 75To set Vim as the default editor for a file type: 761. Start a Windows Explorer 772. Choose View/Options -> File Types 783. 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 89When you open a file in Vim by double clicking it, Vim changes to that 90file's directory. 91 92If you want Vim to start full-screen, use this for the Open action: > 93 gvim -c "simalt ~x" "%1" 94 95Another method, which also works when you put Vim in another directory (e.g., 96when you have got a new version): 971. select a file you want to use Vim with 982. <Shift-F10> 993. select "Open With..." menu entry 1004. click "Other..." 1015. browse to the (new) location of Vim and click "Open" 1026. make "Always Use this program..." checked 1037. <OK> 104 105 *send-to-menu* *sendto* 106You can also install Vim in the "Send To" menu: 1071. Start a Windows Explorer 1082. Navigate to your sendto directory: 109 Windows XP: C:\Documents and Settings\%user%\SendTo 110 Windows Vista: C:\Users\%user%\AppData\Roaming\Microsoft\Windows\SendTo . 1113. Right-click in the file pane and select New->Shortcut 1124. Follow the shortcut wizard, using the full path to VIM/GVIM. 113 114When you 'send a file to Vim', Vim changes to that file's directory. Note, 115however, that any long directory names will appear in their short (MS-DOS) 116form on some Windows versions. This is a limitation of the Windows "Send To" 117mechanism. 118 119 *notepad* 120You could replace notepad.exe with gvim.exe, but that has a few side effects. 121Some programs rely on notepad arguments, which are not recognized by Vim. For 122example "notepad -p" is used by some applications to print a file. It's 123better to leave notepad where it is and use another way to start Vim. 124 125 *win32-popup-menu* 126A more drastic approach is to install an "Edit with Vim" entry in the popup 127menu for the right mouse button. With this you can edit any file with Vim. 128 129This can co-exist with the file associations mentioned above. The difference 130is that the file associations will make starting Vim the default action. With 131the "Edit with Vim" menu entry you can keep the existing file association for 132double clicking on the file, and edit the file with Vim when you want. For 133example, you can associate "*.mak" with your make program. You can execute 134the makefile by double clicking it and use the "Edit with Vim" entry to edit 135the makefile. 136 137You can select any files and right-click to see a menu option called "Edit 138with gvim". Choosing this menu option will invoke gvim with the file you have 139selected. If you select multiple files, you will find two gvim-related menu 140options: 141"Edit with multiple gvims" -- one gvim for each file in the selection 142"Edit with single gvim" -- one gvim for all the files in the selection 143And if there already is a gvim running: 144"Edit with existing gvim" -- edit the file with the running gvim 145 146The "edit with existing Vim" entries can be disabled by adding an entry in the 147registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with 148any value. 149 *install-registry* 150You can add the "Edit with Vim" menu entry in an easy way by using the 151"install.exe" program. It will add several registry entries for you. 152 153You can also do this by hand. This is complicated! Use the install.exe if 154you can. 155 1561. Start the registry editor with "regedit". 1572. Add these keys: 158 key value name value ~ 159 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99} 160 {default} Vim Shell Extension 161 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32 162 {default} {path}\gvimext.dll 163 ThreadingModel Apartment 164 HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim 165 {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99} 166 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved 167 {51EEE242-AD87-11d3-9C1E-0090278BBD99} 168 Vim Shell Extension 169 HKEY_LOCAL_MACHINE\Software\Vim\Gvim 170 path {path}\gvim.exe 171 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 8.2 172 DisplayName Vim 8.2: Edit with Vim popup menu entry 173 UninstallString {path}\uninstall.exe 174 175 Replace {path} with the path that leads to the executable. 176 Don't type {default}, this is the value for the key itself. 177 178To remove "Edit with Vim" from the popup menu, just remove the registry 179entries mentioned above. The "uninstall.exe" program can do this for you. 180You can also use the entry in the Windows standard "Add/Remove Programs" list. 181 182If you notice that this entry overrules other file type associations, set 183those associations again by hand (using Windows Explorer, see above). This 184only seems to happen on some Windows NT versions (Windows bug?). Procedure: 1851. Find the name of the file type. This can be done by starting the registry 186 editor, and searching for the extension in \\HKEY_CLASSES_ROOT 1872. In a Windows Explorer, use View/Options/File Types. Search for the file 188 type in the list and click "Edit". In the actions list, you can select on 189 to be used as the default (normally the "open" action) and click on the 190 "Set Default" button. 191 192 193Vim in the "Open With..." context menu *win32-open-with-menu* 194 195If you use the Vim install program you have the choice to add Vim to the "Open 196With..." menu. This means you can use Vim to edit many files. Not every file 197(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful. 198 199One reason to add this is to be able to edit HTML files directly from Internet 200Explorer. To enable this use the "Tools" menu, "Internet Options..." entry. 201In the dialog select the "Programs" tab and select Vim in the "HTML editor" 202choice. If it's not there then installing didn't work properly. 203 204Doing this manually can be done with this script: 205 206---------------------------------------------------------- 207REGEDIT4 208 209[HKEY_CLASSES_ROOT\Applications\gvim.exe] 210 211[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell] 212 213[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit] 214 215[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command] 216@="c:\\vim\\vim82\\gvim.exe \"%1\"" 217 218[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe] 219 220[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe] 221 222---------------------------------------------------------- 223 224Change the "c:\\vim\\vim82" bit to where gvim.exe is actually located. 225 226To uninstall this run the Vim uninstall program or manually delete the 227registry entries with "regedit". 228 229============================================================================== 2303. Using the clipboard *gui-clipboard* 231 232Windows has a clipboard, where you can copy text to, and paste text from. Vim 233supports this in several ways. For other systems see |gui-selections|. 234 235The "* register reflects the contents of the clipboard. |quotestar| 236 237When the "unnamed" string is included in the 'clipboard' option, the unnamed 238register is the same. Thus you can yank to and paste from the clipboard 239without prepending "* to commands. 240 241The 'a' flag in 'guioptions' is not included by default. This means that text 242is only put on the clipboard when an operation is performed on it. Just 243Visually selecting text doesn't put it on the clipboard. When the 'a' flag is 244included, the text is copied to the clipboard even when it is not operated 245upon. 246 247 *mswin.vim* 248To 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 252Since CTRL-C is used to copy the text to the clipboard, it can't be used to 253cancel an operation. Use CTRL-Break for that. 254 255CTRL-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* 259Since CTRL-V is used to paste, you can't use it to start a blockwise Visual 260selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert 261mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q 262doesn't work for terminals when it's used for control flow. 263 264NOTE: The clipboard support still has a number of bugs. See |todo|. 265 266============================================================================== 2674. Shell Commands *gui-shell-win32* 268 269Vim uses another window for external commands, to make it possible to run any 270command. The external command gets its own environment for running, just like 271it was started from a DOS prompt. 272 273 *win32-vimrun* 274Executing 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 276directory as the Vim executable. If "vimrun" cannot be found, the command is 277executed directly, but then the DOS window closes immediately after the 278external command has finished. 279WARNING: If you close this window with the "X" button, and confirm the 280question 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 283The window in which the commands are executed will be the default you have set 284up for "Console" in Control Panel. 285 286 *win32-!start* 287Normally, Vim waits for a command to complete before continuing (this makes 288sense for most shell commands which produce output for Vim to use). If you 289want Vim to start a program and return immediately, you can use the following 290syntax: > 291 :!start [/min] {command} 292The optional "/min" causes the window to be minimized. 293 294============================================================================== 2955. Special colors *win32-colors* 296 297On Win32, the normal DOS colors can be used. See |dos-colors|. 298 299Additionally the system configured colors can also be used. These are known 300by the names Sys_XXX, where XXX is the appropriate system color name, from the 301following list (see the Win32 documentation for full descriptions). Case is 302ignored. 303 304Sys_3DDKShadow Sys_3DFace Sys_BTNFace 305Sys_3DHilight Sys_3DHighlight Sys_BTNHilight 306Sys_BTNHighlight Sys_3DLight Sys_3DShadow 307Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption 308Sys_AppWorkspace Sys_Background Sys_Desktop 309Sys_BTNText Sys_CaptionText Sys_GrayText 310Sys_Highlight Sys_HighlightText Sys_InactiveBorder 311Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK 312Sys_InfoText Sys_Menu Sys_MenuText 313Sys_ScrollBar Sys_Window Sys_WindowFrame 314Sys_WindowText 315 316Probably 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 322These extra colors are also available: 323Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, 324 325 *rgb.txt* 326Additionally, colors defined by a default color list can be used. For more 327info 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* 3336. Windows dialogs & browsers 334 335The Win32 GUI can use familiar Windows components for some operations, as well 336as the traditional interface shared with the console version. 337 338 3396.1 Dialogs 340 341The dialogs displayed by the "confirm" family (i.e. the 'confirm' option, 342|:confirm| command and |confirm()| function) are GUI-based rather than the 343console-based ones used by other versions. The 'c' flag in 'guioptions' 344changes this. 345 346 3476.2 File Browsers 348 349When prepending ":browse" before file editing commands, a file requester is 350used to allow you to select an existing file. See |:browse|. 351 352 3536.3 Tearoff Menus 354 355The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you 356will see a small graphic "rip here" sign. Selecting it will cause a floating 357window to be created with the same menu entries on it. The floating menu can 358then be accessed just as if it was the original (including sub-menus), but 359without having to go to the menu bar each time. 360This is most useful if you find yourself using a command buried in a sub-menu 361over and over again. 362The tearoff menus can be positioned where you like, and always stay just above 363the Main Vim window. You can get rid of them by closing them as usual; they 364also 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 371Example: > 372 :tearoff File 373will make the "File" menu (if there is one) appear as a tearoff menu. > 374 375 :amenu ]Toolbar.Make :make<CR> 376 :tearoff ]Toolbar 377This creates a floating menu that doesn't exist on the main menu-bar. 378 379Note that a menu that starts with ']' will not be displayed. 380 381============================================================================== 3827. Command line arguments *gui-w32-cmdargs* 383 384Command line arguments behave the same way as with the console application, 385see |win32-cmdargs|. 386 387============================================================================== 3888. Various *gui-w32-various* 389 390 *gui-w32-printing* 391The "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 393printer installed this should also work: > 394 :w >>prn 395 396Vim supports a number of standard MS-Windows features. Some of these are 397detailed elsewhere: see |'mouse'|, |win32-hidden-menus|. 398 399 *drag-n-drop-win32* 400You can drag and drop one or more files into the Vim window, where they will 401be 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 408Normally, Vim takes control of all Alt-<Key> combinations, to increase the 409number of possible mappings. This clashes with the standard use of Alt as the 410key for accessing menus. 411The quick way of getting standard behavior is to set the 'winaltkeys' option 412to "yes". This however prevents you from mapping Alt keys at all. 413Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then 414handled by windows, other ALT keys can be mapped. This doesn't allow a 415dependency on the current state though. 416To 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 418combinations (or anything else for that matter) to produce standard Windows 419actions. Here are some examples: > 420 421 :map <M-f> :simalt f<CR> 422This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by 423simulating the keystrokes Alt, F. > 424 :map <M-Space> :simalt ~<CR> 425This 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> 428Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the 429Vim window via the system menu. 430 431Note that the key changes depending on the language you are using. 432 433 *intellimouse-wheel-problems* 434When using the Intellimouse mouse wheel causes Vim to stop accepting input, go 435to: 436 ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions 437 438And add gvim to the list of applications. This problem only appears to happen 439with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on. 440 441 442XPM support *w32-xpm-support* 443 444GVim can be built on MS-Windows with support for XPM files. |+xpm_w32| 445See the Make_mvc.mak file for instructions, search for XPM. 446 447To 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< 453You may need to get the vim16x16.xpm file from github: 454https://github.com/vim/vim/blob/master/runtime/vim16x16.xpm 455 456 457 vim:tw=78:sw=4:ts=8:noet:ft=help:norl: 458