share/vim/vim58/doc/if_ole.txt

   1 *if_ole.txt*    For Vim version 5.8.  Last change: 2000 Mar 21
   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
  15 {Vi does not have any of these commands}
  16
  17 OLE is only available when compiled with the |+ole| feature.  See
  18 src/if_ole.INSTALL.
  19
  20 ==============================================================================
  21 1. Activation                                           *ole-activation*
  22
  23 Vim acts as an OLE automation server, accessible from any automation client,
  24 for example, Visual Basic, Python, or Perl. The Vim application "name" (its
  25 "ProgID", in OLE terminology) is "Vim.Application".
  26
  27 Hence, in order to start a Vim instance (or connect to an already running
  28 instance), code similar to the following should be used:
  29
  30 [Visual Basic]
  31 >       Dim Vim As Object
  32 >       Set Vim = CreateObject("Vim.Application")
  33
  34 [Python]
  35 >       from win32com.client.dynamic import Dispatch
  36 >       vim = Dispatch('Vim.Application')
  37
  38 [Perl]
  39 >       use Win32::OLE;
  40 >       $vim = new Win32::OLE 'Vim.Application';
  41
  42 Vim does not support acting as a "hidden" OLE server, like some other OLE
  43 Automation servers. When a client starts up an instance of Vim, that instance
  44 is immediately visible. Simply closing the OLE connection to the Vim instance
  45 is not enough to shut down the Vim instance - it is necessary to explicitly
  46 execute a quit command (for example, :qa!, :wqa).
  47
  48 ==============================================================================
  49 2. Methods                                              *ole-methods*
  50
  51 Vim exposes three methods for use by clients.
  52
  53                                                         *ole-sendkeys*
  54 SendKeys(keys)          Execute a series of keys.
  55
  56 This method takes a single parameter, which is a string of keystrokes. These
  57 keystrokes are executed exactly as if they had been types in at the keyboard.
  58 Special keys can be given using their <..> names, as for the right hand side
  59 of a mapping. Note: Execution of the Ex "normal" command is not supported -
  60 see below |ole-normal|.
  61
  62 Examples (Visual Basic syntax)
  63 >       Vim.SendKeys "ihello<Esc>"
  64 >       Vim.SendKeys "ma1GV4jy`a"
  65
  66 These examples assume that Vim starts in Normal mode. To force Normal mode,
  67 start the key sequence with CTRL-\ CTRL-N as in
  68
  69 >       Vim.SendKeys "<C-\><C-N>ihello<Esc>"
  70
  71 CTRL-\ CTRL-N returns Vim to Normal mode, when in Insert or Command-line mode.
  72 Note that this doesn't work halfway a Vim command
  73
  74                                                         *ole-eval*
  75 Eval(expr)              Evaluate an expression.
  76
  77 This method takes a single parameter, which is an expression in Vim's normal
  78 format (see |expression|).  It returns a string, which is the result of
  79 evaluating the expression.
  80
  81 Examples (Visual Basic syntax)
  82 >       Line20 = Vim.Eval("getline(20)")
  83 >       Twelve = Vim.Eval("6 + 6")              ' Note this is a STRING
  84 >       Font = Vim.Eval("&guifont")
  85
  86                                                         *ole-setforeground*
  87 SetForeground()         Make the Vim window come to the foreground
  88
  89 This method takes no arguments.  No value is returned.
  90
  91 Example (Visual Basic syntax)
  92 >       Vim.SetForeground
  93
  94 ==============================================================================
  95 3. The "normal" command                                 *ole-normal*
  96
  97 Due to the way Vim processes OLE Automation commands, combined with the method
  98 of implementation of the ex command :normal, it is not possible to execute the
  99 :normal command via OLE automation. Any attempt to do so will fail, probably
 100 harmlessly, although possibly in unpredictable ways.
 101
 102 There is currently no practical way to trap this situation, and users must
 103 simply be aware of the limitation.
 104 ==============================================================================
 105 4. Registration                                         *ole-registration*
 106
 107 Before Vim will act as an OLE server, it must be registered in the system
 108 registry. In order to do this, Vim should be run with a single parameter of
 109 "-register".
 110
 111 >       gvim -register
 112
 113 Once vim is registered, the application path is stored in the registry. Before
 114 moving, deleting, or upgrading Vim, the registry entries should be removed
 115 using the "-unregister" switch.
 116
 117 >       gvim -unregister
 118
 119 The OLE mechanism will use the first registered Vim it finds.  If a Vim is
 120 already running, this one will be used.  If you want to have (several) Vim
 121 sessions open that should not react to OLE commands, use the non-OLE version,
 122 and put it in a different directory.  The OLE version should then be put in a
 123 directory that is not in your normal path, so that typing "gvim" will start
 124 the non-OLE version.
 125
 126 ==============================================================================
 127 5. MS Visual Studio integration                 *MSVisualStudio* *VisVim*
 128
 129 The OLE version can be used to run Vim as the editor in Microsoft Visual
 130 Studio.  This is called "VisVim".  It is included in the archive that contains
 131 the OLE version.  The documentation can be found in the VisVim directory, the
 132 README.txt file.
 133
 134 ==============================================================================
 135  vim:tw=78:ts=8:sw=8: