src/VisVim/README_VisVim.txt

   1 ===============================
   2 Visual Studio - Vim Integration
   3 ===============================
   4
   5 Copyright (C) 1997 Heiko Erhardt
   6
   7 VisVim is a Visual Studio Add-In that allows Vim to be integrated
   8 as the default text editor. It will be used instead of the Visual
   9 Studio built-in editor when you double-click on a file or press F4
  10 after compiling (it will go to the proper line in the Vim buffer).
  11 The file can be loaded exclusively by Vim or additionally to the
  12 builtin Visual Studio editor (this option can be set in the VisVim
  13 configuration dialog inside Visual Studio).
  14 Vim does not replace the Visual Studio editor, it still runs in its
  15 own window.
  16
  17 VisVim is based upon VisEmacs by Christopher Payne
  18 (Copyright (C) Christopher Payne 1997).
  19
  20 Author: Heiko Erhardt <Heiko.Erhardt@munich.netsurf.de>
  21 Based upon: VisEmacs by Christopher Payne <payneca@sagian.com>
  22 Version: 1.0
  23 Created: 23 Oct 1997
  24 Date: 23 Oct 1997
  25
  26 VisVim is free software; you can redistribute it and/or modify
  27 it under the terms of the GNU General Public License as published by
  28 the Free Software Foundation; either version 2, or (at your option)
  29 any later version.
  30
  31 VisVim is distributed in the hope that it will be useful,
  32 but WITHOUT ANY WARRANTY; without even the implied warranty of
  33 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  34 GNU General Public License for more details.
  35
  36
  37 Requirements
  38 ------------
  39
  40 VisVim works with the *OLE-enabled* version of Vim version 5.0 and higher
  41 only!!!  You must download the extra archive containing the OLE-enabled
  42 executable from your Vim download site.  When building your own Vim
  43 executable, use the if_ole_vc.mak makefile (Vim 5.1 and higher).
  44 VisVim needs DevStudio 5.0 or higher. It does not work with DevStudio 4.2.
  45
  46
  47 Installation
  48 ------------
  49
  50 1) Close running instances of DevStudio.
  51
  52 2) Copy VisVim.dll into a convenient directory like \vim,
  53    \vim\lib, or \vim\addin
  54
  55 3) 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
  65 3a) If you didn't do this yet: Register the OLE gvim:
  66    > gvim -register
  67
  68 4) Start Visual Studio and go to:
  69       Tools
  70          Customize...
  71             Add-Ins and Macro Files
  72
  73 5) Click on Browse, and point Visual Studio to your VisVim.dll file.
  74
  75 6) Click the checkbox to indicate that you want to use the Add-In, and
  76    Close the Customize dialog box.
  77
  78 7) 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
  82 Compiling VisVim
  83 ----------------
  84
  85 Two Options:
  86
  87 1) Load the VisVim.mak file as a Workspace in Visual Studio and compile
  88
  89 2) Use the MSVC command line compiler:
  90         vcvars32
  91         nmake -f VisVim.mak
  92
  93
  94 Using VisVim
  95 ------------
  96
  97 The VisVim DLL exposes several functions to the user. These functions are
  98 accessible using the toolbar or by assigning hotkeys to them (see below).
  99 The following functions are visible on the toolbar (from left to right):
 100
 101 1. VisVim settings dialog
 102    The settings you adjust here will be saved in the registry and
 103    will be reloaded on program startup.
 104
 105 2. 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
 113 3. Disable Vim
 114    The internal Visual Studio editor will be used to edit files.
 115
 116 4. 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
 120 5. 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
 125 You cannot use DevStudio's debugger commands from inside Vim, so you should
 126 disable Vim before running the debugger.
 127
 128 You can customize the Vim toolbar itself or add the Vim buttons to other
 129 toolbars.
 130 To have fast access to the VisVim options dialog I suggest to create keyboard
 131 shortcuts:
 132
 133 1) Choose
 134       Tools
 135          Customize...
 136             Keyboard
 137 2) Choose Category:AddIns and Commands:VisVim.
 138 3) 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
 145 4) Close the dialog
 146
 147 Now a typical debugging example:
 148
 149 Using "Alt+Shift+d" you turn off Vim before starting the debugger.
 150 After hitting the breakpoint you single step through your application
 151 using the internal source code editor and examine variables.
 152 When you stumble across the line with the null pointer
 153 assignment, just press "Alt+Shift+g", and correct the error in Vim.
 154 Save the file, press Alt+Tab to return to DevStudio and press F7 to compile.
 155 That's it.
 156
 157
 158 Troubleshooting
 159 ---------------
 160
 161 1. 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
 172 2. 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
 182 3. 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
 190 4. 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
 196 5. 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
 207 6. 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
 226 Change history
 227 --------------
 228
 229 1.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
 241 1.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
 249 1.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
 257 1.1b to 1.2
 258 -----------
 259
 260 No 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
 273 1.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
 285 ToDo List
 286 ---------
 287
 288 P1 is highest priority, P10 lowest
 289
 290 P9  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
 294 P8  Execute :tag command in Vim for word under cursor in DevStudio
 295
 296 P7  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
 300 P6  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
 307 Known 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
 318 Have fun!
 319
 320 Heiko Erhardt
 321 Heiko.Erhardt@munich.netsurf.de
 322