开源软件 winmerge 代码

# WinMerge Plugins This folders holds the WinMerge runtime plugins, source code and binaries both. These filters are distributed in the `MergePlugins` subdirectory beneath the WinMerge executables. ## Quick description Plugins use an ActiveX interface. Plugins may be written in any format that supports this interface. Examples are available in : * C++ COM component * VB ActiveX dll * Scriptlets (VBScript, JScript) * Delphi Limitation : Scriptlets only work for `EDITOR_SCRIPT` plugins. **Properties** are used to present information concerning the plugin. **Methods** are used to process the data. Method names and syntax depends on events and **API** (see below). ## Events ### `EDITOR_SCRIPT` In editor view, apply a function to the current selection. ### `PREDIFF` Preprocess file before diffing : the plugin is not apply to the text displayed in the editor. It is applied only to a copy of the left and right texts, and this copy are then scanned to create the difference list. As now: * you may delete one column, change the names of variables... * you may not add/delete/move lines. ### `PACK_UNPACK` Transform a file in a viewable format (for example, decompress a file...) * The editor displays the unpacked data. * Sometimes files may be packed again (zipped files...). An additional function is of course necessary. * If the author of the plugin created this function, file may be saved again in the compressed format. * Else the file can only be saved in a text format. To avoid problems, you are proposed to change the filename when saving a changed file. ## API Some events have two API. One to exchange the data through a `BSTR` (memory) and one through input/ouput files. | Event | Data exchange | |:---------------------|:---------------------------------------------------------------------------------------------------------| | `FILE_PREDIFF` | data are exchanged through an input and an output file | | `BUFFER_PREDIFF` | data are exchanged through a `BSTR` | | `FILE_PACK_UNPACK` | data are exchanged through an input and an output file | | `BUFFER_PACK_UNPACK` | data are exchanged through a `SafeArray` (`BSTR` not available as the packed data are possibly not text) | | `EDITOR_SCRIPT` | data are exchanged through a `BSTR` | You need to define only one API to handle an event. Define the one you prefer. ## Properties | Name | Mandatory | Events | |:--------------------|:----------------------------------|:-------------------------| | `PluginEvent` | yes | all | | `PluginDescription` | no | all | | `PluginFileFilters` | no | `PACK_UNPACK`, `PREDIFF` | | `PluginIsAutomatic` | if `PluginFileFilters` is defined | `PACK_UNPACK`, `PREDIFF` | `PluginIsAutomatic` and `PluginFileFilters` are for automatic mode : * When `PluginIsAutomatic` is `false`, the plugin is never used in automatic mode. * When `PluginIsAutomatic` is `true`, `PluginFileFilters` is compared to the filename of both files. If one file matches the filter, the plugin is applied. ## Methods | API | Method name | |:---------------------|:-----------------------------------------------------------------------------------------------| | `EDITOR_SCRIPT` | function name is free **Note**: several functions may be defined in one `EDITOR_SCRIPT` plugin | | `BUFFER_PREDIFF` | `PrediffBufferW` | | `FILE_PREDIFF` | `PrediffFile` | | `BUFFER_PACK_UNPACK` | `UnpackBufferA`, `PackBufferA` | | `FILE_PACK_UNPACK` | `UnpackFile`, `PackFile` | **Note**: `PACK_UNPACK` functions use an additional parameter. The value may be set during `UnpackBuffer`. When file is changed, the value is forwarded to `PackBuffer`. The goal is to pass a parameter from `UnpackBuffer` to `PackBuffer`. For example, the plugin may handle several compressed formats, and use this value to recompress a file in the format of the original. This parameter is mandatory for the function's syntax. But you don't have to set its value when you don't use it. ## Syntax ### Properties syntax #### `PluginEvent` | Language | Syntax | |:--------:|:--------------------------------------------------------------------| | C++ | `STDMETHODIMP CWinMergeScript::get_PluginEvent(BSTR * pVal)` | | VB | `Public Property Get PluginEvent() As String` | | VBScript | `Function get_PluginEvent()` | | JScript | `function get_PluginEvent()` | #### `PluginDescription` | Language | Syntax | |:--------:|:--------------------------------------------------------------------| | C++ | `STDMETHODIMP CWinMergeScript::get_PluginDescription(BSTR * pVal)` | | VB | `Public Property Get PluginDescription() As String` | | VBScript | `Function get_PluginDescription() | | JScript | `function get_PluginDescription()` | #### `PluginFileFilters` String formed of fileFilters, separated with `;` | Language | Syntax | |:--------:|:--------------------------------------------------------------------| | C++ | `STDMETHODIMP CWinMergeScript::get_PluginFileFilters(BSTR * pVal)` | | VB | `Public Property Get PluginFileFilters() As String` | | VBScript | `Function get_PluginFileFilters() | | JScript | `function get_PluginFileFilters()` | #### `PluginIsAutomatic` | Language | Syntax | |:--------:|:------------------------------------------------------------------------------| | C++ | `STDMETHODIMP CWinMergeScript::get_PluginIsAutomatic(VARIANT_BOOL * pVal)` | | VB | `Public Property Get PluginIsAutomatic() As Boolean` | | VBScript | `Function get_PluginIsAutomatic()` | | JScript | `function get_PluginIsAutomatic()` | ### Methods syntax #### `EDITOR_SCRIPT` | Language | Functions parameters (function names are free) | |:--------:|:------------------------------------------------------------------------------| | C++ | `STDMETHOD(MakeUpper)([in] BSTR inputText, [out, retval] BSTR * outputText);` | | VB | `Public Function MakeUpper(text As String)` | | VBScript | `Function MakeUpper(Text)` | | JScript | `function MakeUpper(Text)` | #### `FILE_PREDIFF` | Language | Functions names | Functions parameters | |:--------:|:-------------------