vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: