Mercurial > vim
annotate runtime/doc/if_ole.txt @ 20622:d487701a608e
Added tag v8.2.0864 for changeset d30b16692ce0ef62ead483068caa67cb03c2b795
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 31 May 2020 18:00:04 +0200 |
parents | af69c9335223 |
children | f8116058ca76 |
rev | line source |
---|---|
18879 | 1 *if_ole.txt* For Vim version 8.2. Last change: 2019 Dec 07 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Paul Moore | |
5 | |
6 | |
7 The OLE Interface to Vim *ole-interface* | |
8 | |
9 1. Activation |ole-activation| | |
10 2. Methods |ole-methods| | |
11 3. The "normal" command |ole-normal| | |
12 4. Registration |ole-registration| | |
13 5. MS Visual Studio integration |MSVisualStudio| | |
14 | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
15 {only available when compiled with the |+ole| feature. See |
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
16 src/if_ole.INSTALL} |
7 | 17 An alternative is using the client-server communication |clientserver|. |
18 | |
19 ============================================================================== | |
20 1. Activation *ole-activation* | |
21 | |
22 Vim acts as an OLE automation server, accessible from any automation client, | |
236 | 23 for example, Visual Basic, Python, or Perl. The Vim application "name" (its |
7 | 24 "ProgID", in OLE terminology) is "Vim.Application". |
25 | |
26 Hence, in order to start a Vim instance (or connect to an already running | |
27 instance), code similar to the following should be used: | |
28 | |
29 [Visual Basic] > | |
30 Dim Vim As Object | |
31 Set Vim = CreateObject("Vim.Application") | |
32 | |
33 [Python] > | |
34 from win32com.client.dynamic import Dispatch | |
35 vim = Dispatch('Vim.Application') | |
36 | |
37 [Perl] > | |
38 use Win32::OLE; | |
39 $vim = new Win32::OLE 'Vim.Application'; | |
40 | |
1199 | 41 [C#] > |
18831 | 42 // Add a reference to Vim in your project. |
1199 | 43 // Choose the COM tab. |
11473 | 44 // Select "Vim Ole Interface 1.1 Type Library" |
1199 | 45 Vim.Vim vimobj = new Vim.Vim(); |
46 | |
7 | 47 Vim does not support acting as a "hidden" OLE server, like some other OLE |
236 | 48 Automation servers. When a client starts up an instance of Vim, that instance |
49 is immediately visible. Simply closing the OLE connection to the Vim instance | |
7 | 50 is not enough to shut down the Vim instance - it is necessary to explicitly |
51 execute a quit command (for example, :qa!, :wqa). | |
52 | |
53 ============================================================================== | |
54 2. Methods *ole-methods* | |
55 | |
56 Vim exposes four methods for use by clients. | |
57 | |
58 *ole-sendkeys* | |
59 SendKeys(keys) Execute a series of keys. | |
60 | |
236 | 61 This method takes a single parameter, which is a string of keystrokes. These |
7 | 62 keystrokes are executed exactly as if they had been types in at the keyboard. |
63 Special keys can be given using their <..> names, as for the right hand side | |
236 | 64 of a mapping. Note: Execution of the Ex "normal" command is not supported - |
7 | 65 see below |ole-normal|. |
66 | |
67 Examples (Visual Basic syntax) > | |
68 Vim.SendKeys "ihello<Esc>" | |
69 Vim.SendKeys "ma1GV4jy`a" | |
70 | |
236 | 71 These examples assume that Vim starts in Normal mode. To force Normal mode, |
7 | 72 start the key sequence with CTRL-\ CTRL-N as in > |
73 | |
74 Vim.SendKeys "<C-\><C-N>ihello<Esc>" | |
75 | |
76 CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode. | |
77 Note that this doesn't work halfway a Vim command | |
78 | |
79 *ole-eval* | |
80 Eval(expr) Evaluate an expression. | |
81 | |
82 This method takes a single parameter, which is an expression in Vim's normal | |
83 format (see |expression|). It returns a string, which is the result of | |
714 | 84 evaluating the expression. A |List| is turned into a string by joining the |
85 items and inserting line breaks. | |
7 | 86 |
87 Examples (Visual Basic syntax) > | |
88 Line20 = Vim.Eval("getline(20)") | |
89 Twelve = Vim.Eval("6 + 6") ' Note this is a STRING | |
90 Font = Vim.Eval("&guifont") | |
91 < | |
92 *ole-setforeground* | |
93 SetForeground() Make the Vim window come to the foreground | |
94 | |
95 This method takes no arguments. No value is returned. | |
96 | |
97 Example (Visual Basic syntax) > | |
98 Vim.SetForeground | |
99 < | |
100 | |
101 *ole-gethwnd* | |
102 GetHwnd() Return the handle of the Vim window. | |
103 | |
104 This method takes no arguments. It returns the hwnd of the main Vimwindow. | |
105 You can use this if you are writing something which needs to manipulate the | |
106 Vim window, or to track it in the z-order, etc. | |
107 | |
108 Example (Visual Basic syntax) > | |
109 Vim_Hwnd = Vim.GetHwnd | |
110 < | |
111 | |
112 ============================================================================== | |
113 3. The "normal" command *ole-normal* | |
114 | |
115 Due to the way Vim processes OLE Automation commands, combined with the method | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
116 of implementation of the Ex command :normal, it is not possible to execute the |
236 | 117 :normal command via OLE automation. Any attempt to do so will fail, probably |
7 | 118 harmlessly, although possibly in unpredictable ways. |
119 | |
120 There is currently no practical way to trap this situation, and users must | |
121 simply be aware of the limitation. | |
122 ============================================================================== | |
123 4. Registration *ole-registration* *E243* | |
124 | |
125 Before Vim will act as an OLE server, it must be registered in the system | |
236 | 126 registry. In order to do this, Vim should be run with a single parameter of |
7 | 127 "-register". |
128 *-register* > | |
129 gvim -register | |
130 | |
131 If gvim with OLE support is run and notices that no Vim OLE server has been | |
132 registered, it will present a dialog and offers you the choice to register by | |
133 clicking "Yes". | |
134 | |
135 In some situations registering is not possible. This happens when the | |
136 registry is not writable. If you run into this problem you need to run gvim | |
137 as "Administrator". | |
138 | |
236 | 139 Once vim is registered, the application path is stored in the registry. |
140 Before moving, deleting, or upgrading Vim, the registry entries should be | |
141 removed using the "-unregister" switch. | |
7 | 142 *-unregister* > |
143 gvim -unregister | |
144 | |
145 The OLE mechanism will use the first registered Vim it finds. If a Vim is | |
146 already running, this one will be used. If you want to have (several) Vim | |
147 sessions open that should not react to OLE commands, use the non-OLE version, | |
148 and put it in a different directory. The OLE version should then be put in a | |
149 directory that is not in your normal path, so that typing "gvim" will start | |
150 the non-OLE version. | |
151 | |
152 *-silent* | |
153 To avoid the message box that pops up to report the result, prepend "-silent": | |
154 > | |
155 gvim -silent -register | |
156 gvim -silent -unregister | |
157 | |
158 ============================================================================== | |
159 5. MS Visual Studio integration *MSVisualStudio* *VisVim* | |
160 | |
161 The OLE version can be used to run Vim as the editor in Microsoft Visual | |
162 Studio. This is called "VisVim". It is included in the archive that contains | |
163 the OLE version. The documentation can be found in the runtime directory, the | |
164 README_VisVim.txt file. | |
165 | |
36 | 166 |
167 Using Vim with Visual Studio .Net~ | |
168 | |
169 With .Net you no longer really need VisVim, since .Net studio has support for | |
170 external editors. Follow these directions: | |
171 | |
172 In .Net Studio choose from the menu Tools->External Tools... | |
173 Add | |
174 Title - Vim | |
175 Command - c:\vim\vim63\gvim.exe | |
856 | 176 Arguments - --servername VS_NET --remote-silent "+call cursor($(CurLine), $(CurCol))" $(ItemPath) |
36 | 177 Init Dir - Empty |
178 | |
179 Now, when you open a file in .Net, you can choose from the .Net menu: | |
180 Tools->Vim | |
181 | |
182 That will open the file in Vim. | |
183 You can then add this external command as an icon and place it anywhere you | |
184 like. You might also be able to set this as your default editor. | |
185 | |
186 If you refine this further, please post back to the Vim maillist so we have a | |
187 record of it. | |
188 | |
856 | 189 --servername VS_NET |
36 | 190 This will create a new instance of vim called VS_NET. So if you open multiple |
191 files from VS, they will use the same instance of Vim. This allows you to | |
192 have multiple copies of Vim running, but you can control which one has VS | |
193 files in it. | |
194 | |
856 | 195 --remote-silent "+call cursor(10, 27)" |
196 - Places the cursor on line 10 column 27 | |
36 | 197 In Vim > |
6530 | 198 :h --remote-silent for more details |
36 | 199 |
200 [.Net remarks provided by Dave Fishburn and Brian Sturk] | |
201 | |
7 | 202 ============================================================================== |
14421 | 203 vim:tw=78:ts=8:noet:ft=help:norl: |