README_VisVim.txt
1===============================
2Visual Studio - Vim Integration
3===============================
4
5Copyright (C) 1997 Heiko Erhardt
6
7VisVim is a Visual Studio Add-In that allows Vim to be integrated
8as the default text editor. It will be used instead of the Visual
9Studio built-in editor when you double-click on a file or press F4
10after compiling (it will go to the proper line in the Vim buffer).
11The file can be loaded exclusively by Vim or additionally to the
12builtin Visual Studio editor (this option can be set in the VisVim
13configuration dialog inside Visual Studio).
14Vim does not replace the Visual Studio editor, it still runs in its
15own window.
16
17VisVim is based upon VisEmacs by Christopher Payne
18(Copyright (C) Christopher Payne 1997).
19
20Author: Heiko Erhardt <Heiko.Erhardt@munich.netsurf.de>
21Based upon: VisEmacs by Christopher Payne <payneca@sagian.com>
22Version: 1.0
23Created: 23 Oct 1997
24Date: 23 Oct 1997
25
26VisVim is free software; you can redistribute it and/or modify
27it under the terms of the GNU General Public License as published by
28the Free Software Foundation; either version 2, or (at your option)
29any later version.
30
31VisVim is distributed in the hope that it will be useful,
32but WITHOUT ANY WARRANTY; without even the implied warranty of
33MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
34GNU General Public License for more details.
35
36
37Requirements
38------------
39
40VisVim works with the *OLE-enabled* version of Vim version 5.0 and higher
41only!!! You must download the extra archive containing the OLE-enabled
42executable from your Vim download site. When building your own Vim
43executable, use the if_ole_vc.mak makefile (Vim 5.1 and higher).
44VisVim needs DevStudio 5.0 or higher. It does not work with DevStudio 4.2.
45
46
47Installation
48------------
49
501) Close running instances of DevStudio.
51
522) Copy VisVim.dll into a convenient directory like \vim,
53 \vim\lib, or \vim\addin
54
553) Register the DLL using regsvr32.exe ... (Skip this on Windows 95/98)
56 Example:
57 > cd \vim\addin
58 > regsvr32 VisVim.dll
59 On NT, you should do this from an administrator account.
60 Before installing a new version of VisVim you should unregister
61 the old one using
62 > regsvr32 -unregister VisVim.dll
63 The batch files register.bat and unregister.bat can do that for you.
64
653a) If you didn't do this yet: Register the OLE gvim:
66 > gvim -register
67
684) Start Visual Studio and go to:
69 Tools
70 Customize...
71 Add-Ins and Macro Files
72
735) Click on Browse, and point Visual Studio to your VisVim.dll file.
74
756) Click the checkbox to indicate that you want to use the Add-In, and
76 Close the Customize dialog box.
77
787) You should notice the VisVim Toolbar with the Vim Icon.
79 Click the first item of the toolbar to get to the options dialog.
80
81
82Compiling VisVim
83----------------
84
85Two Options:
86
871) Load the VisVim.mak file as a Workspace in Visual Studio and compile
88
892) Use the MSVC command line compiler:
90 vcvars32
91 nmake -f VisVim.mak
92
93
94Using VisVim
95------------
96
97The VisVim DLL exposes several functions to the user. These functions are
98accessible using the toolbar or by assigning hotkeys to them (see below).
99The following functions are visible on the toolbar (from left to right):
100
1011. VisVim settings dialog
102 The settings you adjust here will be saved in the registry and
103 will be reloaded on program startup.
104
1052. Enable Vim
106 Enables Vim as Visual Studio editor. Control will be switched to Vim when:
107 - Clicking a file in the file view
108 - Clicking a compiler error message line
109 - Using the 'File-Open' Dialog
110 - Showing the current source line when encountering a debugger breakpoint.
111 - Using File-New
112
1133. Disable Vim
114 The internal Visual Studio editor will be used to edit files.
115
1164. Toggle enable state
117 Toggles the enable state of VisVim. Use this function if you want to have
118 one button only to activate/deactivate Vim.
119
1205. Load current file in Vim
121 Loads the file shown in the internal editor into Vim. Use this function if
122 you want the internal editor to stay active and just edit one file in Vim.
123 This command works always whether Vim is enabled as default editor or not.
124
125You cannot use DevStudio's debugger commands from inside Vim, so you should
126disable Vim before running the debugger.
127
128You can customize the Vim toolbar itself or add the Vim buttons to other
129toolbars.
130To have fast access to the VisVim options dialog I suggest to create keyboard
131shortcuts:
132
1331) Choose
134 Tools
135 Customize...
136 Keyboard
1372) Choose Category:AddIns and Commands:VisVim.
1383) Choose 'Main' as editor, enter each hotkey and press the Assign button.
139 I suggest:
140 VisVimDialogCmd Alt+Shift+V
141 VisVimEnableCmd Alt+Shift+E
142 VisVimDisableCmd Alt+Shift+D
143 VisVimToggleCmd Alt+Shift+T
144 VisVimLoadCmd Alt+Shift+G
1454) Close the dialog
146
147Now a typical debugging example:
148
149Using "Alt+Shift+d" you turn off Vim before starting the debugger.
150After hitting the breakpoint you single step through your application
151using the internal source code editor and examine variables.
152When you stumble across the line with the null pointer
153assignment, just press "Alt+Shift+g", and correct the error in Vim.
154Save the file, press Alt+Tab to return to DevStudio and press F7 to compile.
155That's it.
156
157
158Troubleshooting
159---------------
160
1611. When opening a file in DevStudio the file is opened in the DevStudio
162 editor and immediately vanishes. No Vim shows up.
163 Cause: Probably you don't have the OLE-enabled Vim or you didn't
164 register it.
165 Explanation: VisVim is notified by DevStudio if an 'open document' event
166 occurs. It then closes the document in the internal editor
167 and tries to start Vim. If Vim isn't properly OLE-registered,
168 this won't work.
169 Workaround: Download and install the OLE-enable version of Vim and
170 execute "gvim -register".
171
1722. Sometimes when clicking on a file, the file won't be opened by Vim but
173 instead the Visual Studio editor comes up.
174 Cause: The file was already loaded by the DevStudio editor.
175 Explanation: VisVim works by hooks exposed by Visual Studio.
176 Most of the functionality works from the OpenDocument hook.
177 If a document is already loaded in the Visual Studio editor,
178 no 'open document' event will be generated when clicking the
179 file in the file list.
180 Workaround: Close the document in Visual Studio first.
181
1823. I can't get VisVim to work. Either the Vim toolbar does not appear at all
183 or weird crashes happen.
184 Cause: The Visual Studio installation is messed up.
185 Explanation: I can't give you one. Ask M$.
186 Workaround: Reinstall DevStudio (I know this is brute, but in some cases
187 it helped). There was one case where the service pack 1 had
188 to be installed, too.
189
1904. If an instance of Vim is already running, VisVim will use that instance
191 and not start a new one.
192 Cause: This is proper OLE behaviour
193 Explanation: Some call it a bug, some a feature. That's just the way OLE
194 works.
195
1965. When being in insert mode in Vim and selecting a file in Visual Studio,
197 the Vim command :e ... is inserted as text instead of being executed.
198 Cause: You probably know...
199 Explanation: The Vim OLE automation interface interprets the VisVim
200 commands as if they were typed in by the user.
201 So if you're in insert mode Vim considers it to be text.
202 I decided against sending an ESC before the command because
203 it may cause a beep or at least a screen flash when noeb is
204 set.
205 Workaround: Get used to press ESC before switching to DevStudio.
206
2076. I'm tired of VisVim but I can't get rid of it. I can't delete it in
208 Tools-Customize-Add-Ins.
209 Cause: You can't delete an item you once added to the add-ins
210 list box.
211 Explanation: M$ just didn't put a 'delete' button in the dialog box.
212 Unfortunately there is no DEL key accellerator as well...
213 Workaround: You can't kill it, but you can knock it out:
214 1. Uncheck the check box in front of 'Vim Developer Studio
215 Add-in'.
216 2. Close Visual Studio.
217 3. Delete VisVim.dll or move it somewhere it can't be found.
218 4. Run Visual Studio.
219 5. Tools -> Cursomize ->Add-ins and Macro-Files.
220 6. A message appears:
221 ".../VisVim.dll" "This add-in no longer exists. It will
222 no longer be displayed."
223 That's it!
224
225
226Change history
227--------------
228
2291.0a to 1.0
230-----------
231
232- All settings in the VisVim dialog are remembered between DevStudio sessions
233 by keeping them in the registry (HKEY_CURRENT_USER\Software\Vim\VisVim).
234- Added an option to do a :cd before opening the file (having a file opened
235 by clicking it but finding out to be still in C:\Windows\system when trying to
236 open another file by ":e" can be annoying). Change directory can be
237 done to the source file's directory or it's parent directory.
238- Added some explanations to the error message for the CO_E_CLASSSTRING error
239 ("Use OLE Vim and make sure to register...").
240
2411.0 to 1.1a
242-----------
243
244- The VisVim toolbar button now shows the new Vim icon instead of the old one.
245- Made some changes to the documentation, added the troubleshooting chapter
246 and ToDo list.
247- File-New-* now invokes Vim instead of the builtin editor if enabled.
248
2491.1 to 1.1b
250-----------
251
252- Extended the VisVim toolbar to have multiple buttons instead of one.
253- Moved the enable/disable commands from the settings dialog to the toolbar.
254- Added the toggle enable/disable command
255- Added the 'load current file' command.
256
2571.1b to 1.2
258-----------
259
260No new features, just some fine tuning:
261
262- Changed the GUID of the VisVim OLE interface to avoid conflicts with a
263 version of VisEmacs or VisVile on the same computer (Guy Gascoigne)
264- Fixed a bug caused by a bug in the Developer Studio add-in code generator
265 (Clark Morgan)
266- Fixed a memory leak (Clark Morgan)
267- Added an option in the VisVim dialog to prepend ESC before the first command
268 that is sent to Vim. This will avoid inserting the command as text when Vim
269 is still in insert mode.
270- An :update command is sent to Vim before any other command to update the
271 current file if it is modified, or else the following :cd or :e command will fail.
272
2731.2 to 1.3a
274-----------
275
276- Fixed a bug caused by a missing EnableModeless() function call in VimLoad().
277 This seems to reduce VisVim crashing DevStudio on some systems (it
278 occasionally still seems to happen, but it's more stable now).
279 (Vince Negri)
280- Added support for the new CTRL-\ CTRL-N command of Vim 5.4a.
281 This prevents Vim from beeping when a VisVim command is executed an Vim is
282 not in insert mode.
283
284
285ToDo List
286---------
287
288P1 is highest priority, P10 lowest
289
290P9 Switching to DevStudio using ALT-TAB may get annoying. Would be nice to
291 have the option to map ActivateApplication("Visual Studio") in Vim.
292 Vim DLLs would solve that problem.
293
294P8 Execute :tag command in Vim for word under cursor in DevStudio
295
296P7 Controlling the Visual Studio Debugger from inside Vim
297 See message above. Also a 'Debug' highligh group and a
298 command to highlight a certain line would be necessary.
299
300P6 Provide an option to open the current file in VisVim in
301 Visual Studio editor
302 Same as above message. A kind of two way OLE automation would have to be
303 established between VisVim and Vim. Also a 'Debug' highlight group and a
304 command to highlight a certain line would be necessary.
305
306
307Known Problems
308--------------
309
310- Occasional memory corruptions in DevStudio may appear on some systems.
311 Reinstalling DevStudio helped in some cases.
312 The cause of these crashes is unclear; there is no way to debug this.
313 Recompiling VisVim with DevStudio SP3 didn't help.
314 I assume it's a problem deep inside the DevStudio add-in OLE interfaces.
315 This will hopefully be fixed with DevStudio 6.
316
317
318Have fun!
319
320Heiko Erhardt
321Heiko.Erhardt@munich.netsurf.de
322
323