ImageComparison Object

This object represents an image comparison window. The window isn’t necessarily visible on screen and can be used either to perform file comparison services for a client, or to present file comparisons on the screen to the user.

Use the methods and properties exposed by this object to perform image file comparisons, and to alter the appearance of an image file comparison window.

Properties (implemented by interface ICommonUI)

Active

IDL	`[propget] HRESULT Active([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT Active([in] VARIANT_BOOL newValue)`
.NET	`Boolean Active[get, set]`
VB6	`Active As Boolean`

The active state of the comparison window.

The property is read/write.

Height

IDL	`[propget] HRESULT Height([out, retval] long* pValue) [propput] HRESULT Height([in] long newValue)`
.NET	`Int32 Height[get, set]`
VB6	`Height As Long`

The height of the comparison window in pixels.

The property is read/write.

Left

IDL	`[propget] HRESULT Left([out, retval] long* pValue) [propput] HRESULT Left([in] long newValue)`
.NET	`Int32 Left[get, set]`
VB6	`Left As Long`

The location of the left edge pixel coordinate of the comparison window.

The property is read/write.

Maximized

IDL	`[propget] HRESULT Maximized([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT Maximized([in] VARIANT_BOOL newValue)`
.NET	`Boolean Maximized[get, set]`
VB6	`Maximized As Boolean`

The maximized state of the comparison window.

The property is read/write.

Minimized

IDL	`[propget] HRESULT Minimized([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT Minimized([in] VARIANT_BOOL newValue)`
.NET	`Boolean Minimized[get, set]`
VB6	`Minimized As Boolean`

The minimized state of the comparison window.

The property is read/write.

Top

IDL	`[propget] HRESULT Top([out, retval] long* pValue) [propput] HRESULT Top([in] long newValue)`
.NET	`Int32 Top[get, set]`
VB6	`Top As Long`

The location of the top edge pixel coordinate of the comparison window.

The property is read/write.

Visible

IDL	`[propget] HRESULT Visible([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT Visible([in] VARIANT_BOOL newValue)`
.NET	`Boolean Visible[get, set]`
VB6	`Visible As Boolean`

The visible state of the comparison window.

The property is read/write.

Width

IDL	`[propget] HRESULT Width([out, retval] long* pValue) [propput] HRESULT Width([in] long newValue)`
.NET	`Int32 Width[get, set]`
VB6	`Width As Long`

The width of the comparison window in pixels.

The property is read/write.

Properties (implemented by interface IComparison)

ViewType

IDL	`[propget] HRESULT ViewType([out, retval] FileViewType* pValue) [propput] HRESULT ViewType([in] FileViewType newValue)`
.NET	`FileViewType ViewType[get, set]`
VB6	`ViewType As FileViewType`

The comparison type (two way or three way layout).

The property is read/write.

Properties (implemented by interface IFileComparison)

AllUnresolvedConflicts

IDL	`[propget] HRESULT AllUnresolvedConflicts([out, retval] long* pValue)`
.NET	`Int32 AllUnresolvedConflicts[get]`
VB6	`AllUnresolvedConflicts As Long`

Not currently used.

The property is read-only.

AutoSaveOnClose

IDL	`[propget] HRESULT AutoSaveOnClose([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT AutoSaveOnClose([in] VARIANT_BOOL newValue)`
.NET	`Boolean AutoSaveOnClose[get, set]`
VB6	`AutoSaveOnClose As Boolean`

Not currently used.

The property is read/write.

ComparisonError

IDL	`[propget] HRESULT ComparisonError([in, optional] VARIANT nFilePair, [out, retval] FileComparisonError* pValue)`
.NET	`FileComparisonError get_ComparisonError(Object nFilePair)`
VB6	`ComparisonError( [nFilePair As Variant]) As FileComparisonError`

The error (if any) that was encountered by the Compare method.

The property is read-only.

Arguments

nFilePair [optional]
Specifies whether to return results for files 0 and 1 (when nFilePair = 0 [default]) or files 1 and 2 (when nFilePair = 1).

ComparisonResult

IDL	`[propget] HRESULT ComparisonResult([in, optional] VARIANT nFilePair, [out, retval] FileComparisonResult* pValue)`
.NET	`FileComparisonResult get_ComparisonResult(Object nFilePair)`
VB6	`ComparisonResult( [nFilePair As Variant]) As FileComparisonResult`

The result (fcrSame, fcrDifferent, fcrError) of the comparison performed by the Compare method.

The property is read-only.

Arguments

nFilePair [optional]
Specifies whether to return results for files 0 and 1 (when nFilePair = 0 [default]) or files 1 and 2 (when nFilePair = 1).

ErrorInfo

IDL	`[propget] HRESULT ErrorInfo([in] short nFile, [out, retval] BSTR* pValue) [propput] HRESULT ErrorInfo([in] short nFile, [in] BSTR newValue)`
.NET	`String get_ErrorInfo(Int16 nFile) void set_ErrorInfo(Int16 nFile, String newValue)`
VB6	`ErrorInfo(nFile As Integer) As String`

Provides detailed information about errors encountered while loading/comparing one of the files. If nFile is -1, then errors that applied to all three files (for example, out of memory errors) are returned.

The property is read/write.

Arguments

nFile
The file (0, 1, or 2) to get error information for. A value of -1 can also be specified to denote all files.

Modified

IDL	`[propget] HRESULT Modified([in] short nFile, [out, retval] VARIANT_BOOL* pValue) [propput] HRESULT Modified([in] short nFile, [in] VARIANT_BOOL newValue)`
.NET	`Boolean get_Modified(Int16 nFile) void set_Modified(Int16 nFile, Boolean newValue)`
VB6	`Modified(nFile As Integer) As Boolean`

Not currently used.

The property is read/write.

Arguments

nFile

NumberOfChanges

IDL	`[propget] HRESULT NumberOfChanges([in, optional] VARIANT nFilePair, [out, retval] long* pValue)`
.NET	`Int32 get_NumberOfChanges(Object nFilePair)`
VB6	`NumberOfChanges( [nFilePair As Variant]) As Long`

The number of pixels that have changed between the two images. A changed pixel in a given location in both images counts as one change. Inserted and removed pixels (resulting from different image sizes) count as one change each.

The property is read-only.

Arguments

nFilePair [optional]
Specifies whether to return the number of changes between files 0 and 1 (when nFilePair = 0 [default]) or files 1 and 2 (when nFilePair = 1).

PromptForUnsavedFiles

IDL	`[propget] HRESULT PromptForUnsavedFiles([out, retval] VARIANT_BOOL* pValue) [propput] HRESULT PromptForUnsavedFiles([in] VARIANT_BOOL newValue)`
.NET	`Boolean PromptForUnsavedFiles[get, set]`
VB6	`PromptForUnsavedFiles As Boolean`

Not currently used.

The property is read/write.

ReadOnly

IDL	`[propget] HRESULT ReadOnly([in] short nFile, [out, retval] VARIANT_BOOL* pValue) [propput] HRESULT ReadOnly([in] short nFile, [in] VARIANT_BOOL newValue)`
.NET	`Boolean get_ReadOnly(Int16 nFile) void set_ReadOnly(Int16 nFile, Boolean newValue)`
VB6	`ReadOnly(nFile As Integer) As Boolean`

Not currently used.

The property is read/write.

Arguments

nFile

SaveFileName

IDL	`[propget] HRESULT SaveFileName([out, retval] BSTR* pValue) [propput] HRESULT SaveFileName([in] BSTR newValue)`
.NET	`String SaveFileName[get, set]`
VB6	`SaveFileName As String`

Not currently used.

The property is read/write.

ThreeWayMergeActions

IDL	`[propget] HRESULT ThreeWayMergeActions([out, retval] IThreeWayMergeActions** pValue)`
.NET	`ThreeWayMergeActions ThreeWayMergeActions[get]`
VB6	`ThreeWayMergeActions As ThreeWayMergeActions`

Not currently used.

The property is read-only.

UnresolvedConflicts

IDL	`[propget] HRESULT UnresolvedConflicts([in] short nFile, [out, retval] long* pValue)`
.NET	`Int32 get_UnresolvedConflicts(Int16 nFile)`
VB6	`UnresolvedConflicts(nFile As Integer) As Long`

Not currently used.

The property is read-only.

Arguments

nFile

Properties (implemented by interface IImageComparison)

Methods (implemented by interface ICommonUI)

Close

IDL	`HRESULT Close()`
.NET	`void Close()`
VB6	`Close`

Closes the comparison window.

GiveUserControl

IDL	`HRESULT GiveUserControl()`
.NET	`void GiveUserControl()`
VB6	`GiveUserControl`

Gives control over the lifetime of the comparison window to the user. Merge will not automatically close the window when outstanding automation references are released.

Restore

IDL	`HRESULT Restore()`
.NET	`void Restore()`
VB6	`Restore`

Restores the comparison window from minimized or maximised state to its normal resizable state.

Methods (implemented by interface IComparison)

Compare

IDL	`HRESULT Compare([in] VARIANT strFirstFile, [in] VARIANT strSecondFile, [in, optional] VARIANT strThirdFile)`
.NET	`void Compare(Object strFirstFile, Object strSecondFile, Object strThirdFile)`
VB6	`Compare(strFirstFile As Variant, strSecondFile As Variant [, strThirdFile As Variant])`

Compares two or three files. This method is synchronous. An event ComparisonComplete is fired when the comparison is finished to report errors and results.

Arguments

strFirstFile
The fully qualified path to the first file
strSecondFile
The fully qualified path to the second file
strThirdFile [optional]
The fully qualified path to the third file

Print

IDL	`HRESULT Print([in] VARIANT_BOOL bShowPrinterDialog, [in] PageOrientation nOrientation)`
.NET	`void Print(Boolean bShowPrinterDialog, PageOrientation nOrientation)`
VB6	`Print(bShowPrinterDialog As Boolean, nOrientation As PageOrientation)`

Prints the file comparison.

Arguments

bShowPrinterDialog
Defaults to FALSE. Whether to show the printer dialog to the user before printing.
nOrientation
Defaults to poLandscape. Whether to print in portrait or landscape mode.

Refresh

IDL	`HRESULT Refresh()`
.NET	`void Refresh()`
VB6	`Refresh`

Recompares the files displayed in the window. This will cause any unsaved changes to be discarded.

Report

IDL	`HRESULT Report([in] BSTR bstrReporter, [in] LineEndingStyle nLineEndingStyle, [in] BSTR strOutputFile)`
.NET	`void Report(String bstrReporter, LineEndingStyle nLineEndingStyle, String strOutputFile)`
VB6	`Report(bstrReporter As String, nLineEndingStyle As LineEndingStyle, strOutputFile As String)`

This method is not currently used.

Arguments

bstrReporter
nLineEndingStyle
strOutputFile

Report2

IDL	`HRESULT Report2([in] BSTR bstrReporter, [in] LineEndingStyle nLineEndingStyle, [in] VARIANT vtEncoding, [in] BSTR strOutputFile)`
.NET	`void Report2(String bstrReporter, LineEndingStyle nLineEndingStyle, Object vtEncoding, String strOutputFile)`
VB6	`Report2(bstrReporter As String, nLineEndingStyle As LineEndingStyle, vtEncoding As Variant, strOutputFile As String)`

This method is not currently used.

Arguments

bstrReporter
nLineEndingStyle
vtEncoding
strOutputFile

SaveComparison

IDL	`HRESULT SaveComparison([in] BSTR filename)`
.NET	`void SaveComparison(String filename)`
VB6	`SaveComparison(filename As String)`

Saves the comparison to a file. We recommend that you use the .cmp7 extension in the filename.

Arguments

filename
The name of the file to which the comparison should be saved.

SetPanelTitles

IDL	`HRESULT SetPanelTitles([in] VARIANT strFirst, [in] VARIANT strSecond, [in, optional] VARIANT strThird)`
.NET	`void SetPanelTitles(Object strFirst, Object strSecond, Object strThird)`
VB6	`SetPanelTitles(strFirst As Variant, strSecond As Variant [, strThird As Variant])`

Sets the titles shown above the file panels.

Arguments

strFirst
The title for the first file panel.
strSecond
The title for the second file panel.
strThird [optional]
The title for the third file panel.

Methods (implemented by interface IFileComparison)

CompareAsync

IDL	`HRESULT CompareAsync([in] VARIANT strFirstFile, [in] VARIANT strSecondFile, [in, optional] VARIANT strThirdFile)`
.NET	`void CompareAsync(Object strFirstFile, Object strSecondFile, Object strThirdFile)`
VB6	`CompareAsync(strFirstFile As Variant, strSecondFile As Variant [, strThirdFile As Variant])`

Compares two or three files. This method is asynchronous (returns before the comparison completes). An event ComparisonComplete is fired when the comparison is finished to report errors and results.

Arguments

strFirstFile
The fully qualified path to the first file
strSecondFile
The fully qualified path to the second file
strThirdFile [optional]
The fully qualified path to the third file

SaveFile

IDL	`HRESULT SaveFile([in] short nFile, [in, optional] VARIANT strSaveTo)`
.NET	`void SaveFile(Int16 nFile, Object strSaveTo)`
VB6	`SaveFile(nFile As Integer [, strSaveTo As Variant])`

Not currently used.

Arguments

nFile
strSaveTo [optional]

SaveFileAs

IDL	`HRESULT SaveFileAs([in] short nFile)`
.NET	`void SaveFileAs(Int16 nFile)`
VB6	`SaveFileAs(nFile As Integer)`

Not currently used.

Arguments

nFile

ThreeWayMerge

IDL	`HRESULT ThreeWayMerge([out, retval] long* pValue)`
.NET	`Int32 ThreeWayMerge()`
VB6	`ThreeWayMerge As Long`

Not currently used.

Methods (implemented by interface IImageComparison)

Events (implemented by interface IFileComparisonEvents)

Close

IDL	`HRESULT Close()`
.NET	`void Close()`
VB6	`Close`

The file comparison window was closed by the user.

ComparisonComplete

IDL	`HRESULT ComparisonComplete([in] FileComparisonError error1, [in] FileComparisonResult result1, [in, optional] FileComparisonError error2, [in, optional] FileComparisonResult result2)`
.NET	`void ComparisonComplete(FileComparisonError error1, FileComparisonResult result1, FileComparisonError error2, FileComparisonResult result2)`
VB6	`ComparisonComplete(error1 As FileComparisonError, result1 As FileComparisonResult [, error2 As FileComparisonError] [, result2 As FileComparisonResult])`

Occurs when a file comparison completes. For comparisons between two files, only the first two arguments are defined. For comparisons between three files, all four arguments are defined.

Arguments

error1
The error, if any, that occurred during the comparison of the first and second files.
result1
The result of the comparison between the first and second files.
error2 [optional]
The error, if any, that occurred during the comparison of the second and third files.
result2 [optional]
The result of the comparison between the second and third files.

Related topics
Automation API