1VisVile -- Developer Studio Support version 9.8 2----------------------------------- ----------- 3 4 VisVile -- Developer Studio Support 5 6 Within a limited context, winvile may be substituted as the default 7 Developer Studio editor. 8 9 10Preconditions 11------------- 12 * You must be using Developer Studio version 5 (or later), which exposes 13 OLE automation "hooks" that permit winvile to augment and/or replace 14 the default editor. The implementation described within this document 15 will not work with earlier versions of DevStudio. 16 * Obtain or build a version of winvile that supports OLE Automation. 17 Register same. For further details, refer to the file oleauto.doc, 18 stored in the same directory as this document. When reading 19 oleauto.doc, note that: 20 * step 1 (building the editor) is optional if using pre-built 21 versions of _both_ winvile.exe and visvile.dll . 22 * step 2 (configuring the editor as a server) is mandatory, and 23 * step 3 (manipulating winvile via an automation client) is 24 described in great detail within this document :-) . 25 26 27Installation 28------------ 29 1. Obtain or build visvile.dll, a Developer Studio add-in that actually 30 invokes winvile. To build visvile, follow these steps: 31 1. First build winvile using the syntax described in oleauto.doc . 32 This is an important step, since the build process creates a file 33 called winviletlb.h that is included by visvile.dll's sources. 34 2. Use Developer Studio to open the visvile source directory as a 35 project. 36 3. Set the "active project configuration" (see the Build Menu) as 37 "VisVile - Win32 Release". 38 4. Press F7 (which builds visvile.dll in the Release subdirectory). 39 2. Copy Release/visvile.dll to a directory location of your choice. It 40 may or may not be important for the destination directory to be a 41 member of your PATH. On a Win95 host, it is not. 42 3. On a WinNT host it may be necessary to formally register visvile.dll's 43 type information in the Win32 registry (on a Win95 host it is not). 44 Type registration is accomplished like so: 45 1. login to an account with Administrator rights, 46 2. open a dos box, 47 3. cd to the destination directory chosen in step 2 above, 48 4. execute this command: 49 50 regsvr32 visvile.dll 51 52 4. Almost done :-) . Invoke Developer Studio and incorporate visvile.dll 53 as an add-in using these steps: 54 1. Invoke the add-in dialog box via these menus: 55 56 Tools 57 Customize... 58 Add-Ins and Macro Files 59 60 2. Click the Browse button and point Developer Studio at 61 visvile.dll . 62 3. Select visvile.dll (it will be registered as an add-in). 63 4. Close the Customize dialog box. 64 5. You should immediately notice a new VisVile Toolbar. Click the first 65 toolbar icon to configure VisVile (configuration options and toolbar 66 icons are discussed shortly). 67 68 That's it. Now, every time Developer Studio is invoked, visvile.dll is 69 automatically loaded as an add-in. 70 71 72Configuration Options 73--------------------- 74 +------------------------------------------------------------------------+ 75 | Option Name | Explanation | 76 |------------------------+-----------------------------------------------| 77 | Add-in enabled | VisVile causes winvile to open any new or | 78 | | existing _text_ document accessed by | 79 | | DevStudio, provided that the default editor | 80 | | doesn't already have that document open (see | 81 | | next option). | 82 |------------------------+-----------------------------------------------| 83 | Close DevStudio copy | VisVile closes DevStudio's copy of an open | 84 | of text document | text document after winvile has opened its | 85 | | copy. This feature keeps DevStudio from | 86 | | issuing a warning message each time a project | 87 | | file is modified by an external editor. If | 88 | | unchecked, winvile and the DevStudio text | 89 | | editor co-exist side by side. But see the | 90 | | Caveats section below. | 91 |------------------------+-----------------------------------------------| 92 | CWD set from opened | Winvile's current working directory is set to | 93 | document's path | match the path of any document opened by | 94 | | VisVile. | 95 |------------------------+-----------------------------------------------| 96 | Write all modified | VisVile forces winvile to flush all modified | 97 | buffers to disk prior | buffers to disk before a DevStudio build | 98 | to build | begins. Note that DevStudio (v5, at least) | 99 | | decides which files must be compiled _prior_ | 100 | | to notifying VisVile of an imminent build. | 101 | | This is arguably a DevStudio (v5) bug and it | 102 | | does diminish the usefulness of this option. | 103 | | | 104 | | One workaround is to press the build | 105 | | accelerator key (F7) twice for each build. | 106 | | The first key press builds whatever files are | 107 | | out-of-date before modified winvile buffers | 108 | | are written to disk. The second key press | 109 | | forces DevStudio to re-examine its | 110 | | dependencies and build everything affected by | 111 | | the last winvile buffer flush. | 112 | | | 113 | | Another workaround is to become accustomed to | 114 | | typing :ww within winvile prior to starting a | 115 | | DevStudio build. | 116 |------------------------+-----------------------------------------------| 117 | Build log -> errbuf if | Assuming DevStudio has been configured to | 118 | build reports | create an error log (refer to the | 119 | errs/warning | Tools->Customize->Build dialog box), then | 120 | | when the current DevStudio build reports | 121 | | errors or warnings, VisVile causes winvile to | 122 | | use the build log as its error buffer. In | 123 | | this configuration, the source code | 124 | | associated with each error/warning message | 125 | | may be directly accessed by simply typing | 126 | | ^X-^X. For a complete description of ^X-^X, | 127 | | browse vile's help and search for the string | 128 | | "error finder". | 129 |------------------------+-----------------------------------------------| 130 | Redirect selected | Winvile redirects keystrokes specified in the | 131 | Winvile keys to | "redirect-keys" mode to DevStudio. This | 132 | DevStudio | option permits, for example, a single winvile | 133 | | keystroke to start a DevStudio build, execute | 134 | | the target application, or initiate | 135 | | application debugging. More will be said | 136 | | about this option near the end of this | 137 | | document. | 138 +------------------------------------------------------------------------+ 139 140 141DevStudio Operations Affected By VisVile 142---------------------------------------- 143 When VisVile is enabled, any operation that causes DevStudio to open a 144 text file will instead/also cause winvile to open that file. Note too that 145 repeatedly pressing the F4 key within DevStudio following a failed build 146 causes winvile to be positioned at the source code line(s) triggering 147 error and/or warning messages. However, _each_ error or warning message 148 accessed via the F4 key requires a manual switch between winvile and 149 DevStudio. For that reason, the "Build log -> errbuf..." option is much 150 more convenient (no switching required). 151 152 153Toolbar Icons 154------------- 155 The first icon, bound to command name "VisVileConfigCmd", configures 156 VisVile. The second and third icons provide shortcuts for enabling and 157 disabling VisVile. Note that it makes sense to disable VisVile before 158 debugging an application (otherwise, the debugger pops up winvile whenever 159 a breakpoint is taken). These icons are bound to command names 160 "VisVileEnableCmd" and "VisVileDisableCmd", respectively. 161 162 The fourth icon, bound to command name "VisVileOpenDocCmd", forces winvile 163 to unconditionally open the text document currently visible in the default 164 text editor. This icon is often useful when VisVile is disabled. 165 166 167Keyboard Shortcuts 168------------------ 169 Use this menu hierarchy: 170 171 Tools 172 Customize... 173 Keyboard (category Add-ins) 174 175 to assign DevStudio keyboard shortcuts to any of the command names 176 mentioned in the previous section of this document. 177 178 179Don't Forget These Details 180-------------------------- 181 + DevStudio sends VisVile a "document opened" event _only_ if the affected 182 document is not currently open in the default editor. Keep this fact in 183 mind when configuring the "Close DevStudio copy of text document" option. 184 This restriction does not apply to the fourth toolbar icon. + It makes 185 sense to disable VisVile before debugging an application (otherwise, the 186 debugger pops up winvile whenever a breakpoint is taken). 187 188 189Controlling DevStudio From Winvile 190---------------------------------- 191 Initially, VisVile was created so that various DevStudio events caused 192 winvile to execute text editing commands on behalf of the IDE. In other 193 words, DevStudio controlled winvile. But given the rich interprocess 194 communication mechanisms available in the Win32 environment, it became 195 obvious that once DevStudio established an OLE connection with winvile, 196 the editor could turn the tables and manipulate its OLE client :-) . 197 198 To that end, when winvile is compiled as an OLE Automation server, a new 199 mode called "redirect-keys" is available. This mode specifies a list of 200 keystrokes that are to be redirected to DevStudio. The list must be in the 201 following format: 202 203 <keyspec>,... 204 205 where 206 207 <virt_key>:[<modifier>...]:[<action>...] 208 209 and 210 211 <virt_key> :== virtual keycode macro name Refer to the table near the end 212 sans "VK_". of this document for a list of 213 keycodes that may be redirected. 214 <modifier> :== S|C|A <-- mnemonics for shift, control, 215 alt 216 <action> :== <flush>|<switch>|<sync> 217 <Flush> :== F <-- flush all modified buffers to 218 disk prior to redirecting key 219 <Switch> :== S <-- switch focus to redirected 220 window prior to redirecting key 221 <sYnc> :== Y <-- synchronize current buffer (at 222 its current line) within the 223 DevStudio editor. Very useful 224 when setting breakpoints. 225 226 The default list looks like so: 227 228 F5::S,F10::S,F11::S,F7::F,F5:C:,F9::Y 229 230 which can be translated using this table: 231 232 KeyStoke Action Standard DevStudio ShortCut Semantics 233 F5 Switch Focus Run program under debugger 234 F10 Switch Focus Step over 235 F11 Switch Focus Step into 236 F7 Flush buffers Build application 237 Ctrl+F5 <none> Execute application 238 F9 Sync buffer Set/Remove breakpoint at DevStudio's current file 239 location. 240 241 242Augmenting Winvile Control With DevStudio Macros 243------------------------------------------------ 244 We're almost set. For example, we can now start the debugger from winvile 245 by simply pressing F5. Or, we might use winvile to position a source file 246 at a desired breakpoint location and then press F9 to actually set the 247 breakpoint in DevStudio's debugger. Neat. But wouldn't it be great if we 248 could disable VisVile before starting the debugger so that breakpoints 249 don't cause DevStudio to switch focus back to winvile? This is possible, 250 but requires an assist from a small macro (written in Visual Basic). 251 Included with the VisVile source distribution is a macro file called 252 VisVile.dsm that includes assists for the redirected F5, F7, F9, F10, and 253 F11 keys. The F5, F9, F10, and F11 macros simply disable VisVile prior to 254 executing DevStudio's DebugGo, DebugToggleBreakpoint, DebugStepOver, and 255 DebugStepInto commands, respectively. The F7 macro is a bit more 256 complicated, but each of its actions are documented. Notice that 257 VisVile.dsm doesn't include assist macros for Ctrl+F5, which makes sense, 258 because target application execution does not require disabling VisVile. 259 260 Our final configuration task, then, is to modify DevStudio so that it 261 executes Visvile.dsm's macros when the F5, F7, F9, F10, and F11 keys are 262 pressed. We want control flow established like so (using the F10 key as an 263 example): 264 265 Winvile User Presses F10 266 || 267 \/ 268 DevStudio Message Pump 269 || 270 \/ 271 Visvile.dsm's F10 Macro Executed 272 || 273 \/ 274 VisVile Disabled 275 || 276 \/ 277 DevStudio's DebugStepOver Command Executed 278 279 To achieve the desired objective, follow this recipe: 280 281 1. Navigate this menu hierarchy: Tools Customize... Add-ins and Macro 282 Files 283 2. Use the Browse button to find, open, and load visvile.dsm . 284 3. Now navigate using this menu hierarchy: 285 286 Tools 287 Customize... 288 Keyboard 289 Category 290 Macros 291 292 4. Next, use the "Commands" drop-down box to select the "F10" macro. In 293 the same dialog box context, use the "Editor" drop-down box to select 294 "Main" and then enter F10 (by pressing F10 on the keyboard) as the new 295 shortcut key. Be sure to click the Assign button or your actions will 296 be lost. 297 298 As a side effect of this sequence, the standard DevStudio F10 shortcut 299 (available from the Debug Menu) will be deleted. Finally, in the same 300 dialog box context, use the "Editor" drop-down box to select "Text" 301 and again enter F10 as a new shortcut key (and don't forget to click 302 the Assign button). 303 304 Repeat the last step for the F5, F7, F9, and F11 macros. 305 306 At this point it's probably a good idea to close DevStudio and re-invoke. 307 After checking to ensure that VisVile.dll and VisVile.dsm are still 308 installed as add-ins and also ensuring that your new shortcuts are in 309 place, test the winvile redirection feature as follows: 310 311 1. open a buildable project and enable Visvile. 312 2. configure VisVile so that the "Redirect selected Winvile keys to 313 DevStudio" option is checked. 314 3. perform some action that causes DevStudio to invoke winvile (for 315 example, double click on a filename in the file view pane). 316 4. with window focus directed to winvile, press F7. If the aforementioned 317 configuration is correct, DevStudio will begin building the selected 318 project. 319 320 If nothing happens when the F7 key is pressed, chances are good that 321 DevStudio was not configured to direct the F7 key to the F7 assist macro 322 for both the "Main" and "Text" editors. 323 324 325Uninstalling VisVile 326-------------------- 327 1. Invoke Developer Studio, invoke the Add-Ins and Macro Files dialog 328 box, and uncheck "Winvile Developer Studio Add-In". 329 2. If it was necessary to register visvile.dll's type information, open a 330 dos box, cd to the destination directory chosen in installation step 2 331 above, and execute this command: regsvr32 -unregister visvile.dll . 332 333 334Redirectable Virtual Keycode Names (sans VK_ prefix) 335---------------------------------------------------- 336 BACK /* backspace */ 337 TAB 338 PAUSE 339 SPACE 340 PRIOR 341 NEXT 342 END 343 HOME 344 LEFT 345 UP 346 RIGHT 347 DOWN 348 SNAPSHOT /* print screen */ 349 INSERT 350 DELETE 351 0-9 /* taken from VK_0, VK_1, etc. */ 352 A-Z /* taken from VK_A, VK_B, etc. */ 353 APPS /* properties key (Win95 kybd) */ 354 MULTIPLY /* keypad */ 355 ADD /* keypad */ 356 SUBTRACT /* keypad */ 357 DECIMAL /* keypad */ 358 DIVIDE /* keypad */ 359 F1-F24 /* taken from VK_F1, VK_F2, etc. */ 360 NUMLOCK 361 SCROLL 362 363 364Known Differences Between VisVile and VisVim 365-------------------------------------------- 366 Unique to VisVile: 367 368 * Context-sensitive configuration dialog box. 369 * "Write all modified buffers to disk prior to build" option. 370 * "Build log -> errbuf if build reports errs/warnings" option. 371 * "Redirect selected Winvile keys to DevStudio" option. 372 * When winvile is in insert mode, visvile forces the editor to command 373 mode before sending command strings. 374 * Synchronization of winvile's current buffer with DevStudio's editor. 375 376 Unique to VisVim: 377 378 * "CWD set to opened document's parent directory" option 379 380 381Copyright And Acknowledgments 382----------------------------- 383 Copyright (c) 1998-2002 Clark Morgan 384 385 VisVile is based upon VisVim, written by Heiko Erhardt (Copyright (c) 1997 386 Heiko Erhardt). VisVim is based upon VisEmacs, written by Christopher 387 Payne (Copyright (c) Christopher Payne 1997). 388 389 VisVile is free software; you can redistribute it and/or modify it under 390 the terms of the GNU General Public License as published by the Free 391 Software Foundation; either version 2, or (at your option) any later 392 version. 393 394 VisVile is distributed in the hope that it will be useful, but WITHOUT ANY 395 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 396 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 397 details. 398 399-- (generated by make-hlp.pl from visvile.html(1.12)) 400-- vile:txtmode fillcol=78 401-- $Id: visvile.doc,v 1.21 2020/01/18 01:58:44 tom Exp $ 402