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