1*gui_w32.txt* For Vim version 7.3. Last change: 2007 Aug 30 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{Vi does not have a Windows GUI} 23 24============================================================================== 251. Starting the GUI *gui-w32-start* 26 27The Win32 GUI version of Vim will always start the GUI, no matter how you 28start it or what it's called. 29 30The GUI will always run in the Windows subsystem. Mostly shells automatically 31return with a command prompt after starting gvim. If not, you should use the 32"start" command: > 33 start gvim [options] file .. 34 35Note: All fonts (bold, italic) must be of the same size!!! If you don't do 36this, text will disappear or mess up the display. Vim does not check the font 37sizes. It's the size in screen pixels that must be the same. Note that some 38fonts that have the same point size don't have the same pixel size! 39Additionally, the positioning of the fonts must be the same (ascent and 40descent). 41 42The Win32 GUI has an extra menu item: "Edit/Select Font". It brings up the 43standard Windows font selector. 44 45Setting the menu height doesn't work for the Win32 GUI. 46 47 *gui-win32-maximized* 48If you want Vim to start with a maximized window, add this command to your 49vimrc or gvimrc file: > 50 au GUIEnter * simalt ~x 51< 52 *gui-w32s* 53There is a specific version of gvim.exe that runs under the Win32s subsystem 54of Windows 3.1 or 3.11. See |win32s|. 55 56 57Using Vim as a plugin *gui-w32-windowid* 58 59When gvim starts up normally, it creates its own top level window. If you 60pass Vim the command-line option |--windowid| with a decimal or hexadecimal 61value, Vim will create a window that is a child of the window with the given 62ID. This enables Vim to act as a plugin in another application. This really 63is a programmer's interface, and is of no use without a supporting application 64to spawn Vim correctly. 65 66============================================================================== 672. Vim as default editor *vim-default-editor* 68 69To set Vim as the default editor for a file type: 701. Start a Windows Explorer 712. Choose View/Options -> File Types 723. Select the path to gvim for every file type that you want to use it for. 73 (you can also use three spaces in the file type field, for files without an 74 extension). 75 In the "open" action, use: > 76 gvim "%1" 77< The quotes are required for using file names with embedded spaces. 78 You can also use this: > 79 gvim "%L" 80< This should avoid short (8.3 character) file names in some situations. But 81 I'm not sure if this works everywhere. 82 83When you open a file in Vim by double clicking it, Vim changes to that 84file's directory. 85 86If you want Vim to start full-screen, use this for the Open action: > 87 gvim -c "simalt ~x" "%1" 88 89Another method, which also works when you put Vim in another directory (e.g., 90when you have got a new version): 911. select a file you want to use Vim with 922. <Shift-F10> 933. select "Open With..." menu entry 944. click "Other..." 955. browse to the (new) location of Vim and click "Open" 966. make "Always Use this program..." checked 977. <OK> 98 99 *send-to-menu* *sendto* 100You can also install Vim in the "Send To" menu: 1011. Start a Windows Explorer 1022. Navigate to your sendto directory: 103 Windows 95: %windir%\sendto (e.g. "c:\windows\sendto") 104 Windows NT: %windir%\profiles\%user%\sendto (e.g. 105 "c:\winnt\profiles\mattha\sendto"). 1063. Right-click in the file pane and select New->Shortcut 1074. Follow the shortcut wizard, using the full path to VIM/GVIM. 108 109When you 'send a file to Vim', Vim changes to that file's directory. Note, 110however, that any long directory names will appear in their short (MS-DOS) 111form. This is a limitation of the Windows "Send To" mechanism. 112 113 *notepad* 114You could replace notepad.exe with gvim.exe, but that has a few side effects. 115Some programs rely on notepad arguments, which are not recognized by Vim. For 116example "notepad -p" is used by some applications to print a file. It's 117better to leave notepad where it is and use another way to start Vim. 118 119 *win32-popup-menu* 120A more drastic approach is to install an "Edit with Vim" entry in the popup 121menu for the right mouse button. With this you can edit any file with Vim. 122 123This can co-exist with the file associations mentioned above. The difference 124is that the file associations will make starting Vim the default action. With 125the "Edit with Vim" menu entry you can keep the existing file association for 126double clicking on the file, and edit the file with Vim when you want. For 127example, you can associate "*.mak" with your make program. You can execute 128the makefile by double clicking it and use the "Edit with Vim" entry to edit 129the makefile. 130 131You can select any files and right-click to see a menu option called "Edit 132with gvim". Choosing this menu option will invoke gvim with the file you have 133selected. If you select multiple files, you will find two gvim-related menu 134options: 135"Edit with multiple gvims" -- one gvim for each file in the selection 136"Edit with single gvim" -- one gvim for all the files in the selection 137And if there already is a gvim running: 138"Edit with existing gvim" -- edit the file with the running gvim 139 140 *install-registry* 141You can add the "Edit with Vim" menu entry in an easy way by using the 142"install.exe" program. It will add several registry entries for you. 143 144You can also do this by hand. This is complicated! Use the install.exe if 145you can. 146 1471. Start the registry editor with "regedit". 1482. Add these keys: 149 key value name value ~ 150 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99} 151 {default} Vim Shell Extension 152 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32 153 {default} {path}\gvimext.dll 154 ThreadingModel Apartment 155 HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim 156 {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99} 157 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved 158 {51EEE242-AD87-11d3-9C1E-0090278BBD99} 159 Vim Shell Extension 160 HKEY_LOCAL_MACHINE\Software\Vim\Gvim 161 path {path}\gvim.exe 162 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6 163 DisplayName Vim 5.6: Edit with Vim popup menu entry 164 UninstallString {path}\uninstal.exe 165 166 Replace {path} with the path that leads to the executable. 167 Don't type {default}, this is the value for the key itself. 168 169To remove "Edit with Vim" from the popup menu, just remove the registry 170entries mentioned above. The "uninstal.exe" program can do this for you. You 171can also use the entry in the Windows standard "Add/Remove Programs" list. 172 173If you notice that this entry overrules other file type associations, set 174those associations again by hand (using Windows Explorer, see above). This 175only seems to happen on some Windows NT versions (Windows bug?). Procedure: 1761. Find the name of the file type. This can be done by starting the registry 177 editor, and searching for the extension in \\HKEY_CLASSES_ROOT 1782. In a Windows Explorer, use View/Options/File Types. Search for the file 179 type in the list and click "Edit". In the actions list, you can select on 180 to be used as the default (normally the "open" action) and click on the 181 "Set Default" button. 182 183 184Vim in the "Open With..." context menu *win32-open-with-menu* 185 186If you use the Vim install program you have the choice to add Vim to the "Open 187With..." menu. This means you can use Vim to edit many files. Not every file 188(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful. 189 190One reason to add this is to be able to edit HTML files directly from Internet 191Explorer. To enable this use the "Tools" menu, "Internet Options..." entry. 192In the dialog select the "Programs" tab and select Vim in the "HTML editor" 193choice. If it's not there than installing didn't work properly. 194 195Doing this manually can be done with this script: 196 197---------------------------------------------------------- 198REGEDIT4 199 200[HKEY_CLASSES_ROOT\Applications\gvim.exe] 201 202[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell] 203 204[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit] 205 206[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command] 207@="c:\\vim\\vim62\\gvim.exe \"%1\"" 208 209[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe] 210 211[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe] 212 213---------------------------------------------------------- 214 215Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located. 216 217To uninstall this run the Vim uninstall program or manually delete the 218registry entries with "regedit". 219 220============================================================================== 2213. Using the clipboard *gui-clipboard* 222 223Windows has a clipboard, where you can copy text to, and paste text from. Vim 224supports this in several ways. For other systems see |gui-selections|. 225 226The "* register reflects the contents of the clipboard. |quotestar| 227 228When the "unnamed" string is included in the 'clipboard' option, the unnamed 229register is the same. Thus you can yank to and paste from the clipboard 230without prepending "* to commands. 231 232The 'a' flag in 'guioptions' is not included by default. This means that text 233is only put on the clipboard when an operation is performed on it. Just 234Visually selecting text doesn't put it on the clipboard. When the 'a' flag is 235included, the text is copied to the clipboard even when it is not operated 236upon. 237 238 *mswin.vim* 239To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the 240$VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: > 241 source $VIMRUNTIME/mswin.vim 242 243Since CTRL-C is used to copy the text to the clipboard, it can't be used to 244cancel an operation. Use CTRL-Break for that. 245 246CTRL-Z is used for undo. This means you can't suspend Vim with this key, use 247|:suspend| instead (if it's supported at all). 248 249 *CTRL-V-alternative* *CTRL-Q* 250Since CTRL-V is used to paste, you can't use it to start a blockwise Visual 251selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert 252mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q 253doesn't work for terminals when it's used for control flow. 254 255NOTE: The clipboard support still has a number of bugs. See |todo|. 256 257============================================================================== 2584. Shell Commands *gui-shell-win32* 259 260Vim uses another window for external commands, to make it possible to run any 261command. The external command gets its own environment for running, just like 262it was started from a DOS prompt. 263 264 *win32-vimrun* 265Executing an external command is done indirectly by the "vimrun" command. The 266"vimrun.exe" must be in the path for this to work. Or it must be in the same 267directory as the Vim executable. If "vimrun" cannot be found, the command is 268executed directly, but then the DOS window closes immediately after the 269external command has finished. 270WARNING: If you close this window with the "X" button, and confirm the 271question if you really want to kill the application, Vim may be killed too! 272(This does not apply to commands run asynchronously with ":!start".) 273 274In Windows 95, the window in which the commands are executed is always 25x80 275characters, to be as DOS compatible as possible (this matters!). The default 276system font is used. On NT, the window will be the default you have set up for 277"Console" in Control Panel. On Win32s, the properties of the DOS box are 278determined by _default.pif in the windows directory. 279 280 *msdos-mode* 281If you get a dialog that says "This program is set to run in MS-DOS mode..." 282when you run an external program, you can solve this by changing the 283properties of the associated shortcut: 284- Use a Windows Explorer to find the command.com that is used. It can be 285 c:\command.com, c:\dos\command.com, c:\windows\command.com, etc. 286- With the right mouse button, select properties of this command.com. 287- In the Program tab select "Advanced". 288- Unselect "MS-DOS mode". 289- Click "OK" twice. 290 291 *win32-!start* 292Normally, Vim waits for a command to complete before continuing (this makes 293sense for most shell commands which produce output for Vim to use). If you 294want Vim to start a program and return immediately, you can use the following 295syntax on W95 & NT: > 296 :!start {command} 297On Win32s, you will have to go to another window instead. Don't forget that 298you must tell Windows 3.1x to keep executing a DOS command in the background 299while you switch back to Vim. 300 301============================================================================== 3025. Special colors *win32-colors* 303 304On Win32, the normal DOS colors can be used. See |dos-colors|. 305 306Additionally the system configured colors can also be used. These are known 307by the names Sys_XXX, where XXX is the appropriate system color name, from the 308following list (see the Win32 documentation for full descriptions). Case is 309ignored. Note: On Win32s not all of these colors are supported. 310 311Sys_3DDKShadow Sys_3DFace Sys_BTNFace 312Sys_3DHilight Sys_3DHighlight Sys_BTNHilight 313Sys_BTNHighlight Sys_3DLight Sys_3DShadow 314Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption 315Sys_AppWorkspace Sys_Background Sys_Desktop 316Sys_BTNText Sys_CaptionText Sys_GrayText 317Sys_Highlight Sys_HighlightText Sys_InactiveBorder 318Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK 319Sys_InfoText Sys_Menu Sys_MenuText 320Sys_ScrollBar Sys_Window Sys_WindowFrame 321Sys_WindowText 322 323Probably the most useful values are 324 Sys_Window Normal window background 325 Sys_WindowText Normal window text 326 Sys_Highlight Highlighted background 327 Sys_HighlightText Highlighted text 328 329These extra colors are also available: 330Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet, 331 332 *rgb.txt* 333Additionally, colors defined by a "rgb.txt" file can be used. This file is 334well known from X11. A few lines from it: > 335 336 255 218 185 peach puff 337 205 133 63 peru 338 255 181 197 pink 339 340This shows the layout of the file: First the R, G and B value as a decimal 341number, followed by the name of the color. The four fields are separated by 342spaces. 343 344You can get an rgb.txt file from any X11 distribution. It is located in a 345directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the 346$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt". 347 348============================================================================== 349 *gui-w32-dialogs* *dialog* 3506. Windows dialogs & browsers 351 352The Win32 GUI can use familiar Windows components for some operations, as well 353as the traditional interface shared with the console version. 354 355 3566.1 Dialogs 357 358The dialogs displayed by the "confirm" family (i.e. the 'confirm' option, 359|:confirm| command and |confirm()| function) are GUI-based rather than the 360console-based ones used by other versions. The 'c' flag in 'guioptions' 361changes this. 362 363 3646.2 File Browsers 365 366When prepending ":browse" before file editing commands, a file requester is 367used to allow you to select an existing file. See |:browse|. 368 369 3706.3 Tearoff Menus 371 372The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you 373will see a small graphic "rip here" sign. Selecting it will cause a floating 374window to be created with the same menu entries on it. The floating menu can 375then be accessed just as if it was the original (including sub-menus), but 376without having to go to the menu bar each time. 377This is most useful if you find yourself using a command buried in a sub-menu 378over and over again. 379The tearoff menus can be positioned where you like, and always stay just above 380the Main Vim window. You can get rid of them by closing them as usual; they 381also of course close when you exit Vim. 382 383 *:tearoff* *:te* 384:te[aroff] {name} Tear-off the menu {name}. The menu named must have at 385 least one subentry, but need not appear on the 386 menu-bar (see |win32-hidden-menus|). 387 388Example: > 389 :tearoff File 390will make the "File" menu (if there is one) appear as a tearoff menu. > 391 392 :amenu ]Toolbar.Make :make<CR> 393 :tearoff ]Toolbar 394This creates a floating menu that doesn't exist on the main menu-bar. 395 396Note that a menu that starts with ']' will not be displayed. 397 398============================================================================== 3997. Command line arguments *gui-w32-cmdargs* 400 401Analysis of a command line into parameters is not standardised in MS Windows. 402Gvim has to provide logic to analyse a command line. This logic is likely to 403be different from the default logic provided by a compilation system used to 404build vim. The differences relate to unusual double quote (") usage. 405The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the 406same way. The argument "+/Sch""iller" may be handled different by gvim and 407vim, depending what it was compiled with. 408 409The rules are: 410 a) A parameter is a sequence of graphic characters. 411 b) Parameters are separated by white space. 412 c) A parameter can be enclosed in double quotes to include white space. 413 d) A sequence of zero or more backslashes (\) and a double quote (") 414 is special. The effective number of backslashes is halved, rounded 415 down. An even number of backslashes reverses the acceptability of 416 spaces and tabs, an odd number of backslashes produces a literal 417 double quote. 418 419So: 420 " is a special double quote 421 \" is a literal double quote 422 \\" is a literal backslash and a special double quote 423 \\\" is a literal backslash and a literal double quote 424 \\\\" is 2 literal backslashes and a special double quote 425 \\\\\" is 2 literal backslashes and a literal double quote 426 etc. 427 428Example: > 429 gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\" 430 431opens "C:\My Music\freude" and executes the line mode commands: > 432 set ignorecase; /"foo\ and /bar\" 433 434============================================================================== 4358. Various *gui-w32-various* 436 437 *gui-w32-printing* 438The "File/Print" menu prints the text with syntax highlighting, see 439|:hardcopy|. If you just want to print the raw text and have a default 440printer installed this should also work: > 441 :w >>prn 442 443Vim supports a number of standard MS Windows features. Some of these are 444detailed elsewhere: see |'mouse'|, |win32-hidden-menus|. 445 446 *drag-n-drop-win32* 447You can drag and drop one or more files into the Vim window, where they will 448be opened as normal. See |drag-n-drop|. 449 450 *:simalt* *:si* 451:sim[alt] {key} simulate pressing {key} while holding Alt pressed. 452 {not in Vi} {only for Win32 versions} 453 454Normally, Vim takes control of all Alt-<Key> combinations, to increase the 455number of possible mappings. This clashes with the standard use of Alt as the 456key for accessing menus. 457The quick way of getting standard behavior is to set the 'winaltkeys' option 458to "yes". This however prevents you from mapping Alt keys at all. 459Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then 460handled by windows, other ALT keys can be mapped. This doesn't allow a 461dependency on the current state though. 462To get round this, the :simalt command allows Vim (when 'winaltkeys' is not 463"yes") to fake a Windows-style Alt keypress. You can use this to map Alt key 464combinations (or anything else for that matter) to produce standard Windows 465actions. Here are some examples: > 466 467 :map <M-f> :simalt f<CR> 468This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by 469simulating the keystrokes Alt, F. > 470 :map <M-Space> :simalt ~<CR> 471This maps Alt-Space to pop down the system menu for the Vim window. Note that 472~ is used by simalt to represent the <Space> character. > 473 :map <C-n> :simalt ~n<CR> 474Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the 475Vim window via the system menu. 476 477Note that the key changes depending on the language you are using. 478 479 *intellimouse-wheel-problems* 480When using the Intellimouse mouse wheel causes Vim to stop accepting input, go 481to: 482 ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions 483 484And add gvim to the list of applications. This problem only appears to happen 485with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on. 486 487 vim:tw=78:sw=4:ts=8:ft=help:norl: 488