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