blob: fbe3f35e7458c88ae141c8deeb03fef59f3c6031 [file] [log] [blame]
Bram Moolenaar3b1db362013-08-10 15:00:24 +02001*gui_w32.txt* For Vim version 7.4. Last change: 2012 Aug 04
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
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.
Bram Moolenaarfa13eef2013-02-06 17:34:04 +010020|os_win32.txt| For Win32 specific items.
Bram Moolenaar071d4272004-06-13 20:20:40 +000021
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
Bram Moolenaar78e17622007-08-30 10:26:19 +000056
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
Bram Moolenaar071d4272004-06-13 20:20:40 +000066==============================================================================
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
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000712. Choose View/Options -> File Types
Bram Moolenaar071d4272004-06-13 20:20:40 +0000723. 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
Bram Moolenaarc236c162008-07-13 17:41:49 +0000132with gvim". Choosing this menu option will invoke gvim with the file you have
Bram Moolenaar071d4272004-06-13 20:20:40 +0000133selected. 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
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200140The "edit with existing Vim" entries can be disabled by adding an entry in the
141registry under HKLM\Software\Vim\Gvim, named DisableEditWithExisting, and with
142any value.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000143 *install-registry*
144You can add the "Edit with Vim" menu entry in an easy way by using the
145"install.exe" program. It will add several registry entries for you.
146
147You can also do this by hand. This is complicated! Use the install.exe if
148you can.
149
1501. Start the registry editor with "regedit".
1512. Add these keys:
152 key value name value ~
153 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}
154 {default} Vim Shell Extension
155 HKEY_CLASSES_ROOT\CLSID\{51EEE242-AD87-11d3-9C1E-0090278BBD99}\InProcServer32
156 {default} {path}\gvimext.dll
157 ThreadingModel Apartment
158 HKEY_CLASSES_ROOT\*\shellex\ContextMenuHandlers\gvim
159 {default} {51EEE242-AD87-11d3-9C1E-0090278BBD99}
160 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved
161 {51EEE242-AD87-11d3-9C1E-0090278BBD99}
162 Vim Shell Extension
163 HKEY_LOCAL_MACHINE\Software\Vim\Gvim
164 path {path}\gvim.exe
165 HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\vim 5.6
166 DisplayName Vim 5.6: Edit with Vim popup menu entry
167 UninstallString {path}\uninstal.exe
168
169 Replace {path} with the path that leads to the executable.
170 Don't type {default}, this is the value for the key itself.
171
172To remove "Edit with Vim" from the popup menu, just remove the registry
173entries mentioned above. The "uninstal.exe" program can do this for you. You
174can also use the entry in the Windows standard "Add/Remove Programs" list.
175
176If you notice that this entry overrules other file type associations, set
177those associations again by hand (using Windows Explorer, see above). This
178only seems to happen on some Windows NT versions (Windows bug?). Procedure:
1791. Find the name of the file type. This can be done by starting the registry
180 editor, and searching for the extension in \\HKEY_CLASSES_ROOT
1812. In a Windows Explorer, use View/Options/File Types. Search for the file
182 type in the list and click "Edit". In the actions list, you can select on
183 to be used as the default (normally the "open" action) and click on the
184 "Set Default" button.
185
186
187Vim in the "Open With..." context menu *win32-open-with-menu*
188
189If you use the Vim install program you have the choice to add Vim to the "Open
190With..." menu. This means you can use Vim to edit many files. Not every file
191(for unclear reasons...), thus the "Edit with Vim" menu entry is still useful.
192
193One reason to add this is to be able to edit HTML files directly from Internet
194Explorer. To enable this use the "Tools" menu, "Internet Options..." entry.
195In the dialog select the "Programs" tab and select Vim in the "HTML editor"
196choice. If it's not there than installing didn't work properly.
197
198Doing this manually can be done with this script:
199
200----------------------------------------------------------
201REGEDIT4
202
203[HKEY_CLASSES_ROOT\Applications\gvim.exe]
204
205[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell]
206
207[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit]
208
209[HKEY_CLASSES_ROOT\Applications\gvim.exe\shell\edit\command]
210@="c:\\vim\\vim62\\gvim.exe \"%1\""
211
212[HKEY_CLASSES_ROOT\.htm\OpenWithList\gvim.exe]
213
214[HKEY_CLASSES_ROOT\*\OpenWithList\gvim.exe]
215
216----------------------------------------------------------
217
218Change the "c:\\vim\\vim62" bit to where gvim.exe is actually located.
219
220To uninstall this run the Vim uninstall program or manually delete the
221registry entries with "regedit".
222
223==============================================================================
2243. Using the clipboard *gui-clipboard*
225
226Windows has a clipboard, where you can copy text to, and paste text from. Vim
227supports this in several ways. For other systems see |gui-selections|.
228
229The "* register reflects the contents of the clipboard. |quotestar|
230
231When the "unnamed" string is included in the 'clipboard' option, the unnamed
232register is the same. Thus you can yank to and paste from the clipboard
233without prepending "* to commands.
234
235The 'a' flag in 'guioptions' is not included by default. This means that text
236is only put on the clipboard when an operation is performed on it. Just
237Visually selecting text doesn't put it on the clipboard. When the 'a' flag is
238included, the text is copied to the clipboard even when it is not operated
239upon.
240
241 *mswin.vim*
242To use the standard MS-Windows way of CTRL-X, CTRL-C and CTRL-V, use the
243$VIMRUNTIME/mswin.vim script. You could add this line to your _vimrc file: >
244 source $VIMRUNTIME/mswin.vim
245
246Since CTRL-C is used to copy the text to the clipboard, it can't be used to
247cancel an operation. Use CTRL-Break for that.
248
Bram Moolenaar9964e462007-05-05 17:54:07 +0000249CTRL-Z is used for undo. This means you can't suspend Vim with this key, use
250|:suspend| instead (if it's supported at all).
Bram Moolenaar6f7926c2005-01-07 21:45:22 +0000251
Bram Moolenaardf177f62005-02-22 08:39:57 +0000252 *CTRL-V-alternative* *CTRL-Q*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000253Since CTRL-V is used to paste, you can't use it to start a blockwise Visual
254selection. You can use CTRL-Q instead. You can also use CTRL-Q in Insert
255mode and Command-line mode to get the old meaning of CTRL-V. But CTRL-Q
256doesn't work for terminals when it's used for control flow.
257
258NOTE: The clipboard support still has a number of bugs. See |todo|.
259
260==============================================================================
2614. Shell Commands *gui-shell-win32*
262
263Vim uses another window for external commands, to make it possible to run any
264command. The external command gets its own environment for running, just like
265it was started from a DOS prompt.
266
267 *win32-vimrun*
268Executing an external command is done indirectly by the "vimrun" command. The
269"vimrun.exe" must be in the path for this to work. Or it must be in the same
270directory as the Vim executable. If "vimrun" cannot be found, the command is
271executed directly, but then the DOS window closes immediately after the
272external command has finished.
273WARNING: If you close this window with the "X" button, and confirm the
274question if you really want to kill the application, Vim may be killed too!
275(This does not apply to commands run asynchronously with ":!start".)
276
277In Windows 95, the window in which the commands are executed is always 25x80
278characters, to be as DOS compatible as possible (this matters!). The default
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000279system font is used. On NT, the window will be the default you have set up for
280"Console" in Control Panel. On Win32s, the properties of the DOS box are
Bram Moolenaar071d4272004-06-13 20:20:40 +0000281determined by _default.pif in the windows directory.
282
283 *msdos-mode*
284If you get a dialog that says "This program is set to run in MS-DOS mode..."
285when you run an external program, you can solve this by changing the
286properties of the associated shortcut:
287- Use a Windows Explorer to find the command.com that is used. It can be
288 c:\command.com, c:\dos\command.com, c:\windows\command.com, etc.
289- With the right mouse button, select properties of this command.com.
290- In the Program tab select "Advanced".
291- Unselect "MS-DOS mode".
292- Click "OK" twice.
293
294 *win32-!start*
295Normally, Vim waits for a command to complete before continuing (this makes
296sense for most shell commands which produce output for Vim to use). If you
297want Vim to start a program and return immediately, you can use the following
298syntax on W95 & NT: >
Bram Moolenaar2a8a3ec2011-01-08 16:06:37 +0100299 :!start [/min] {command}
300The optional "/min" causes the window to be minimized.
301
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000302On Win32s, you will have to go to another window instead. Don't forget that
Bram Moolenaar071d4272004-06-13 20:20:40 +0000303you must tell Windows 3.1x to keep executing a DOS command in the background
304while you switch back to Vim.
305
306==============================================================================
3075. Special colors *win32-colors*
308
309On Win32, the normal DOS colors can be used. See |dos-colors|.
310
311Additionally the system configured colors can also be used. These are known
312by the names Sys_XXX, where XXX is the appropriate system color name, from the
313following list (see the Win32 documentation for full descriptions). Case is
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000314ignored. Note: On Win32s not all of these colors are supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000315
316Sys_3DDKShadow Sys_3DFace Sys_BTNFace
317Sys_3DHilight Sys_3DHighlight Sys_BTNHilight
318Sys_BTNHighlight Sys_3DLight Sys_3DShadow
319Sys_BTNShadow Sys_ActiveBorder Sys_ActiveCaption
320Sys_AppWorkspace Sys_Background Sys_Desktop
321Sys_BTNText Sys_CaptionText Sys_GrayText
322Sys_Highlight Sys_HighlightText Sys_InactiveBorder
323Sys_InactiveCaption Sys_InactiveCaptionText Sys_InfoBK
324Sys_InfoText Sys_Menu Sys_MenuText
325Sys_ScrollBar Sys_Window Sys_WindowFrame
326Sys_WindowText
327
328Probably the most useful values are
329 Sys_Window Normal window background
330 Sys_WindowText Normal window text
331 Sys_Highlight Highlighted background
332 Sys_HighlightText Highlighted text
333
334These extra colors are also available:
335Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
336
337 *rgb.txt*
338Additionally, colors defined by a "rgb.txt" file can be used. This file is
339well known from X11. A few lines from it: >
340
341 255 218 185 peach puff
342 205 133 63 peru
343 255 181 197 pink
344
345This shows the layout of the file: First the R, G and B value as a decimal
346number, followed by the name of the color. The four fields are separated by
347spaces.
348
349You can get an rgb.txt file from any X11 distribution. It is located in a
350directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the
351$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt".
352
353==============================================================================
354 *gui-w32-dialogs* *dialog*
3556. Windows dialogs & browsers
356
357The Win32 GUI can use familiar Windows components for some operations, as well
358as the traditional interface shared with the console version.
359
360
3616.1 Dialogs
362
363The dialogs displayed by the "confirm" family (i.e. the 'confirm' option,
364|:confirm| command and |confirm()| function) are GUI-based rather than the
365console-based ones used by other versions. The 'c' flag in 'guioptions'
366changes this.
367
368
3696.2 File Browsers
370
371When prepending ":browse" before file editing commands, a file requester is
372used to allow you to select an existing file. See |:browse|.
373
374
3756.3 Tearoff Menus
376
377The Win32 GUI emulates Motif's tear-off menus. At the top of each menu you
378will see a small graphic "rip here" sign. Selecting it will cause a floating
379window to be created with the same menu entries on it. The floating menu can
380then be accessed just as if it was the original (including sub-menus), but
381without having to go to the menu bar each time.
382This is most useful if you find yourself using a command buried in a sub-menu
383over and over again.
384The tearoff menus can be positioned where you like, and always stay just above
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000385the Main Vim window. You can get rid of them by closing them as usual; they
Bram Moolenaar071d4272004-06-13 20:20:40 +0000386also of course close when you exit Vim.
387
388 *:tearoff* *:te*
389:te[aroff] {name} Tear-off the menu {name}. The menu named must have at
390 least one subentry, but need not appear on the
391 menu-bar (see |win32-hidden-menus|).
392
393Example: >
394 :tearoff File
395will make the "File" menu (if there is one) appear as a tearoff menu. >
396
397 :amenu ]Toolbar.Make :make<CR>
398 :tearoff ]Toolbar
399This creates a floating menu that doesn't exist on the main menu-bar.
400
401Note that a menu that starts with ']' will not be displayed.
402
403==============================================================================
4047. Command line arguments *gui-w32-cmdargs*
405
406Analysis of a command line into parameters is not standardised in MS Windows.
407Gvim has to provide logic to analyse a command line. This logic is likely to
408be different from the default logic provided by a compilation system used to
409build vim. The differences relate to unusual double quote (") usage.
410The arguments "C:\My Music\freude.txt" and "+/Sch\"iller" are handled in the
411same way. The argument "+/Sch""iller" may be handled different by gvim and
412vim, depending what it was compiled with.
413
414The rules are:
415 a) A parameter is a sequence of graphic characters.
416 b) Parameters are separated by white space.
417 c) A parameter can be enclosed in double quotes to include white space.
418 d) A sequence of zero or more backslashes (\) and a double quote (")
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000419 is special. The effective number of backslashes is halved, rounded
Bram Moolenaar071d4272004-06-13 20:20:40 +0000420 down. An even number of backslashes reverses the acceptability of
421 spaces and tabs, an odd number of backslashes produces a literal
422 double quote.
423
424So:
425 " is a special double quote
426 \" is a literal double quote
427 \\" is a literal backslash and a special double quote
428 \\\" is a literal backslash and a literal double quote
429 \\\\" is 2 literal backslashes and a special double quote
430 \\\\\" is 2 literal backslashes and a literal double quote
431 etc.
432
433Example: >
434 gvim "C:\My Music\freude" +"set ignorecase" +/"\"foo\\" +\"bar\\\"
435
436opens "C:\My Music\freude" and executes the line mode commands: >
437 set ignorecase; /"foo\ and /bar\"
438
439==============================================================================
4408. Various *gui-w32-various*
441
442 *gui-w32-printing*
443The "File/Print" menu prints the text with syntax highlighting, see
444|:hardcopy|. If you just want to print the raw text and have a default
445printer installed this should also work: >
446 :w >>prn
447
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000448Vim supports a number of standard MS Windows features. Some of these are
Bram Moolenaar071d4272004-06-13 20:20:40 +0000449detailed elsewhere: see |'mouse'|, |win32-hidden-menus|.
450
451 *drag-n-drop-win32*
452You can drag and drop one or more files into the Vim window, where they will
453be opened as normal. See |drag-n-drop|.
454
455 *:simalt* *:si*
456:sim[alt] {key} simulate pressing {key} while holding Alt pressed.
457 {not in Vi} {only for Win32 versions}
458
459Normally, Vim takes control of all Alt-<Key> combinations, to increase the
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000460number of possible mappings. This clashes with the standard use of Alt as the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000461key for accessing menus.
462The quick way of getting standard behavior is to set the 'winaltkeys' option
463to "yes". This however prevents you from mapping Alt keys at all.
464Another way is to set 'winaltkeys' to "menu". Menu shortcut keys are then
465handled by windows, other ALT keys can be mapped. This doesn't allow a
466dependency on the current state though.
467To get round this, the :simalt command allows Vim (when 'winaltkeys' is not
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000468"yes") to fake a Windows-style Alt keypress. You can use this to map Alt key
Bram Moolenaar071d4272004-06-13 20:20:40 +0000469combinations (or anything else for that matter) to produce standard Windows
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000470actions. Here are some examples: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000471
472 :map <M-f> :simalt f<CR>
473This makes Alt-F pop down the 'File' menu (with the stock Menu.vim) by
474simulating the keystrokes Alt, F. >
475 :map <M-Space> :simalt ~<CR>
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000476This maps Alt-Space to pop down the system menu for the Vim window. Note that
Bram Moolenaar071d4272004-06-13 20:20:40 +0000477~ is used by simalt to represent the <Space> character. >
478 :map <C-n> :simalt ~n<CR>
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000479Maps Control-N to produce the keys Alt-Space followed by N. This minimizes the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000480Vim window via the system menu.
481
Bram Moolenaar9964e462007-05-05 17:54:07 +0000482Note that the key changes depending on the language you are using.
483
Bram Moolenaar071d4272004-06-13 20:20:40 +0000484 *intellimouse-wheel-problems*
485When using the Intellimouse mouse wheel causes Vim to stop accepting input, go
486to:
487 ControlPanel - Mouse - Wheel - UniversalScrolling - Exceptions
488
489And add gvim to the list of applications. This problem only appears to happen
490with the Intellimouse driver 2.2 and when "Universal Scrolling" is turned on.
491
Bram Moolenaar9b451252012-08-15 17:43:31 +0200492
493XPM support *w32-xpm-support*
494
495Gvim can be build on MS-Windows with support for XPM files. |+xpm_w32|
496See the Make_mvc.mak file for instructions, search for XPM.
497
498To try out if XPM support works do this: >
499 :help
500 :exe 'sign define vimxpm icon=' . $VIMRUNTIME . '\\vim16x16.xpm'
501 :exe 'sign place 1 line=1 name=vimxpm file=' . expand('%:p')
502<
503
Bram Moolenaar071d4272004-06-13 20:20:40 +0000504 vim:tw=78:sw=4:ts=8:ft=help:norl: