Plugins use an ActiveX interface. Plugins may be written in any format that supports this interface.
Examples are available in :
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).
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 :
PACK_UNPACK
Transform a file in a viewable format (for example, decompress a file...)
Some events have two API. One to exchange the data through a BSTR
(memory) and one through input/ouput files.
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.
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 :
PluginIsAutomatic
is false
, the plugin is never used in automatic mode.PluginIsAutomatic
is true
, PluginFileFilters
is compared to the filename of both files. If one file
matches the filter, the plugin is applied.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.
PluginEvent
C++ | STDMETHODIMP CWinMergeScript::get_PluginEvent(BSTR * pVal) |
---|---|
VB | Public Property Get PluginEvent() As String |
VBS | Function get_PluginEvent() |
PluginDescription
C++ | STDMETHODIMP CWinMergeScript::get_PluginDescription(BSTR * pVal) |
---|---|
VB | Public Property Get PluginDescription() As String |
VBS | Function get_PluginDescription() |
PluginFileFilters
String formed of fileFilters, separated with ";
"
C++ | STDMETHODIMP CWinMergeScript::get_PluginFileFilters(BSTR * pVal) |
---|---|
VB | Public Property Get PluginFileFilters() As String |
PluginIsAutomatic
C++ | STDMETHODIMP CWinMergeScript::get_PluginIsAutomatic(VARIANT_BOOL * pVal) |
---|---|
VB | Public Property Get PluginIsAutomatic() As Boolean |
EDITOR_SCRIPT
Functions parameters (function names are free) | |
---|---|
C++ | STDMETHOD(MakeUpperVB)([in] BSTR inputText, [out, retval] BSTR * outputText); |
VB | Public Function MakeUpperVB(text As String) |
VBS | Function MakeUpperVBS(Text) |
FILE_PREDIFF
Functions names | Functions parameters | |
---|---|---|
VC++ | STDMETHOD(PrediffFile) |
([in] BSTR fileSrc, [in] BSTR fileDst, VARIANT_BOOL * pbChanged, INT * pSubcode, [out, retval] VARIANT_BOOL * pbSuccess) |
VB | Public Function PrediffFile |
(BSTR fileSrc, BSTR fileDst, ByRef bChanged As Boolean, ByRef subcode As Long) As Boolean |
BUFFER_PREDIFF
Functions names | Functions parameters | |
---|---|---|
C++ | STDMETHOD(PrediffBufferW) |
([in] BSTR * pText, [in] INT * pSize, [in] VARIANT_BOOL * pbChanged, [out, retval] VARIANT_BOOL * pbHandled); |
VB | Public Function PrediffBufferW |
(ByRef text As String, ByRef size As Long, ByRef bChanged As Boolean) As Boolean |
FILE_PACK_UNPACK
Functions names | Functions parameters | |
---|---|---|
VC++ | STDMETHOD(UnpackFile) |
([in] BSTR fileSrc, [in] BSTR fileDst, VARIANT_BOOL * pbChanged, INT * pSubcode, [out, retval] VARIANT_BOOL * pbSuccess) |
STDMETHOD(PackFile) |
([in] BSTR fileSrc, [in] BSTR fileDst, VARIANT_BOOL * pbChanged, INT pSubcode, [out, retval] VARIANT_BOOL * pbSuccess) |
|
VB | Public Function UnpackFile |
(BSTR fileSrc, BSTR fileDst, ByRef bChanged As Boolean, ByRef subcode As Long) As Boolean |
Public Function PackFile |
(BSTR fileSrc, BSTR fileDst, ByRef bChanged As Boolean, subcode As Long) As Boolean |
BUFFER_PACK_UNPACK
Functions names | Functions parameters | |
---|---|---|
VC++ | STDMETHOD(UnpackBufferA) |
([in] SAFEARRAY ** pBuffer, [in] INT * pSize, [in] VARIANT_BOOL * pbChanged, [in] INT * pSubcode, [out, retval] VARIANT_BOOL * pbSuccess) |
STDMETHOD(PackBufferA) |
([in] SAFEARRAY ** pBuffer, [in] INT * pSize, [in] VARIANT_BOOL * pbChanged, [in] INT subcode, [out, retval] VARIANT_BOOL * pbSuccess) |
|
VB | Public Function UnpackBufferA |
(ByRef buffer() As Byte, ByRef size As Long, ByRef bChanged As Boolean, ByRef subcode As Long) As Boolean |
Public Function PackBufferA |
(ByRef buffer() As Byte, ByRef size As Long, ByRef bChanged As Boolean, subcode As Long) As Boolean |
Easiest plugins are scriptlets.
Just VBscript (or JavaScript probably) with an additional section <implement>
. See examples.
But they are difficult to debug. And valid only for EDITOR_SCRIPT
events.
The most difficult to write when you do it from scratch. See in Plugins/syntax.txt
, there are three additional steps from normal COM dll.
But easy to write from an existing plugin.
cpp,def,dsp,idl,rc
: replace [name of old plugin] with [name of your plugin]WinMergeScript.cpp
holds all the important functions..idl
file..rgs
, and the registry section in the file .rc
typeinfoex.h
+ and make 3 changes in WinMergeScript.h
(see commented lines)SAFEARRAY
: replace the interface in .idl
:
SAFEARRAY *
SAFEARRAY(unsigned char)
SAFEARRAY **
SAFEARRAY(unsigned char) *
Easy with Visual Studio after you installed WinMerge source.
EDITOR_SCRIPT
:safeInvokeA
in Plugins.cpp
.WinMergeScript.cpp
source of your plugin in the debugging session.F5
. The breakpoint in your function is triggered.PREDIFF
, PACK_UNPACK
:Same steps, point #1 only differs:
safeInvokeW
in Plugins.cpp
.safeInvokeW
instead of safeInvokeA
.