if_ole.txt - html version

*if_ole.txt*    For Vim version 5.0.  Last modification: 1998 Jan 25

		  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|

{Vi does not have any of these commands}

OLE is only available when compiled with the |+ole| feature.  See
src/if_ole.INSTALL.



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';

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 three 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 <Esc> as in

>	Vim.SendKeys "<Esc>ihello<Esc>"



							*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.

Examples (Visual Basic syntax)
>	Line20 = Vim.Expr("getline(20)")
>	Twelve = Vim.Expr("6 + 6")		'' Note this is a STRING
>	Font = Vim.Expr("&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



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*

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".

>	gvim -register

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.

>	gvim -unregister

top - back to help