diff options
Diffstat (limited to 'src/VisVim/README_VisVim.txt')
| -rw-r--r-- | src/VisVim/README_VisVim.txt | 326 |
1 files changed, 326 insertions, 0 deletions
diff --git a/src/VisVim/README_VisVim.txt b/src/VisVim/README_VisVim.txt new file mode 100644 index 0000000..25b0fbd --- /dev/null +++ b/src/VisVim/README_VisVim.txt @@ -0,0 +1,326 @@ +=============================== +Visual Studio - Vim Integration +=============================== + +Copyright (C) 1997 Heiko Erhardt + +VisVim is a Visual Studio Add-In that allows Vim to be integrated +as the default text editor. It will be used instead of the Visual +Studio built-in editor when you double-click on a file or press F4 +after compiling (it will go to the proper line in the Vim buffer). +The file can be loaded exclusively by Vim or additionally to the +builtin Visual Studio editor (this option can be set in the VisVim +configuration dialog inside Visual Studio). +Vim does not replace the Visual Studio editor, it still runs in its +own window. + +VisVim is based upon VisEmacs by Christopher Payne +(Copyright (C) Christopher Payne 1997). + +Author: Heiko Erhardt <heiko.erhardt@gmx.net> +Based upon: VisEmacs by Christopher Payne <payneca@sagian.com> +Version: 1.0 +Created: 23 Oct 1997 +Date: 23 Oct 1997 + +VisVim was originally GNU GPL licensed, as stated below. On March 21 2012 +Heiko Erhardt declared this work to be relicensed under the Vim license, as +stated in ../../runtime/doc/uganda.txt (or ":help uganda" in Vim). + +VisVim is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +VisVim is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + + +Requirements +------------ + +VisVim works with the *OLE-enabled* version of Vim version 5.0 and higher +only!!! You must download the extra archive containing the OLE-enabled +executable from your Vim download site. When building your own Vim +executable, use the if_ole_vc.mak makefile (Vim 5.1 and higher). +VisVim needs DevStudio 5.0 or higher. It does not work with DevStudio 4.2. + + +Installation +------------ + +1) Close running instances of DevStudio. + +2) Copy VisVim.dll into a convenient directory like \vim, + \vim\lib, or \vim\addin + +3) Register the DLL using regsvr32.exe ... (Skip this on Windows 95/98) + Example: + > cd \vim\addin + > regsvr32 VisVim.dll + On NT, you should do this from an administrator account. + Before installing a new version of VisVim you should unregister + the old one using + > regsvr32 -unregister VisVim.dll + The batch files register.bat and unregister.bat can do that for you. + +3a) If you didn't do this yet: Register the OLE gvim: + > gvim -register + +4) Start Visual Studio and go to: + Tools + Customize... + Add-Ins and Macro Files + +5) Click on Browse, and point Visual Studio to your VisVim.dll file. + +6) Click the checkbox to indicate that you want to use the Add-In, and + Close the Customize dialog box. + +7) You should notice the VisVim Toolbar with the Vim Icon. + Click the first item of the toolbar to get to the options dialog. + + +Compiling VisVim +---------------- + +Two Options: + +1) Load the VisVim.mak file as a Workspace in Visual Studio and compile + +2) Use the MSVC command line compiler: + vcvars32 + nmake -f VisVim.mak + + +Using VisVim +------------ + +The VisVim DLL exposes several functions to the user. These functions are +accessible using the toolbar or by assigning hotkeys to them (see below). +The following functions are visible on the toolbar (from left to right): + +1. VisVim settings dialog + The settings you adjust here will be saved in the registry and + will be reloaded on program startup. + +2. Enable Vim + Enables Vim as Visual Studio editor. Control will be switched to Vim when: + - Clicking a file in the file view + - Clicking a compiler error message line + - Using the 'File-Open' Dialog + - Showing the current source line when encountering a debugger breakpoint. + - Using File-New + +3. Disable Vim + The internal Visual Studio editor will be used to edit files. + +4. Toggle enable state + Toggles the enable state of VisVim. Use this function if you want to have + one button only to activate/deactivate Vim. + +5. Load current file in Vim + Loads the file shown in the internal editor into Vim. Use this function if + you want the internal editor to stay active and just edit one file in Vim. + This command works always whether Vim is enabled as default editor or not. + +You cannot use DevStudio's debugger commands from inside Vim, so you should +disable Vim before running the debugger. + +You can customize the Vim toolbar itself or add the Vim buttons to other +toolbars. +To have fast access to the VisVim options dialog I suggest to create keyboard +shortcuts: + +1) Choose + Tools + Customize... + Keyboard +2) Choose Category:AddIns and Commands:VisVim. +3) Choose 'Main' as editor, enter each hotkey and press the Assign button. + I suggest: + VisVimDialogCmd Alt+Shift+V + VisVimEnableCmd Alt+Shift+E + VisVimDisableCmd Alt+Shift+D + VisVimToggleCmd Alt+Shift+T + VisVimLoadCmd Alt+Shift+G +4) Close the dialog + +Now a typical debugging example: + +Using "Alt+Shift+d" you turn off Vim before starting the debugger. +After hitting the breakpoint you single step through your application +using the internal source code editor and examine variables. +When you stumble across the line with the null pointer +assignment, just press "Alt+Shift+g", and correct the error in Vim. +Save the file, press Alt+Tab to return to DevStudio and press F7 to compile. +That's it. + + +Troubleshooting +--------------- + +1. When opening a file in DevStudio the file is opened in the DevStudio + editor and immediately vanishes. No Vim shows up. + Cause: Probably you don't have the OLE-enabled Vim or you didn't + register it. + Explanation: VisVim is notified by DevStudio if an 'open document' event + occurs. It then closes the document in the internal editor + and tries to start Vim. If Vim isn't properly OLE-registered, + this won't work. + Workaround: Download and install the OLE-enable version of Vim and + execute "gvim -register". + +2. Sometimes when clicking on a file, the file won't be opened by Vim but + instead the Visual Studio editor comes up. + Cause: The file was already loaded by the DevStudio editor. + Explanation: VisVim works by hooks exposed by Visual Studio. + Most of the functionality works from the OpenDocument hook. + If a document is already loaded in the Visual Studio editor, + no 'open document' event will be generated when clicking the + file in the file list. + Workaround: Close the document in Visual Studio first. + +3. I can't get VisVim to work. Either the Vim toolbar does not appear at all + or weird crashes happen. + Cause: The Visual Studio installation is messed up. + Explanation: I can't give you one. Ask M$. + Workaround: Reinstall DevStudio (I know this is brute, but in some cases + it helped). There was one case where the service pack 1 had + to be installed, too. + +4. If an instance of Vim is already running, VisVim will use that instance + and not start a new one. + Cause: This is proper OLE behaviour + Explanation: Some call it a bug, some a feature. That's just the way OLE + works. + +5. When being in insert mode in Vim and selecting a file in Visual Studio, + the Vim command :e ... is inserted as text instead of being executed. + Cause: You probably know... + Explanation: The Vim OLE automation interface interprets the VisVim + commands as if they were typed in by the user. + So if you're in insert mode Vim considers it to be text. + I decided against sending an ESC before the command because + it may cause a beep or at least a screen flash when noeb is + set. + Workaround: Get used to press ESC before switching to DevStudio. + +6. I'm tired of VisVim but I can't get rid of it. I can't delete it in + Tools-Customize-Add-Ins. + Cause: You can't delete an item you once added to the add-ins + list box. + Explanation: M$ just didn't put a 'delete' button in the dialog box. + Unfortunately there is no DEL key accellerator as well... + Workaround: You can't kill it, but you can knock it out: + 1. Uncheck the check box in front of 'Vim Developer Studio + Add-in'. + 2. Close Visual Studio. + 3. Delete VisVim.dll or move it somewhere it can't be found. + 4. Run Visual Studio. + 5. Tools -> Customize ->Add-ins and Macro-Files. + 6. A message appears: + ".../VisVim.dll" "This add-in no longer exists. It will + no longer be displayed." + That's it! + + +Change history +-------------- + +1.0a to 1.0 +----------- + +- All settings in the VisVim dialog are remembered between DevStudio sessions + by keeping them in the registry (HKEY_CURRENT_USER\Software\Vim\VisVim). +- Added an option to do a :cd before opening the file (having a file opened + by clicking it but finding out to be still in C:\Windows\system when trying to + open another file by ":e" can be annoying). Change directory can be + done to the source file's directory or it's parent directory. +- Added some explanations to the error message for the CO_E_CLASSSTRING error + ("Use OLE Vim and make sure to register..."). + +1.0 to 1.1a +----------- + +- The VisVim toolbar button now shows the new Vim icon instead of the old one. +- Made some changes to the documentation, added the troubleshooting chapter + and ToDo list. +- File-New-* now invokes Vim instead of the builtin editor if enabled. + +1.1 to 1.1b +----------- + +- Extended the VisVim toolbar to have multiple buttons instead of one. +- Moved the enable/disable commands from the settings dialog to the toolbar. +- Added the toggle enable/disable command +- Added the 'load current file' command. + +1.1b to 1.2 +----------- + +No new features, just some fine tuning: + +- Changed the GUID of the VisVim OLE interface to avoid conflicts with a + version of VisEmacs or VisVile on the same computer (Guy Gascoigne) +- Fixed a bug caused by a bug in the Developer Studio add-in code generator + (Clark Morgan) +- Fixed a memory leak (Clark Morgan) +- Added an option in the VisVim dialog to prepend ESC before the first command + that is sent to Vim. This will avoid inserting the command as text when Vim + is still in insert mode. +- An :update command is sent to Vim before any other command to update the + current file if it is modified, or else the following :cd or :e command will fail. + +1.2 to 1.3a +----------- + +- Fixed a bug caused by a missing EnableModeless() function call in VimLoad(). + This seems to reduce VisVim crashing DevStudio on some systems (it + occasionally still seems to happen, but it's more stable now). + (Vince Negri) +- Added support for the new CTRL-\ CTRL-N command of Vim 5.4a. + This prevents Vim from beeping when a VisVim command is executed and Vim is + not in insert mode. + + +ToDo List +--------- + +P1 is highest priority, P10 lowest + +P9 Switching to DevStudio using ALT-TAB may get annoying. Would be nice to + have the option to map ActivateApplication("Visual Studio") in Vim. + Vim DLLs would solve that problem. + +P8 Execute :tag command in Vim for word under cursor in DevStudio + +P7 Controlling the Visual Studio Debugger from inside Vim + See message above. Also a 'Debug' highlight group and a + command to highlight a certain line would be necessary. + +P6 Provide an option to open the current file in VisVim in + Visual Studio editor + Same as above message. A kind of two way OLE automation would have to be + established between VisVim and Vim. Also a 'Debug' highlight group and a + command to highlight a certain line would be necessary. + + +Known Problems +-------------- + +- Occasional memory corruptions in DevStudio may appear on some systems. + Reinstalling DevStudio helped in some cases. + The cause of these crashes is unclear; there is no way to debug this. + Recompiling VisVim with DevStudio SP3 didn't help. + I assume it's a problem deep inside the DevStudio add-in OLE interfaces. + This will hopefully be fixed with DevStudio 6. + + +Have fun! + +Heiko Erhardt +heiko.erhardt@gmx.net + |