codekingpro/portable-devtools

1*if_ole.txt*	For Vim version 9.2.  Last change: 2026 Feb 142 3 4		  VIM REFERENCE MANUAL	  by Paul Moore5 6 7The OLE Interface to Vim				*ole-interface*8 91. Activation			|ole-activation|102. Methods			|ole-methods|113. The "normal" command		|ole-normal|124. Registration			|ole-registration|135. MS Visual Studio integration	|MSVisualStudio|14 15{only available when compiled with the |+ole| feature.  See16src/if_ole.INSTALL}17An alternative is using the client-server communication |clientserver|.18 19==============================================================================201. Activation						*ole-activation*21 22Vim acts as an OLE automation server, accessible from any automation client,23for example, Visual Basic, Python, or Perl.  The Vim application "name" (its24"ProgID", in OLE terminology) is "Vim.Application".25 26Hence, in order to start a Vim instance (or connect to an already running27instance), code similar to the following should be used:28 29[Visual Basic] >30	Dim Vim As Object31	Set Vim = CreateObject("Vim.Application")32 33[Python] >34	from win32com.client.dynamic import Dispatch35	vim = Dispatch('Vim.Application')36 37[Perl] >38	use Win32::OLE;39	$vim = new Win32::OLE 'Vim.Application';40 41[C#] >42	// Add a reference to Vim in your project.43	// Choose the COM tab.44	// Select "Vim Ole Interface 1.1 Type Library"45	Vim.Vim vimobj = new Vim.Vim();46 47Vim does not support acting as a "hidden" OLE server, like some other OLE48Automation servers.  When a client starts up an instance of Vim, that instance49is immediately visible.  Simply closing the OLE connection to the Vim instance50is not enough to shut down the Vim instance - it is necessary to explicitly51execute a quit command (for example, :qa!, :wqa).52 53==============================================================================542. Methods						*ole-methods*55 56Vim exposes four methods for use by clients.57 58							*ole-sendkeys*59SendKeys(keys)		Execute a series of keys.60 61This method takes a single parameter, which is a string of keystrokes.  These62keystrokes are executed exactly as if they had been typed in at the keyboard.63Special keys can be given using their <..> names, as for the right hand side64of a mapping.  Note: Execution of the Ex "normal" command is not supported -65see below |ole-normal|.66 67Examples (Visual Basic syntax) >68	Vim.SendKeys "ihello<Esc>"69	Vim.SendKeys "ma1GV4jy`a"70 71These examples assume that Vim starts in Normal mode.  To force Normal mode,72start the key sequence with CTRL-\ CTRL-N as in >73 74	Vim.SendKeys "<C-\><C-N>ihello<Esc>"75 76CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.77Note that this doesn't work halfway a Vim command78 79							*ole-eval*80Eval(expr)		Evaluate an expression.81 82This method takes a single parameter, which is an expression in Vim's normal83format (see |expression|).  It returns a string, which is the result of84evaluating the expression.  A |List| is turned into a string by joining the85items and inserting line breaks.86 87Examples (Visual Basic syntax) >88	Line20 = Vim.Eval("getline(20)")89	Twelve = Vim.Eval("6 + 6")		' Note this is a STRING90	Font = Vim.Eval("&guifont")91<92							*ole-setforeground*93SetForeground()		Make the Vim window come to the foreground94 95This method takes no arguments.  No value is returned.96 97Example (Visual Basic syntax) >98	Vim.SetForeground99<100 101							*ole-gethwnd*102GetHwnd()		Return the handle of the Vim window.103 104This method takes no arguments.  It returns the hwnd of the main Vimwindow.105You can use this if you are writing something which needs to manipulate the106Vim window, or to track it in the z-order, etc.107 108Example (Visual Basic syntax) >109	Vim_Hwnd = Vim.GetHwnd110<111 112==============================================================================1133. The "normal" command					*ole-normal*114 115Due to the way Vim processes OLE Automation commands, combined with the method116of implementation of the Ex command :normal, it is not possible to execute the117:normal command via OLE automation.  Any attempt to do so will fail, probably118harmlessly, although possibly in unpredictable ways.119 120There is currently no practical way to trap this situation, and users must121simply be aware of the limitation.122==============================================================================1234. Registration					*ole-registration* *E243*124 125Before Vim will act as an OLE server, it must be registered in the system126registry.  In order to do this, Vim should be run with a single parameter of127"-register".128							*-register*  >129	gvim -register130 131If gvim with OLE support is run and notices that no Vim OLE server has been132registered, it will present a dialog and offers you the choice to register by133clicking "Yes".134 135In some situations registering is not possible.  This happens when the136registry is not writable.  If you run into this problem you need to run gvim137as "Administrator".138 139Once vim is registered, the application path is stored in the registry.140Before moving, deleting, or upgrading Vim, the registry entries should be141removed using the "-unregister" switch.142							*-unregister*  >143	gvim -unregister144 145The OLE mechanism will use the first registered Vim it finds.  If a Vim is146already running, this one will be used.  If you want to have (several) Vim147sessions open that should not react to OLE commands, use the non-OLE version,148and put it in a different directory.  The OLE version should then be put in a149directory that is not in your normal path, so that typing "gvim" will start150the non-OLE version.151 152							*-silent*153To avoid the message box that pops up to report the result, prepend "-silent":154>155	gvim -silent -register156	gvim -silent -unregister157 158==============================================================================1595. MS Visual Studio integration				*MSVisualStudio*160 161The old "VisVim" integration was removed from Vim in patch 9.0.0698.162 163 164Using Vim with Visual Studio .Net~165 166.Net studio has support for external editors.  Follow these directions:167 168In .Net Studio choose from the menu Tools->External Tools...169Add170     Title     - Vim171     Command   - c:\vim\vim63\gvim.exe172     Arguments - --servername VS_NET --remote-silent "+call cursor($(CurLine), $(CurCol))" $(ItemPath)173     Init Dir  - Empty174 175Now, when you open a file in .Net, you can choose from the .Net menu:176Tools->Vim177 178That will open the file in Vim.179You can then add this external command as an icon and place it anywhere you180like.  You might also be able to set this as your default editor.181 182If you refine this further, please post back to the Vim maillist so we have a183record of it.184 185--servername VS_NET186This will create a new instance of vim called VS_NET.  So if you open multiple187files from VS, they will use the same instance of Vim.  This allows you to188have multiple copies of Vim running, but you can control which one has VS189files in it.190 191--remote-silent "+call cursor(10, 27)"192	      - Places the cursor on line 10 column 27193In Vim >194   :h --remote-silent for more details195 196[.Net remarks provided by Dave Fishburn and Brian Sturk]197 198==============================================================================199 vim:tw=78:ts=8:noet:ft=help:norl:200