codekingpro/portable-devtools

1*gui_w32.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Bram Moolenaar5 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 you27start it or what it's called.28 29The GUI will always run in the Windows subsystem.  Mostly shells automatically30return with a command prompt after starting gvim.  If not, you should use the31"start" command: >32	start gvim [options] file ..33<							*E988*34The console version with the |-g| option may also start the GUI by executing35gvim.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 an41experimental 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 the43GUI Vim.44 45Note: All fonts (bold, italic) must be of the same size!!!  If you don't do46this, text will disappear or mess up the display.  Vim does not check the font47sizes.  It's the size in screen pixels that must be the same.  Note that some48fonts that have the same point size don't have the same pixel size!49Additionally, the positioning of the fonts must be the same (ascent and50descent).51 52The Win32 GUI has an extra menu item:  "Edit/Select Font".  It brings up the53standard 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 your59vimrc or gvimrc file: >60	au GUIEnter * simalt ~x61<62 63Using Vim as a plugin					*gui-w32-windowid*64 65When gvim starts up normally, it creates its own top level window.  If you66pass Vim the command-line option |--windowid| with a decimal or hexadecimal67value, Vim will create a window that is a child of the window with the given68ID.  This enables Vim to act as a plugin in another application.  This really69is a programmer's interface, and is of no use without a supporting application70to 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 Explorer772. Choose View/Options -> File Types783. 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 an80   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.  But87   I'm not sure if this works everywhere.88 89When you open a file in Vim by double clicking it, Vim changes to that90file'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 with982. <Shift-F10>993. select "Open With..." menu entry1004. click "Other..."1015. browse to the (new) location of Vim and click "Open"1026. make "Always Use this program..." checked1037. <OK>104 105						*send-to-menu* *sendto*106You can also install Vim in the "Send To" menu:1071. Start a Windows Explorer1082. Navigate to your sendto directory:109   C:\Users\%user%\AppData\Roaming\Microsoft\Windows\SendTo .1103. Right-click in the file pane and select New->Shortcut1114. Follow the shortcut wizard, using the full path to VIM/GVIM.112 113When you 'send a file to Vim', Vim changes to that file's directory.  Note,114however, that any long directory names will appear in their short (MS-DOS)115form on some Windows versions.  This is a limitation of the Windows "Send To"116mechanism.117 118						*notepad*119You could replace notepad.exe with gvim.exe, but that has a few side effects.120Some programs rely on notepad arguments, which are not recognized by Vim.  For121example "notepad -p" is used by some applications to print a file.  It's122better to leave notepad where it is and use another way to start Vim.123 124						*win32-popup-menu*125A more drastic approach is to install an "Edit with Vim" entry in the popup126menu for the right mouse button.  With this you can edit any file with Vim.127 128This can co-exist with the file associations mentioned above.  The difference129is that the file associations will make starting Vim the default action.  With130the "Edit with Vim" menu entry you can keep the existing file association for131double clicking on the file, and edit the file with Vim when you want.  For132example, you can associate "*.mak" with your make program.  You can execute133the makefile by double clicking it and use the "Edit with Vim" entry to edit134the makefile.135 136You can select any files and right-click to see a menu option called "Edit137with gvim".  Choosing this menu option will invoke gvim with the file you have138selected.  If you select multiple files, you will find two gvim-related menu139options:140"Edit with multiple gvims"  -- one gvim for each file in the selection141"Edit with single gvim"     -- one gvim for all the files in the selection142And if there already is a gvim running:143"Edit with existing gvim"   -- edit the file with the running gvim144 145The "edit with existing Vim" entries can be disabled by adding an entry in the146registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with147any value.148						*install-registry*149You can add the "Edit with Vim" menu entry in an easy way by using the150"install.exe" program.  It will add several registry entries for you.151 152You can also do this by hand.  This is complicated!  Use the install.exe if153you can.154 1551. Start the registry editor with "regedit".1562. Add these keys:157   key		value name		    value ~158   HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}159		{default}		    Vim Shell Extension160   HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32161		{default}		    {path}\gvimext.dll162		ThreadingModel		    Apartment163   HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim164		{default}		    {51EEE242-AD87-11d3-9C1E-0090278BBD99}165   HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved166		{51EEE242-AD87-11d3-9C1E-0090278BBD99}167					    Vim Shell Extension168   HKEY_LOCAL_MACHINE\Software\Vim\Gvim169		path			    {path}\gvim.exe170   HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 8.2171		DisplayName		    Vim 8.2: Edit with Vim popup menu entry172		UninstallString		    {path}\uninstall.exe173 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 177To remove "Edit with Vim" from the popup menu, just remove the registry178entries mentioned above.  The "uninstall.exe" program can do this for you.179You can also use the entry in the Windows standard "Add/Remove Programs" list.180 181If you notice that this entry overrules other file type associations, set182those associations again by hand (using Windows Explorer, see above).  This183only seems to happen on some Windows NT versions (Windows bug?).  Procedure:1841. Find the name of the file type.  This can be done by starting the registry185   editor, and searching for the extension in \\HKEY_CLASSES_ROOT1862. In a Windows Explorer, use View/Options/File Types.  Search for the file187   type in the list and click "Edit".  In the actions list, you can select on188   to be used as the default (normally the "open" action) and click on the189   "Set Default" button.190 191 192Vim in the "Open With..." context menu			*win32-open-with-menu*193 194If you use the Vim install program you have the choice to add Vim to the "Open195With..." menu.  This means you can use Vim to edit many files.  Not every file196(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful.197 198One reason to add this is to be able to edit HTML files directly from Internet199Explorer.  To enable this use the "Tools" menu, "Internet Options..." entry.200In the dialog select the "Programs" tab and select Vim in the "HTML editor"201choice.  If it's not there then installing didn't work properly.202 203Doing this manually can be done with this script:204 205----------------------------------------------------------206REGEDIT4207 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 223Change the "c:\\vim\\vim82" bit to where gvim.exe is actually located.224 225To uninstall this run the Vim uninstall program or manually delete the226registry entries with "regedit".227 228==============================================================================2293. Using the clipboard					*gui-clipboard*230 231Windows has a clipboard, where you can copy text to, and paste text from.  Vim232supports this in several ways.  For other systems see |gui-selections|.233 234The "* register reflects the contents of the clipboard.  |quotestar|235 236When the "unnamed" string is included in the 'clipboard' option, the unnamed237register is the same.  Thus you can yank to and paste from the clipboard238without prepending "* to commands.  If this doesn't work use the "unnamedplus"239string in the 'clipboard' option.240 241The 'a' flag in 'guioptions' is not included by default.  This means that text242is only put on the clipboard when an operation is performed on it.  Just243Visually selecting text doesn't put it on the clipboard.  When the 'a' flag is244included, the text is copied to the clipboard even when it is not operated245upon.246 247							*mswin.vim*248To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the249$VIMRUNTIME/mswin.vim script.  You could add this line to your _vimrc file: >250	source $VIMRUNTIME/mswin.vim251 252Since CTRL-C is used to copy the text to the clipboard, it can't be used to253cancel an operation.  Use CTRL-Break for that.254 255CTRL-Z is used for undo.  This means you can't suspend Vim with this key, use256|: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 Visual260selection.  You can use CTRL-Q instead.  You can also use CTRL-Q in Insert261mode and Command-line mode to get the old meaning of CTRL-V.  But CTRL-Q262doesn'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 any270command.  The external command gets its own environment for running, just like271it was started from a DOS prompt.272 273							*win32-vimrun*274Executing an external command is done indirectly by the "vimrun" command.  The275"vimrun.exe" must be in the path for this to work.  Or it must be in the same276directory as the Vim executable.  If "vimrun" cannot be found, the command is277executed directly, but then the DOS window closes immediately after the278external command has finished.279WARNING: If you close this window with the "X" button, and confirm the280question 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 set284up for "Console" in Control Panel.285 286							*win32-!start*287Normally, Vim waits for a command to complete before continuing (this makes288sense for most shell commands which produce output for Vim to use).  If you289want Vim to start a program and return immediately, you can use the following290syntax: >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 known300by the names Sys_XXX, where XXX is the appropriate system color name, from the301following list (see the Win32 documentation for full descriptions).  Case is302ignored.303 304Sys_3DDKShadow		Sys_3DFace			Sys_BTNFace305Sys_3DHilight		Sys_3DHighlight			Sys_BTNHilight306Sys_BTNHighlight	Sys_3DLight			Sys_3DShadow307Sys_BTNShadow		Sys_ActiveBorder		Sys_ActiveCaption308Sys_AppWorkspace	Sys_Background			Sys_Desktop309Sys_BTNText		Sys_CaptionText			Sys_GrayText310Sys_Highlight		Sys_HighlightText		Sys_InactiveBorder311Sys_InactiveCaption	Sys_InactiveCaptionText		Sys_InfoBK312Sys_InfoText		Sys_Menu			Sys_MenuText313Sys_ScrollBar		Sys_Window			Sys_WindowFrame314Sys_WindowText315 316Probably the most useful values are317	Sys_Window	    Normal window background318	Sys_WindowText      Normal window text319	Sys_Highlight       Highlighted background320	Sys_HighlightText   Highlighted text321 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 more327info see |:colorscheme|.  These colors used to be defined in328$VIMRUNTIME/rgb.txt, now they are in |v:colornames| which is initialized from329$VIMRUNTIME/colors/lists/default.vim.330 331==============================================================================332						*gui-w32-dialogs* *dialog*3336. Windows dialogs & browsers334 335The Win32 GUI can use familiar Windows components for some operations, as well336as the traditional interface shared with the console version.337 338 3396.1 Dialogs340 341The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,342|:confirm| command and |confirm()| function) are GUI-based rather than the343console-based ones used by other versions.  The 'c' flag in 'guioptions'344changes this.345 346 3476.2 File Browsers348 349When prepending ":browse" before file editing commands, a file requester is350used to allow you to select an existing file.  See |:browse|.351 352 3536.3 Tearoff Menus354 355The Win32 GUI emulates Motif's tear-off menus.  At the top of each menu you356will see a small graphic "rip here" sign.  Selecting it will cause a floating357window to be created with the same menu entries on it.  The floating menu can358then be accessed just as if it was the original (including sub-menus), but359without having to go to the menu bar each time.360This is most useful if you find yourself using a command buried in a sub-menu361over and over again.362The tearoff menus can be positioned where you like, and always stay just above363the Main Vim window.  You can get rid of them by closing them as usual; they364also 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 at368			least one subentry, but need not appear on the369			menu-bar (see |win32-hidden-menus|).370 371Example: >372	:tearoff File373will make the "File" menu (if there is one) appear as a tearoff menu. >374 375	:amenu ]Toolbar.Make	:make<CR>376	:tearoff ]Toolbar377This 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, see392|:hardcopy|.  If you just want to print the raw text and have a default393printer installed this should also work: >394	:w >>prn395 396Vim supports a number of standard MS-Windows features.  Some of these are397detailed 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 will401be 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 the409number of possible mappings.  This clashes with the standard use of Alt as the410key for accessing menus.411The quick way of getting standard behavior is to set the 'winaltkeys' option412to "yes".  This however prevents you from mapping Alt keys at all.413Another way is to set 'winaltkeys' to "menu".  Menu shortcut keys are then414handled by windows, other ALT keys can be mapped.  This doesn't allow a415dependency on the current state though.416To get round this, the :simalt command allows Vim (when 'winaltkeys' is not417"yes") to fake a Windows-style Alt keypress.  You can use this to map Alt key418combinations (or anything else for that matter) to produce standard Windows419actions.  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) by423simulating 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 that426~ 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 minimizes429the Vim 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, go435to:436	ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions437 438And add gvim to the list of applications.  This problem only appears to happen439with 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	:help449	: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.xpm455 456 457Keycode translation strategy    *w32-experimental-keycode-trans-strategy*458 459In Patch v8.2.4807 W32 GVIM was changed over to experimental keycode460translation method with the aim to be able to use more keyboard shortcuts and461especially supporting non-standard keyboard layouts.  In order to implement462this support Win API TranslateMessage() call was dropped, and instead the463recognition of keycode was changed over to ToUnicode() Win API call.  This464approach uncovered numerous corner cases, which are apparently covered by465TranslateMessage() implementation, each of it is necessary to be dealt with on466an individual basis.  Therefore the decision was taken to declare this467functionality experimental for the time being and to recover "classic" keycode468translation method as default again.469 470Discussion about use of "experimental" keycode translation method will471probably last some time yet.  In the meantime, if you are impacted by this472change over back to "classic" keycode translation method in W32 GVIM, you can473enable "experimental" translation method again in your vimrc using following474snippet:475>476  :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'experimental'})477<478Similarly, in case you need to turn back "classic" keycode translation method479(for example for testing purposes), please use:480>481  :call test_mswin_event('set_keycode_trans_strategy', {'strategy': 'classic'})482<483Alternatively (this method is especially useful for the TINY GVIM build, where484test_mswin_event() cannot be called), an environment variable485VIM_KEYCODE_TRANS_STRATEGY can be set to the desired value ("experimental" or486"classic"), to override the default, e.g., type in dos prompt:487>488        set VIM_KEYCODE_TRANS_STRATEGY=experimental489        gvim.exe490<491 492Title Bar						*gui-w32-title-bar*493 494Starting with Windows 11, you can customize the gVim title bar (also known as495the caption bar) by enabling the |'go-C'| option.496 497Once enabled, the appearance is controlled by two highlighting groups:4981. |hl-TitleBar|   -- Sets the color of the title bar for the active window.4992. |hl-TitleBarNC| -- Sets the color of the title bar for inactive windows.500 501To use the system's default title bar colors, set highlighting groups to502`NONE`: >503 504	hi TitleBar guibg=NONE guifg=NONE505	hi TitleBarNC guibg=NONE guifg=NONE506<507 508Full Screen						*gui-w32-fullscreen*509 510To enable fullscreen mode in the Windows GUI version of Vim, add the 's' flag511to the 'guioptions' setting.512 513For convenience, you can define a command or mapping to toggle fullscreen514mode:515>516	command ToggleFullscreen {517	  if &guioptions =~# 's'518	    set guioptions-=s519	  else520	    set guioptions+=s521	  endif522	}523 524	map <expr> <F11> &go =~# 's' ? ":se go-=s<CR>" : ":se go+=s<CR>"525 526The fullscreen mode will occupy the entire screen area while hiding window527decorations such as the title bar and borders.528 529 vim:tw=78:sw=4:ts=8:noet:ft=help:norl:530