summaryrefslogtreecommitdiffstats
path: root/runtime/doc/if_ole.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--runtime/doc/if_ole.txt199
1 files changed, 199 insertions, 0 deletions
diff --git a/runtime/doc/if_ole.txt b/runtime/doc/if_ole.txt
new file mode 100644
index 0000000..9f899dd
--- /dev/null
+++ b/runtime/doc/if_ole.txt
@@ -0,0 +1,199 @@
+*if_ole.txt* For Vim version 9.0. Last change: 2022 Oct 08
+
+
+ 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*
+
+The old "VisVim" integration was removed from Vim in patch 9.0.0698.
+
+
+Using Vim with Visual Studio .Net~
+
+.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: