diff options
Diffstat (limited to 'runtime/doc/if_ole.txt')
| -rw-r--r-- | runtime/doc/if_ole.txt | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/runtime/doc/if_ole.txt b/runtime/doc/if_ole.txt new file mode 100644 index 0000000..8417637 --- /dev/null +++ b/runtime/doc/if_ole.txt @@ -0,0 +1,203 @@ +*if_ole.txt* For Vim version 8.2. Last change: 2019 Dec 07 + + + 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| + +{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 more details + +[.Net remarks provided by Dave Fishburn and Brian Sturk] + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: |