gui_w32.txt ForVim version 9.2. Last change: 2026 Feb 14VIM REFERENCE MANUAL by Bram MoolenaarVim'sWin32 GraphicalUserInterfacegui-w32win32-gui1. Starting theGUIgui-w32-start2. Vimas default editorvim-default-editor3. Using theclipboardgui-clipboard4. Shell Commandsgui-shell-win325.Special colorswin32-colors6. Windows dialogs& browsersgui-w32-dialogs7. Command line argumentsgui-w32-cmdargs8. Variousgui-w32-variousOther relevant documentation:gui.txt For generic items of the GUI.os_win32.txt ForWin32 specific items.==============================================================================1. Starting theGUIgui-w32-startTheWin32GUI version of Vim will always start the GUI, no matter how youstartit or what it's called.TheGUI will always run in the Windows subsystem. Mostly shells automaticallyreturn witha command prompt afterstarting gvim. If not, you should use the"start" command:start gvim [options] file ..E988The console version with the-g option may also start theGUI by executinggvim.exe:vim -g [options] file ..To make this work, gvim.exemust exist in the same directoryas the vim.exe,and this featuremust be enabledat compile time.One may also use:gui from the console version. However, thisis anexperimental feature and this featuremust be enabledat compile time.It usesa session file to recreate the current state of the console Vim in theGUI Vim.Note: All fonts (bold, italic)must be of the same size!!! If you don'tdothis, text will disappear or mess up the display. Vim does not check the fontsizes. It's the size in screen pixels thatmust be the same.Note that somefonts that have the same point size don't have the same pixel size!Additionally, the positioning of the fontsmust be the same (ascent anddescent).TheWin32GUI has an extra menu item: "Edit/Select Font". It brings up thestandard Windows font selector.Setting the menu height doesn't work for theWin32 GUI.gui-win32-maximizedIf you want Vim to start witha maximized window, add this command to yourvimrc orgvimrc file:au GUIEnter * simalt ~xUsing Vimasaplugingui-w32-windowidWhengvim starts up normally,it creates its own top level window. If youpass Vim the command-line option--windowid witha decimal or hexadecimalvalue, Vim will createawindow thatisa child of thewindow with the givenID. This enables Vim to actasaplugin in another application. This reallyisa programmer's interface, andis of no use withouta supporting applicationto spawn Vim correctly.==============================================================================2. Vimas default editorvim-default-editorTo set Vimas the default editor fora file type:1. Starta Windows Explorer2. Choose View/Options-> File Types3.Select the path togvim for every file type that you want to useit for. (you can also use three spaces in the file type field, for files without an extension). In the "open" action, use:gvim "%1" Thequotes are required for using file names with embedded spaces. You can also use this:gvim "%L" This should avoid short (8.3 character) file names in some situations. But I'm not sure if this works everywhere.When you opena file in Vim by double clicking it, Vim changes to thatfile's directory.If you want Vim to start full-screen, use this for the Open action:gvim -c "simalt ~x" "%1"Another method, which also works when youput Vim in another directory (e.g.,when you have gota new version):1. selecta file you want to use Vim with2.<Shift-F10>3. select "Open With..." menu entry4. click "Other..."5. browse to the (new) location of Vim and click "Open"6. make "Always Use this program..." checked7.<OK>send-to-menusendtoYou can alsoinstall Vim in the "Send To" menu:1. Starta Windows Explorer2. Navigate to yoursendto directory: C:\Users\%user%\AppData\Roaming\Microsoft\Windows\SendTo.3. Right-click in the file pane and select New->Shortcut4. Follow the shortcut wizard, using the full path to VIM/GVIM.When you 'senda file to Vim', Vim changes to that file's directory. Note,however, that any long directory names will appear in their short (MS-DOS)form on some Windows versions. Thisisa limitation of the Windows "Send To"mechanism.notepadYou could replace notepad.exe with gvim.exe, but that hasa few side effects.Some programs rely onnotepad arguments, which are not recognized by Vim. Forexample "notepad-p"is used by some applications to printa file. It'sbetter to leavenotepad whereitis and use another way to start Vim.win32-popup-menuA more drastic approachis toinstall an "Edit with Vim" entry in thepopupmenu for the right mouse button. With this you can edit any file with Vim.This can co-exist with the file associations mentioned above. The differenceis that the file associations will makestarting Vim the default action. Withthe "Edit with Vim" menu entry you can keep the existing file association fordouble clicking on the file, and edit the file with Vim when you want. Forexample, you can associate "*.mak" with your make program. You can executethe makefile by double clickingit and use the "Edit with Vim" entry to editthe makefile.You can select any files and right-click to seea menu option called "Editwithgvim". Choosing this menu option will invokegvim with the file you haveselected. If you select multiple files, you will find two gvim-related menuoptions:"Edit with multiple gvims"-- onegvim for each file in the selection"Edit with singlegvim"-- onegvim for all the files in the selectionAnd if there alreadyisagvim running:"Edit with existinggvim"-- edit the file with the runninggvimThe "edit with existing Vim" entries can be disabled by adding an entry in theregistry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and withany value.install-registryYou can add the "Edit with Vim" menu entry in aneasy way by using the"install.exe" program. It will add several registry entries for you.You can alsodo this by hand. Thisis complicated! Use the install.exe ifyou can.1. Start the registry editor with "regedit".2. Add these keys: keyvalue name value HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}{default} Vim Shell Extension HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32{default}{path}\gvimext.dllThreadingModel Apartment HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim{default}{51EEE242-AD87-11d3-9C1E-0090278BBD99} HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved{51EEE242-AD87-11d3-9C1E-0090278BBD99} Vim Shell Extension HKEY_LOCAL_MACHINE\Software\Vim\Gvimpath{path}\gvim.exe HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 8.2DisplayName Vim 8.2: Edit with Vimpopup menu entryUninstallString{path}\uninstall.exeReplace{path} with the path that leads to the executable. Don't type{default}, thisis the value for the key itself.To remove "Edit with Vim" from thepopup menu, just remove the registryentries mentioned above. The "uninstall.exe" program cando this for you.You can also use the entry in the Windows standard "Add/Remove Programs" list.If you notice that this entry overrules other file type associations, setthose associations again by hand (using Windows Explorer, see above). Thisonly seems to happen on some Windows NT versions (Windows bug?). Procedure:1. Find the name of the file type. This can be done bystarting the registry editor, and searching for the extension in \\HKEY_CLASSES_ROOT2. Ina Windows Explorer, use View/Options/File Types. Search for the file type in thelist and click "Edit". In the actions list, you can select on to be usedas the default (normally the "open" action) and click on the "Set Default" button.Vim in the "Open With..." context menuwin32-open-with-menuIf you use the Viminstall program you have the choice to add Vim to the "OpenWith..." menu. This means you can use Vim to edit many files. Not every file(for unclear reasons...), thus the "Edit with Vim" menu entryis still useful.One reason to add thisis to be able to edit HTML files directly from InternetExplorer. To enable this use the "Tools" menu, "Internet Options..." entry.In thedialog select the "Programs"tab and select Vim in the "HTML editor"choice. If it's not there then installing didn't work properly.Doing this manually can be done with this script:----------------------------------------------------------REGEDIT4[HKEY_CLASSES_ROOT\Applications\gvim.exe][HKEY_CLASSES_ROOT\Applications\gvim.exe\shell][HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit][HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command]@="c:\\vim\\vim82\\gvim.exe \"%1\""[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe][HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe]----------------------------------------------------------Change the "c:\\vim\\vim82" bit to where gvim.exeis actually located.To uninstall this run the Vim uninstall program or manually delete theregistry entries with "regedit".==============================================================================3. Using theclipboardgui-clipboardWindows hasa clipboard, where you can copy text to, and paste text from. Vimsupports this in several ways. For other systems seegui-selections.The "* register reflects the contents of the clipboard.quotestarWhen the "unnamed"stringis included in the'clipboard' option, the unnamedregisteris the same. Thus you canyank to and paste from theclipboardwithout prepending "* to commands. If this doesn't work use the "unnamedplus"string in the'clipboard' option.The 'a' flag in'guioptions'is not included by default. This means that textis onlyput on theclipboard when an operationis performed on it. JustVisually selecting text doesn'tputit on the clipboard. When the 'a' flagisincluded, the textis copied to theclipboard even whenitis not operatedupon.mswin.vimTo use the standardMS-Windows way ofCTRL-X,CTRL-C andCTRL-V, use the$VIMRUNTIME/mswin.vim script. You could add this line to your_vimrc file:source $VIMRUNTIME/mswin.vimSinceCTRL-Cis used to copy the text to the clipboard,it can't be used tocancel an operation. UseCTRL-Break for that.CTRL-Zis used for undo. This means you can'tsuspend Vim with this key, use:suspend instead (if it's supportedat all).CTRL-V-alternativeCTRL-QSinceCTRL-Vis used to paste, you can't useit to starta blockwiseVisualselection. You can useCTRL-Q instead. You can also useCTRL-Q inInsertmode andCommand-line mode to get the old meaning ofCTRL-V. ButCTRL-Qdoesn't work for terminals when it's used forcontrol flow.NOTE: Theclipboard support still hasa number of bugs. Seetodo.==============================================================================4. Shell Commandsgui-shell-win32Vim uses anotherwindow for external commands, to makeit possible to run anycommand. The external command gets its own environment for running, just likeit was started fromaDOS prompt.win32-vimrunExecuting an external commandis done indirectly by the "vimrun" command. The"vimrun.exe"must be in the path for this to work. Oritmust be in the samedirectoryas the Vim executable. If "vimrun" cannot be found, the commandisexecuted directly, but then theDOSwindow closes immediately after theexternal command has finished.WARNING: If you close thiswindow with the "X" button, and confirm thequestion if you really want to kill the application, Vim may be killed too!(This does not apply to commands run asynchronously with ":!start".)Thewindow in which the commands are executed will be the default you have setup for "Console" in Control Panel.win32-!startNormally, Vim waits fora command to complete before continuing (this makessense for most shell commands which produce output for Vim to use). If youwant Vim to starta program and return immediately, you can use the followingsyntax::!start [/min] {command}The optional "/min" causes thewindow to be minimized.==============================================================================5.Special colorswin32-colorsOn Win32, the normalDOS colors can be used. Seedos-colors.Additionally the system configured colors can also be used. These are knownby the names Sys_XXX, where XXXis the appropriate system color name, from thefollowinglist (see theWin32 documentation for full descriptions). Caseisignored.Sys_3DDKShadowSys_3DFaceSys_BTNFaceSys_3DHilightSys_3DHighlightSys_BTNHilightSys_BTNHighlightSys_3DLightSys_3DShadowSys_BTNShadowSys_ActiveBorderSys_ActiveCaptionSys_AppWorkspaceSys_BackgroundSys_DesktopSys_BTNTextSys_CaptionTextSys_GrayTextSys_HighlightSys_HighlightTextSys_InactiveBorderSys_InactiveCaptionSys_InactiveCaptionTextSys_InfoBKSys_InfoTextSys_MenuSys_MenuTextSys_ScrollBarSys_WindowSys_WindowFrameSys_WindowTextProbably the most useful values areSys_WindowNormalwindow backgroundSys_WindowTextNormalwindow textSys_Highlight Highlighted backgroundSys_HighlightText Highlighted textThese extra colors are also available:Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,rgb.txtAdditionally, colors defined bya default colorlist can be used. For moreinfo see:colorscheme. These colors used to be defined in$VIMRUNTIME/rgb.txt, now they are inv:colornames whichis initialized from$VIMRUNTIME/colors/lists/default.vim.==============================================================================gui-w32-dialogsdialog6. Windows dialogs& browsersTheWin32GUI can use familiar Windows components for some operations,as wellas the traditionalinterface shared with the console version.6.1 DialogsThe dialogs displayed by the "confirm" family (i.e. the'confirm' option,:confirm command andconfirm() function) are GUI-based rather than theconsole-based ones used by other versions. The 'c' flag in'guioptions'changes this.6.2 File BrowsersWhen prepending ":browse" before file editing commands,a file requesterisused to allow you to select an existing file. See:browse.6.3 Tearoff MenusTheWin32GUI emulates Motif's tear-off menus. At the top of each menu youwill seea small graphic "rip here" sign. Selectingit will causea floatingwindow to be created with the same menu entries on it. The floating menu canthen be accessed justas ifit was the original (including sub-menus), butwithout having togo to the menubar each time.Thisis most useful if you find yourself usinga command buried ina sub-menuover and over again.The tearoffmenus can be positioned where you like, and always stay just abovethe Main Vim window. You can get rid of them by closing themas usual; theyalso of course close when you exit Vim.:tearoff:te:te[aroff]{name}Tear-off the menu{name}. The menu namedmust haveatleast one subentry, but need not appear on themenu-bar (seewin32-hidden-menus).Example::tearoff Filewill make the "File" menu (if thereis one) appearasa tearoff menu.:amenu ]Toolbar.Make:make<CR>:tearoff ]ToolbarThis createsa floating menu that doesn't exist on the main menu-bar.Note thata menu that starts with ']' will not be displayed.==============================================================================7. Command line argumentsgui-w32-cmdargsCommand line arguments behave the same wayas with the console application,seewin32-cmdargs.==============================================================================8. Variousgui-w32-variousgui-w32-printingThe "File/Print" menu prints the text withsyntax highlighting, see:hardcopy. If you just want to print the raw text and havea defaultprinter installed this should also work::w >>prnVim supportsa number of standardMS-Windows features. Some of these aredetailed elsewhere: see'mouse',win32-hidden-menus.drag-n-drop-win32You can drag and drop one or more files into the Vim window, where they willbe openedas normal. Seedrag-n-drop.:simalt:sim:sim[alt]{key}simulate pressing{key} while holding Alt pressed.{only for Win32 versions}Note: ":si" means ":s" with the "i" flag.Normally, Vim takescontrol of all Alt-<Key> combinations, to increase thenumber of possible mappings. This clashes with the standard use of Altas thekey for accessing menus.The quick way of getting standard behavioris to set the'winaltkeys' optionto "yes". This however prevents you frommapping Alt keysat all.Another wayis to set'winaltkeys' to "menu". Menu shortcut keys are thenhandled by windows, other ALT keys can be mapped. This doesn't allowadependency on the current state though.To get round this, the:simalt command allows Vim (when'winaltkeys'is not"yes") to fakea Windows-style Alt keypress. You can use this to map Alt keycombinations (or anything else for that matter) to produce standard Windowsactions. Here are some examples::map <M-f> :simalt f<CR>This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) bysimulating the keystrokes Alt, F.:map <M-Space> :simalt ~<CR>This maps Alt-Space to pop down the system menu for the Vim window.Note that~is used by simalt to represent the<Space> character.:map <C-n> :simalt ~n<CR>Maps Control-N to produce the keys Alt-Space followed by N. This minimizesthe Vimwindow via the system menu.Note that the key changes depending on the language you are using.intellimouse-wheel-problemsWhen using the Intellimouse mouse wheel causes Vim to stop accepting input,goto:ControlPanel- Mouse- Wheel- UniversalScrolling- ExceptionsAnd addgvim to thelist of applications. This problem only appears to happenwith the Intellimouse driver 2.2 and when "Universal Scrolling"is turned on.XPM supportw32-xpm-supportGVim can be built onMS-Windows with support for XPM files.+xpm_w32See the Make_mvc.mak file for instructions, search for XPM.To try out if XPM support worksdo this::help:let runtime = escape($VIMRUNTIME, ' \'):exe 'sign define vimxpm icon=' .. runtime .. '\\vim16x16.xpm':exe 'sign place 1 line=1 name=vimxpm file=' .. expand('%:p')You may need to get the vim16x16.xpm file from github:https://github.com/vim/vim/blob/master/runtime/vim16x16.xpmKeycode translation strategyw32-experimental-keycode-trans-strategyIn Patch v8.2.4807 W32 GVIM was changed over to experimental keycodetranslationmethod with the aim to be able to use more keyboard shortcuts andespecially supporting non-standard keyboard layouts. In order to implementthis support Win API TranslateMessage() call was dropped, and instead therecognition of keycode was changed over to ToUnicode() Win API call. Thisapproach uncovered numerous corner cases, which are apparently covered byTranslateMessage() implementation, each ofitis necessary to be dealt with onan individual basis. Therefore the decision was taken to declare thisfunctionality experimental for the time being and to recover "classic" keycodetranslationmethodas default again.Discussion about use of "experimental" keycode translationmethod willprobably last some time yet. In the meantime, if you are impacted by thischange over back to "classic" keycode translationmethod in W32 GVIM, you canenable "experimental" translationmethod again in yourvimrc using followingsnippet: :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'experimental'})Similarly, incase you need to turn back "classic" keycode translationmethod(for example fortesting purposes), please use: :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'classic'})Alternatively (thismethodis especially useful for the TINY GVIM build, wheretest_mswin_event() cannot be called), an environment variableVIM_KEYCODE_TRANS_STRATEGY can be set to the desired value("experimental" or"classic"), to override the default, e.g., type indos prompt: set VIM_KEYCODE_TRANS_STRATEGY=experimental gvim.exeTitle Bargui-w32-title-barStarting with Windows 11, you can customize the gVim titlebar (also knownasthe caption bar) by enabling the'go-C' option.Once enabled, the appearanceis controlled by two highlighting groups:1.hl-TitleBar-- Sets the color of the titlebar for the active window.2.hl-TitleBarNC-- Sets the color of the titlebar for inactive windows.To use the system's default titlebar colors, set highlighting groups toNONE:hi TitleBar guibg=NONE guifg=NONEhi TitleBarNC guibg=NONE guifg=NONEFull Screengui-w32-fullscreenTo enable fullscreen mode in the WindowsGUI version of Vim, add the 's' flagto the'guioptions' setting.For convenience, you can definea command ormapping totoggle fullscreenmode:command ToggleFullscreen { if &guioptions =~# 's' set guioptions-=s else set guioptions+=s endif}map <expr> <F11> &go =~# 's' ? ":se go-=s<CR>" : ":se go+=s<CR>"The fullscreen mode will occupy the entire screen area while hidingwindowdecorations suchas the titlebar and borders. vim:tw=78:sw=4:ts=8:noet:ft=help:norl: