blob: 9ced34ecab1a6144065d651c9d67257703e15c44 [file] [log] [blame]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001*if_ole.txt* For Vim version 7.0aa. Last change: 2003 Jun 19
2
3
4 VIM REFERENCE MANUAL by Paul Moore
5
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{Vi does not have any of these commands}
16
17OLE is only available when compiled with the |+ole| feature. See
18src/if_ole.INSTALL.
19An alternative is using the client-server communication |clientserver|.
20
21==============================================================================
221. Activation *ole-activation*
23
24Vim acts as an OLE automation server, accessible from any automation client,
25for example, Visual Basic, Python, or Perl. The Vim application "name" (its
26"ProgID", in OLE terminology) is "Vim.Application".
27
28Hence, in order to start a Vim instance (or connect to an already running
29instance), code similar to the following should be used:
30
31[Visual Basic] >
32 Dim Vim As Object
33 Set Vim = CreateObject("Vim.Application")
34
35[Python] >
36 from win32com.client.dynamic import Dispatch
37 vim = Dispatch('Vim.Application')
38
39[Perl] >
40 use Win32::OLE;
41 $vim = new Win32::OLE 'Vim.Application';
42
43Vim does not support acting as a "hidden" OLE server, like some other OLE
44Automation servers. When a client starts up an instance of Vim, that instance
45is immediately visible. Simply closing the OLE connection to the Vim instance
46is not enough to shut down the Vim instance - it is necessary to explicitly
47execute a quit command (for example, :qa!, :wqa).
48
49==============================================================================
502. Methods *ole-methods*
51
52Vim exposes four methods for use by clients.
53
54 *ole-sendkeys*
55SendKeys(keys) Execute a series of keys.
56
57This method takes a single parameter, which is a string of keystrokes. These
58keystrokes are executed exactly as if they had been types in at the keyboard.
59Special keys can be given using their <..> names, as for the right hand side
60of a mapping. Note: Execution of the Ex "normal" command is not supported -
61see below |ole-normal|.
62
63Examples (Visual Basic syntax) >
64 Vim.SendKeys "ihello<Esc>"
65 Vim.SendKeys "ma1GV4jy`a"
66
67These examples assume that Vim starts in Normal mode. To force Normal mode,
68start the key sequence with CTRL-\ CTRL-N as in >
69
70 Vim.SendKeys "<C-\><C-N>ihello<Esc>"
71
72CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.
73Note that this doesn't work halfway a Vim command
74
75 *ole-eval*
76Eval(expr) Evaluate an expression.
77
78This method takes a single parameter, which is an expression in Vim's normal
79format (see |expression|). It returns a string, which is the result of
80evaluating the expression.
81
82Examples (Visual Basic syntax) >
83 Line20 = Vim.Eval("getline(20)")
84 Twelve = Vim.Eval("6 + 6") ' Note this is a STRING
85 Font = Vim.Eval("&guifont")
86<
87 *ole-setforeground*
88SetForeground() Make the Vim window come to the foreground
89
90This method takes no arguments. No value is returned.
91
92Example (Visual Basic syntax) >
93 Vim.SetForeground
94<
95
96 *ole-gethwnd*
97GetHwnd() Return the handle of the Vim window.
98
99This method takes no arguments. It returns the hwnd of the main Vimwindow.
100You can use this if you are writing something which needs to manipulate the
101Vim window, or to track it in the z-order, etc.
102
103Example (Visual Basic syntax) >
104 Vim_Hwnd = Vim.GetHwnd
105<
106
107==============================================================================
1083. The "normal" command *ole-normal*
109
110Due to the way Vim processes OLE Automation commands, combined with the method
111of implementation of the ex command :normal, it is not possible to execute the
112:normal command via OLE automation. Any attempt to do so will fail, probably
113harmlessly, although possibly in unpredictable ways.
114
115There is currently no practical way to trap this situation, and users must
116simply be aware of the limitation.
117==============================================================================
1184. Registration *ole-registration* *E243*
119
120Before Vim will act as an OLE server, it must be registered in the system
121registry. In order to do this, Vim should be run with a single parameter of
122"-register".
123 *-register* >
124 gvim -register
125
126If gvim with OLE support is run and notices that no Vim OLE server has been
127registered, it will present a dialog and offers you the choice to register by
128clicking "Yes".
129
130In some situations registering is not possible. This happens when the
131registry is not writable. If you run into this problem you need to run gvim
132as "Administrator".
133
134Once vim is registered, the application path is stored in the registry. Before
135moving, deleting, or upgrading Vim, the registry entries should be removed
136using the "-unregister" switch.
137 *-unregister* >
138 gvim -unregister
139
140The OLE mechanism will use the first registered Vim it finds. If a Vim is
141already running, this one will be used. If you want to have (several) Vim
142sessions open that should not react to OLE commands, use the non-OLE version,
143and put it in a different directory. The OLE version should then be put in a
144directory that is not in your normal path, so that typing "gvim" will start
145the non-OLE version.
146
147 *-silent*
148To avoid the message box that pops up to report the result, prepend "-silent":
149>
150 gvim -silent -register
151 gvim -silent -unregister
152
153==============================================================================
1545. MS Visual Studio integration *MSVisualStudio* *VisVim*
155
156The OLE version can be used to run Vim as the editor in Microsoft Visual
157Studio. This is called "VisVim". It is included in the archive that contains
158the OLE version. The documentation can be found in the runtime directory, the
159README_VisVim.txt file.
160
161==============================================================================
162 vim:tw=78:ts=8:ft=help:norl: