1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
$Id: oleauto.html,v 1.7 2010/01/03 13:54:51 tom Exp $
-->
<HTML>
<HEAD>
<TITLE>
OLE Automation Support
</TITLE>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rev="made" href="mailto:dickey@invisible-island.net">
<link rel="SHORTCUT ICON" href="/img/icons/vile.ico" type="image/x-icon">
</HEAD>
<BODY>
<h1 id="toplevel-id"><a name="toplevel">OLE Automation Support</a></h1>
Winvile can be built and configured to execute as an OLE Automation server.
The following steps are required:
<ol>
<li>build a version of winvile that supports OLE,
<li>configure winvile as a server, and
<li>use an OLE automation client to invoke and manipulate winvile.
</ol>
<h2 id="building-id"><a name="building">Build Syntax</a></h2>
<p>
By default, winvile is _not_ built with OLE Automation enabled, but this
command adds that feature:
<pre>
nmake -f makefile.wnt CFG=winvile OPT=ole-auto
</pre><p>
Or, if an embedded perl support is desired, use this syntax:
<pre>
nmake -f makefile.wnt CFG=winvile-with-perl OPT=ole-auto
</pre>
<h2 id="minimalcfg-id"><a name="minimalcfg">Minimal Configuration</a></h2>
<p>
OLE Automation support is not available until the Windows registry has been
updated with various configuration information. The simplest method of
registration is to:
<ol>
<li>copy winvile.exe to some directory in your PATH, and then
<li>execute this command:
<pre>
winvile -Or
</pre>
</ol>
<p>
The second step registers winvile as an OLE automation server that will be launched
(by a client) with _no_ command line options, which implies these server
attributes:
<ul>
<li>editor geometry is 24 rows by 80 columns
<li>default font is "system fixed", 12-point (crayola-sized :-) )
<li>editor visible
<li>a single server instance (i.e., no matter how many clients create a
winvile server object, there will be at most one server instance).
</ul>
<p>
There are, however, a number of command line options that can be specified
during registration and which subsequently affect the launched winvile
server.
<h2 id="registryopts-id"><a name="registryopts">Registration Options</a></h2>
<p>
The complete registration syntax is:
<pre>
winvile -Or [-geometry <cols>x<rows>] [-multiple] [-invisible]
[{-font|-fn} <font_spec>]
</pre><p>
where:
<table border="0" summary="Registration Options">
<colgroup><col width="200px"></colgroup>
<tr><td valign="top">-geometry <cols>x<rows></td><td>specifies the editor's window geometry.</td></tr>
<tr><td valign="top">-invisible</td><td>launched server(s) are invisible and must be
made visible via the application's Visible
property.</td></tr>
<tr><td valign="top">-multiple</td><td>each client creates a new, unique server
instance.</td></tr>
<tr><td valign="top">-font <font_spec></td><td>specifies the editor's font</td></tr>
</table>
<p>
where:
<pre>
<font_spec> :== [<face>,]<size>[,<style>]
<face> :== font-name
<size> :== point size (as an integer)
<style> :== { bold | italic | bold-italic }
</pre>
<table border="0" summary="Registration Options">
<colgroup><col width="60px"></colgroup>
<tr><td valign="top">Note 1:</td>
<td>if <style> is unspecified, "normal" is assumed.</td></tr>
<tr><td valign="top">Note 2:</td>
<td>if <face> contains a comma escape it with '\'.</td></tr>
<tr><td valign="top">Note 3:</td>
<td>if <face> is omitted, the current font is modified.</td></tr>
<tr><td valign="top">Note 4:</td>
<td>if <face> contains spaces, delimit <font_spec> as appropriate
for the current shell/desktop environment.</td></tr>
<tr><td valign="top">Note 5:</td>
<td><face> must be fixed pitch. To obtain a list of all fixed
pitch fonts on the current win32 host, invoke winvile and
browse the "Font" dialog box accessible from the System menu
(accelerator key is ALT+<space bar>+F).</td></tr>
</table>
<pre>
Example: -font 'Letter Gothic,8'
Example: -fn r_ansi,8,bold
</pre><p>
Note that it's generally not necessary to specify the font or geometry when
registering winvile because those parameters may be set in the vile startup
file (vile.rc). See the vile help topic "Win32 specifics" for further
information.
<h2 id="example-id"><a name="example">Example Automation Client Access</a></h2>
<p>
Perl Access
<!--{{atr2html--><p style="font-family: monospace;">
<strong><font color="#000080">use</font></strong> Win32::OLE;<br>
<font color="#008080">$vile</font> = new Win32::OLE <font color="#800080">'Winvile.Application'</font>;<br>
<font color="#008080">$vile</font>->VileKeys(<font color="#800080">":show-bindings\n"</font>);<br>
<font color="#008080">$vile</font>->{Visible} = <strong><font color="#008080">1</font></strong>; <font color="#800000"># may not be necessary</font><br>
<strong><font color="#000080">print</font></strong> <font color="#800080">"sleeping for 3 seconds\n"</font>;<br>
<strong><font color="#000080">sleep</font></strong>(<strong><font color="#008080">3</font></strong>);<br>
<font color="#008080">$vile</font>->VileKeys(<font color="#800080">":buffer [unnamed]\n"</font>);<br>
<font color="#008080">$vile</font>->VileKeys(<font color="#800080">":r c:/config.sys\n"</font>);<br>
<strong><font color="#000080">sleep</font></strong>(<strong><font color="#008080">3</font></strong>);<br>
<strong><font color="#000080">print</font></strong> <font color="#800080">"killing vile\n"</font>;<br>
<font color="#008080">$vile</font>->Quit();<br>
<strong><font color="#000080">exit</font></strong><br>
<!--atr2html}}--></p>
VB Access
<!--{{atr2html--><p style="font-family: monospace;">
<strong><font color="#000080">Private</font></strong> VileObj <strong><font color="#000080">As</font></strong> Winvile.Application<br>
<br>
<strong><font color="#000080">Private</font></strong> <strong><font color="#000080">Sub</font></strong> Form_Load()<br>
<strong><font color="#000080">Set</font></strong> VileObj = <strong><font color="#000080">New</font></strong> Winvile.Application<br>
VileObj.Visible = <strong><font color="#008080">True</font></strong> <font color="#800000">' may not be necessary</font><br>
VileObj.VileKeys (<font color="#800080">":help"</font> + vbLf)<br>
<strong><font color="#000080">End</font></strong> <strong><font color="#000080">Sub</font></strong><br>
<br>
<strong><font color="#000080">Private</font></strong> <strong><font color="#000080">Sub</font></strong> Quit_Click()<br>
VileObj.Quit <font color="#800000">' Kill the server (winvile)</font><br>
<strong><font color="#000080">End</font></strong><br>
<strong><font color="#000080">End</font></strong> <strong><font color="#000080">Sub</font></strong><br>
<!--atr2html}}--></p>
<h2 id="winvilewrapper-id"><a name="winvilewrapper">wvwrap.exe -- WinVile WRAPper</a></h2>
<p>
[ Note: Ed Henderson discovered this novel use of automation and
wrote the original version of wvwrap.exe . Thanks, Ed! ]
<h2 id="wvwrapbkg-id"><a name="wvwrapbkg">Background</a></h2>
<p>
It's possible to modify the Windows registry such that any arbitrary
utility appears on the Windows Explorer right mouse popup menu. To do so,
use regedit to create the following entry in the registry:
<pre>
HKEY_CLASSES_ROOT\*\shell\<utility_name>\command
</pre><p>
Example:
<pre>
HKEY_CLASSES_ROOT\*\shell\winvile\command
</pre><p>
Next, give the "command" key the following (Default) value:
<pre>
<utility_name> "%1"
</pre><p>
An actual example:
<pre>
HKEY_CLASSES_ROOT\*\shell\winvile\command\winvile "%1"
</pre><p>
Once this registry entry is installed, then anytime the right mouse button
is clicked on a file in Windows Explorer, "winvile" appears as a selection
at the top of the popup menu. Choosing winvile from this menu launches the
editor, which then opens the selected file. So far, so good. However,
when multiple files are selected and winvile is launched via a right mouse
click, Windows Explorer opens one instance of the editor per selected file.
Most vile-aholics will find this behavior rather repugnant. However, if
winvile is configured as a single server instance (the default), a
workaround exists. Read on.
<p>
When the Ole Automation version of winvile is built as described above, a
utility called wvwrap.exe is also created. Copy wvwrap to a directory in
your PATH and create the following registry entry:
<pre>
HKEY_CLASSES_ROOT\*\shell\wvwrap\command\wvwrap "%1"
</pre><p>
If using Windows XP, it's necessary to specify the full path to wvwrap,
as shown here:
<pre>
HKEY_CLASSES_ROOT\*\shell\wvwrap\command\<full_path_to>wvwrap.exe "%1"
</pre><p>
Now, as a test, select multiple files within Window Explorers, right click
the mouse, and launch wvwrap. Notice that all files are read into a
single instance of winvile, one buffer per file.
<h2 id="serverprops-id"><a name="serverprops">Server Properties And Methods</a></h2>
<table border="0" summary="Server Properties and Methods">
<colgroup><col width="200px"><col width="20px"></colgroup>
<tr><td valign="top">Application
</td><td valign="top">—
</td><td>[out] Returns the application object.</td></tr>
<tr><td valign="top">ForegroundWindow()
</td><td valign="top">—
</td><td>Makes the editor the foreground window. Note that
Windows 2000 and XP essentially emasculated this
method. See MainHwnd() for an alternative approach.</td></tr>
<tr><td valign="top">FullName
</td><td valign="top">—
</td><td>[out] Returns the path of the application.</td></tr>
<tr><td valign="top">InsertMode
</td><td valign="top">—
</td><td>[out] True if editor window with keyboard focus is
in insert mode.</td></tr>
<tr><td valign="top">IsMinimized
</td><td valign="top">—
</td><td>[out] True if editor minimized.</td></tr>
<tr><td valign="top">MainHwnd
</td><td valign="top">—
</td><td>[out] Returns the editor's main window handle.
Useful if the client wishes to, say, call
SetForegroundWindow() on behalf of the editor.</td></tr>
<tr><td valign="top">Minimize()
</td><td valign="top">—
</td><td>Minimizes the editor.</td></tr>
<tr><td valign="top">Name()
</td><td valign="top">—
</td><td>[out] Returns the name of the application.</td></tr>
<tr><td valign="top">Parent()
</td><td valign="top">—
</td><td>Returns the parent of the application object.</td></tr>
<tr><td valign="top">Quit()
</td><td valign="top">—
</td><td>Exits the editor.</td></tr>
<tr><td valign="top">Restore()
</td><td valign="top">—
</td><td>Restores the editor's window.</td></tr>
<tr><td valign="top">VileKeys([in] keys)
</td><td valign="top">—
</td><td>Sends keystrokes to the editor. Note that this method
is implemented by using PostMessage() to send a
WM_CHAR message for _each_ character in the "keys"
string. In other words, this is not an efficient
method and should not be used to create large files.</td></tr>
<tr><td valign="top">Visible
</td><td valign="top">—
</td><td>[in, out] Sets or returns the editor's visibility.</td></tr>
<tr><td valign="top">WindowRedirect([in] hwnd)
</td><td valign="top">—
</td><td>Specifies a window handle to which
user-specified keystrokes are redirected.
Redirected keystrokes are specified via winvile's
"redirect-keys" mode. Refer to the file <a href="visvile.html">visvile.doc</a>
for a detailed discussion of this method and its
associated mode.
<p>
To disable redirection once enabled, pass this method a
NULL window handle.</td></tr>
</table>
<p>
Note: ForegroundWindow(), Minimize(), and Restore() implicitly force an
Invisible server to the Visible state.
<h2 id="unregistering-id"><a name="unregistering">Unregistering The Server</a></h2>
<p>
To unregister winvile as an OLE automation server, execute this command:
<pre>
winvile -Ou
</pre>
<h2 id="credits-id"><a name="credits">Credits</a></h2>
The OLE automation support for winvile was written by Clark Morgan,
from 1998 to 2005.
|
