| *if_ole.txt* For Vim version 7.1. Last change: 2007 May 10 |
| |
| |
| VIM REFERENCE MANUAL by Paul Moore |
| |
| |
| The OLE Interface to Vim *ole-interface* |
| |
| 1. Activation |ole-activation| |
| 2. Methods |ole-methods| |
| 3. The "normal" command |ole-normal| |
| 4. Registration |ole-registration| |
| 5. MS Visual Studio integration |MSVisualStudio| |
| |
| {Vi does not have any of these commands} |
| |
| OLE is only available when compiled with the |+ole| feature. See |
| src/if_ole.INSTALL. |
| An alternative is using the client-server communication |clientserver|. |
| |
| ============================================================================== |
| 1. Activation *ole-activation* |
| |
| Vim acts as an OLE automation server, accessible from any automation client, |
| for example, Visual Basic, Python, or Perl. The Vim application "name" (its |
| "ProgID", in OLE terminology) is "Vim.Application". |
| |
| Hence, in order to start a Vim instance (or connect to an already running |
| instance), code similar to the following should be used: |
| |
| [Visual Basic] > |
| Dim Vim As Object |
| Set Vim = CreateObject("Vim.Application") |
| |
| [Python] > |
| from win32com.client.dynamic import Dispatch |
| vim = Dispatch('Vim.Application') |
| |
| [Perl] > |
| use Win32::OLE; |
| $vim = new Win32::OLE 'Vim.Application'; |
| |
| [C#] > |
| // Add a reference to VIM in your project. |
| // Choose the COM tab. |
| // Select "VIM Ole Interface 1.1 Type Library" |
| Vim.Vim vimobj = new Vim.Vim(); |
| |
| Vim does not support acting as a "hidden" OLE server, like some other OLE |
| Automation servers. When a client starts up an instance of Vim, that instance |
| is immediately visible. Simply closing the OLE connection to the Vim instance |
| is not enough to shut down the Vim instance - it is necessary to explicitly |
| execute a quit command (for example, :qa!, :wqa). |
| |
| ============================================================================== |
| 2. Methods *ole-methods* |
| |
| Vim exposes four methods for use by clients. |
| |
| *ole-sendkeys* |
| SendKeys(keys) Execute a series of keys. |
| |
| This method takes a single parameter, which is a string of keystrokes. These |
| keystrokes are executed exactly as if they had been types in at the keyboard. |
| Special keys can be given using their <..> names, as for the right hand side |
| of a mapping. Note: Execution of the Ex "normal" command is not supported - |
| see below |ole-normal|. |
| |
| Examples (Visual Basic syntax) > |
| Vim.SendKeys "ihello<Esc>" |
| Vim.SendKeys "ma1GV4jy`a" |
| |
| These examples assume that Vim starts in Normal mode. To force Normal mode, |
| start the key sequence with CTRL-\ CTRL-N as in > |
| |
| Vim.SendKeys "<C-\><C-N>ihello<Esc>" |
| |
| CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode. |
| Note that this doesn't work halfway a Vim command |
| |
| *ole-eval* |
| Eval(expr) Evaluate an expression. |
| |
| This method takes a single parameter, which is an expression in Vim's normal |
| format (see |expression|). It returns a string, which is the result of |
| evaluating the expression. A |List| is turned into a string by joining the |
| items and inserting line breaks. |
| |
| Examples (Visual Basic syntax) > |
| Line20 = Vim.Eval("getline(20)") |
| Twelve = Vim.Eval("6 + 6") ' Note this is a STRING |
| Font = Vim.Eval("&guifont") |
| < |
| *ole-setforeground* |
| SetForeground() Make the Vim window come to the foreground |
| |
| This method takes no arguments. No value is returned. |
| |
| Example (Visual Basic syntax) > |
| Vim.SetForeground |
| < |
| |
| *ole-gethwnd* |
| GetHwnd() Return the handle of the Vim window. |
| |
| This method takes no arguments. It returns the hwnd of the main Vimwindow. |
| You can use this if you are writing something which needs to manipulate the |
| Vim window, or to track it in the z-order, etc. |
| |
| Example (Visual Basic syntax) > |
| Vim_Hwnd = Vim.GetHwnd |
| < |
| |
| ============================================================================== |
| 3. The "normal" command *ole-normal* |
| |
| Due to the way Vim processes OLE Automation commands, combined with the method |
| of implementation of the ex command :normal, it is not possible to execute the |
| :normal command via OLE automation. Any attempt to do so will fail, probably |
| harmlessly, although possibly in unpredictable ways. |
| |
| There is currently no practical way to trap this situation, and users must |
| simply be aware of the limitation. |
| ============================================================================== |
| 4. Registration *ole-registration* *E243* |
| |
| Before Vim will act as an OLE server, it must be registered in the system |
| registry. In order to do this, Vim should be run with a single parameter of |
| "-register". |
| *-register* > |
| gvim -register |
| |
| If gvim with OLE support is run and notices that no Vim OLE server has been |
| registered, it will present a dialog and offers you the choice to register by |
| clicking "Yes". |
| |
| In some situations registering is not possible. This happens when the |
| registry is not writable. If you run into this problem you need to run gvim |
| as "Administrator". |
| |
| Once vim is registered, the application path is stored in the registry. |
| Before moving, deleting, or upgrading Vim, the registry entries should be |
| removed using the "-unregister" switch. |
| *-unregister* > |
| gvim -unregister |
| |
| The OLE mechanism will use the first registered Vim it finds. If a Vim is |
| already running, this one will be used. If you want to have (several) Vim |
| sessions open that should not react to OLE commands, use the non-OLE version, |
| and put it in a different directory. The OLE version should then be put in a |
| directory that is not in your normal path, so that typing "gvim" will start |
| the non-OLE version. |
| |
| *-silent* |
| To avoid the message box that pops up to report the result, prepend "-silent": |
| > |
| gvim -silent -register |
| gvim -silent -unregister |
| |
| ============================================================================== |
| 5. MS Visual Studio integration *MSVisualStudio* *VisVim* |
| |
| The OLE version can be used to run Vim as the editor in Microsoft Visual |
| Studio. This is called "VisVim". It is included in the archive that contains |
| the OLE version. The documentation can be found in the runtime directory, the |
| README_VisVim.txt file. |
| |
| |
| Using Vim with Visual Studio .Net~ |
| |
| With .Net you no longer really need VisVim, since .Net studio has support for |
| external editors. Follow these directions: |
| |
| In .Net Studio choose from the menu Tools->External Tools... |
| Add |
| Title - Vim |
| Command - c:\vim\vim63\gvim.exe |
| Arguments - --servername VS_NET --remote-silent "+call cursor($(CurLine), $(CurCol))" $(ItemPath) |
| Init Dir - Empty |
| |
| Now, when you open a file in .Net, you can choose from the .Net menu: |
| Tools->Vim |
| |
| That will open the file in Vim. |
| You can then add this external command as an icon and place it anywhere you |
| like. You might also be able to set this as your default editor. |
| |
| If you refine this further, please post back to the Vim maillist so we have a |
| record of it. |
| |
| --servername VS_NET |
| This will create a new instance of vim called VS_NET. So if you open multiple |
| files from VS, they will use the same instance of Vim. This allows you to |
| have multiple copies of Vim running, but you can control which one has VS |
| files in it. |
| |
| --remote-silent "+call cursor(10, 27)" |
| - Places the cursor on line 10 column 27 |
| In Vim > |
| :h --remote-silent for mor details |
| |
| [.Net remarks provided by Dave Fishburn and Brian Sturk] |
| |
| ============================================================================== |
| vim:tw=78:ts=8:ft=help:norl: |