TextComparison Object

On this page:

• Description
• Properties
  • Active read/write, ICommonUI
  • AllUnresolvedConflicts read-only, IFileComparison
  • AutoSaveOnClose read/write, IFileComparison
  • ChangeLength read-only, ITextComparison
  • ChangeStartLine read-only, ITextComparison
  • ChangeType read-only, ITextComparison
  • ComparisonError read-only, IFileComparison
  • ComparisonResult read-only, IFileComparison
  • ErrorInfo read/write, IFileComparison
  • FileContent read/write, ITextComparison
  • FullLineData read-only, ITextComparison
  • FullLineLength read-only, ITextComparison
  • Height read/write, ICommonUI
  • Left read/write, ICommonUI
  • LineData read-only, ITextComparison
  • LineLength read-only, ITextComparison
  • Maximized read/write, ICommonUI
  • Minimized read/write, ICommonUI
  • Modified read/write, IFileComparison
  • NumberOfChanges read-only, IFileComparison
  • NumberOfLines read-only, ITextComparison
  • PromptForUnsavedFiles read/write, IFileComparison
  • ReadOnly read/write, IFileComparison
  • SaveFileName read/write, IFileComparison
  • ThreeWayMergeActions read-only, IFileComparison
  • Top read/write, ICommonUI
  • UnresolvedConflicts read-only, IFileComparison
  • ViewType read/write, IComparison
  • Visible read/write, ICommonUI
  • Width read/write, ICommonUI
• Methods
  • Close ICommonUI
  • Compare IComparison
  • CompareAsync IFileComparison
  • CompareAsyncWithEncoding ITextComparison2
  • CompareWithEncoding ITextComparison2
  • GiveUserControl ICommonUI
  • Print IComparison
  • Refresh IComparison
  • Report IComparison
  • Report2 IComparison
  • Restore ICommonUI
  • SaveComparison IComparison
  • SaveFile IFileComparison
  • SaveFileAs IFileComparison
  • SetPanelTitles IComparison
  • ThreeWayMerge IFileComparison
• Events
  • Close IFileComparisonEvents
  • ComparisonComplete IFileComparisonEvents

Description

This object represents a text file 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 text file comparisons, extract results, and to alter the appearance of a text file comparison window.

Once the comparison represented by this object is closed, the handler for the Close event provides the final opportunity to access methods and properties. Accessing them after this time will result in an error.

Properties

Active read/write, ICommonUI

The active state of the comparison window.

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

AllUnresolvedConflicts read-only, IFileComparison

Provides a count of the unresolved conflicts in all files in the comparison.

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

AutoSaveOnClose read/write, IFileComparison

Normally, if Merge is closed when some modified files are unsaved, it will ask the user whether those files should be saved (unless the PromptForUnsavedFiles property is set to false, in which case any unsaved files will be discarded). However, if AutoSaveOnClose is set to true, Merge will automatically save any unsaved files without prompting the user. This feature can sometimes be useful when integrating Merge with other applications.

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

ChangeLength read-only, ITextComparison

The number of lines in a change.

IDL	[propget] HRESULT ChangeLength(     [in] long nChange,     [in] long nSide,     [in, optional] VARIANT nFilePair,     [out, retval] long* pValue)
.NET	Int32 get_ChangeLength(     Int32 nChange,     Int32 nSide,     Object nFilePair)

• nChange
  Specifies the change (0 based) for which the number of contained lines is required. This value should be in the range 0 to NumberOfChanges-1.
• nSide
  Specifies the left (0) or right (1) side of the change.
• nFilePair optional
  Specifies whether to return results for files 0 and 1 (when nFilePair = 0, the default) or files 1 and 2 (when nFilePair = 1).

ChangeStartLine read-only, ITextComparison

The starting line number (0 based) of a change.

IDL	[propget] HRESULT ChangeStartLine(     [in] long nChange,     [in] long nSide,     [in, optional] VARIANT nFilePair,     [out, retval] long* pValue)
.NET	Int32 get_ChangeStartLine(     Int32 nChange,     Int32 nSide,     Object nFilePair)

• nChange
  Specifies the change (0 based) for which the starting line is required. This value should be in the range 0 to NumberOfChanges-1.
• nSide
  Specifies the left (0) or right (1) side of the change.
• nFilePair optional
  Specifies whether to return results for files 0 and 1 (when nFilePair = 0, the default) or files 1 and 2 (when nFilePair = 1).

ChangeType read-only, ITextComparison

The type of a change. A change represents a block of inserted, removed, changed, or unchanged lines.

IDL	[propget] HRESULT ChangeType(     [in] long nChange,     [in, optional] VARIANT nFilePair,     [out, retval] ChangeStyle* pValue)
.NET	ChangeStyle get_ChangeType(     Int32 nChange,     Object nFilePair)

• nChange
  Specifies the change (0 based) for which the type is required. This value should be in the range 0 to NumberOfChanges-1.
• nFilePair optional
  Specifies whether to return results for files 0 and 1 (when nFilePair = 0, the default) or files 1 and 2 (when nFilePair = 1).

ComparisonError read-only, IFileComparison

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

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

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

ComparisonResult read-only, IFileComparison

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

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

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

ErrorInfo read/write, IFileComparison

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.

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)

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

FileContent read/write, ITextComparison

Enables the content a file panel to get set or retrieved.

IDL	[propget] HRESULT FileContent(     [in] short nFile,     [out, retval] BSTR* pValue) [propput] HRESULT FileContent(     [in] short nFile,     [in] BSTR newValue)
.NET	String get_FileContent(     Int16 nFile) void set_FileContent(     Int16 nFile, String newValue)

• nFile
  Specifies the file (0, 1 or 2) that contains the line.

FullLineData read-only, ITextComparison

The contents of a line within one of the files. The content includes CR and/or LF line ending characters.

IDL	[propget] HRESULT FullLineData(     [in] long nLine,     [in] short nFile,     [out, retval] BSTR* pValue)
.NET	String get_FullLineData(     Int32 nLine,     Int16 nFile)

• nLine
  Specifies the line (0 based) whose data is required.
• nFile
  Specifies the file (0, 1 or 2) that contains the line.

FullLineLength read-only, ITextComparison

The length of a line within one of the files. The length includes CR and/or LF line ending characters.

IDL	[propget] HRESULT FullLineLength(     [in] long nLine,     [in] short nFile,     [out, retval] long* pValue)
.NET	Int32 get_FullLineLength(     Int32 nLine,     Int16 nFile)

• nLine
  Specifies the line (0 based) whose length is required.
• nFile
  Specifies the file (0, 1 or 2) that contains the line.

Height read/write, ICommonUI

The height of the comparison window in pixels.

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

Left read/write, ICommonUI

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

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

LineData read-only, ITextComparison

The contents of a line within one of the files. The content does not include CR and/or LF line ending characters.

IDL	[propget] HRESULT LineData(     [in] long nLine,     [in] short nFile,     [out, retval] BSTR* pValue)
.NET	String get_LineData(     Int32 nLine,     Int16 nFile)

• nLine
  Specifies the line (0 based) whose data is required.
• nFile
  Specifies the file (0, 1 or 2) that contains the line.

LineLength read-only, ITextComparison

The length of a line within one of the files. The length does not include CR and/or LF line ending characters.

IDL	[propget] HRESULT LineLength(     [in] long nLine,     [in] short nFile,     [out, retval] long* pValue)
.NET	Int32 get_LineLength(     Int32 nLine,     Int16 nFile)

• nLine
  Specifies the line (0 based) whose length is required.
• nFile
  Specifies the file (0, 1 or 2) that contains the line.

Maximized read/write, ICommonUI

The maximized state of the comparison window.

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

Minimized read/write, ICommonUI

The minimized state of the comparison window.

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

Modified read/write, IFileComparison

Enables the modified state of a file to be set or retrieved.

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)

• nFile
  The file (0, 1, or 2) to get/set the modified state for.

NumberOfChanges read-only, IFileComparison

The number of changes between two files. Use this property and the ChangeType, ChangeStartLine, and ChangeLength properties to iterate through the changes between the compared files. Note that the set of changes will include unchanged blocks of lines as well as removed, inserted, and changed blocks of lines.

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

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

NumberOfLines read-only, ITextComparison

The number of lines in one of the compared files.

IDL	[propget] HRESULT NumberOfLines(     [in] short nFile,     [out, retval] short* pValue)
.NET	Int16 get_NumberOfLines(     Int16 nFile)

• nFile
  Specifies the file in question (0, 1 or 2 for the first, second and third files respectively).

PromptForUnsavedFiles read/write, IFileComparison

If a file comparison window containing modified files is closed, Merge will normally provide an opportunity to save them. Setting this property to false will prevent the Save Changes window from appearing. See also the AutoSaveOnClose property.

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

ReadOnly read/write, IFileComparison

Enables the read-only state of a file to be set or retrieved.

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)

• nFile
  The file (0, 1, or 2) to get/set the read-only state for.

SaveFileName read/write, IFileComparison

The filename to use when saving changes (with CtrlS or other save command) in the text comparison window.

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

ThreeWayMergeActions read-only, IFileComparison

Retrieves a collection of actions that need to be performed to merge changes from the first and third files into the central common ancestor file.

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

Top read/write, ICommonUI

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

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

UnresolvedConflicts read-only, IFileComparison

Provides a count of the unresolved conflicts in one of the files in the comparison.

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

• nFile
  Specifies the file (0, 1 or 2) that should be checked for unresolved conflict.

ViewType read/write, IComparison

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

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

Visible read/write, ICommonUI

The visible state of the comparison window.

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

Width read/write, ICommonUI

The width of the comparison window in pixels.

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

Methods

Close ICommonUI

Closes the comparison window.

IDL	HRESULT Close()
.NET	void Close()

Compare IComparison

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

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

• 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

CompareAsync IFileComparison

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

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

• 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

CompareAsyncWithEncoding ITextComparison2

Compares two or three files, using the specified encodings when loading the files. This method is asynchronous (returns before the comparison completes). A ComparisonComplete event is fired when the comparison is finished to report errors and results.

IDL	HRESULT CompareAsyncWithEncoding(     [in] VARIANT strFirstFile,     [in] IEncoding* firstEncoding,     [in] VARIANT strSecondFile,     [in] IEncoding* secondEncoding,     [in, optional] VARIANT strThirdFile,     [in, optional] IEncoding* thirdEncoding)
.NET	void CompareAsyncWithEncoding(     Object strFirstFile,     Encoding firstEncoding,     Object strSecondFile,     Encoding secondEncoding,     Object strThirdFile,     Encoding thirdEncoding)

• strFirstFile
  The fully qualified path to the first file
• firstEncoding
  The encoding to use when loading the first file, or 0 (null NULL) to use the default encoding.
• strSecondFile
  The fully qualified path to the second file
• secondEncoding
  The encoding to use when loading the second file, or 0 (null NULL) to use the default encoding.
• strThirdFile optional
  The fully qualified path to the third file
• thirdEncoding optional
  The encoding to use when loading the third file, or 0 (null NULL) to use the default encoding.

CompareWithEncoding ITextComparison2

Compares two or three files, using the specified encodings when loading the files. This method is synchronous. A ComparisonComplete event is fired when the comparison is finished to report errors and results.

IDL	HRESULT CompareWithEncoding(     [in] VARIANT strFirstFile,     [in] IEncoding* firstEncoding,     [in] VARIANT strSecondFile,     [in] IEncoding* secondEncoding,     [in, optional] VARIANT strThirdFile,     [in, optional] IEncoding* thirdEncoding)
.NET	void CompareWithEncoding(     Object strFirstFile,     Encoding firstEncoding,     Object strSecondFile,     Encoding secondEncoding,     Object strThirdFile,     Encoding thirdEncoding)

• strFirstFile
  The fully qualified path to the first file
• firstEncoding
  The encoding to use when loading the first file, or 0 (null NULL) to use the default encoding.
• strSecondFile
  The fully qualified path to the second file
• secondEncoding
  The encoding to use when loading the second file, or 0 (null NULL) to use the default encoding.
• strThirdFile optional
  The fully qualified path to the third file
• thirdEncoding optional
  The encoding to use when loading the third file, or 0 (null NULL) to use the default encoding.

GiveUserControl ICommonUI

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.

IDL	HRESULT GiveUserControl()
.NET	void GiveUserControl()

Print IComparison

Prints the file comparison.

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

• 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 IComparison

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

IDL	HRESULT Refresh()
.NET	void Refresh()

Report IComparison

Generates a report for the file comparison.

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

• bstrReporter
  The short-name of the reporter that should be used to generate the report. Valid names are xml, html, htmlslideshow, and diff. Please note that not all reporters support the generation of three-way comparison reports.
• nLineEndingStyle
  The type of line-ending to use in the generated report file(s).
• strOutputFile
  The name of the output file for the report. If the reporter generates more than one file, those files will have names based on this one.

Report2 IComparison

Generates a report for the file comparison.

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)

• bstrReporter
  The short-name of the reporter that should be used to generate the report. Valid names are “xml”, “html”, “htmlslideshow”, and “diff”. Please note that not all reporters support the generation of three-way comparison reports.
• nLineEndingStyle
  The type of line-ending to use in the generated report file(s).
• vtEncoding
  The character encoding to use for the generated report. It can either be a code page number, or one of the following strings: UCS2 (Unicode UCS2), UCS2-BE (Unicode UCS2 big endian), UTF8 (Unicode UTF8 with byte-order marker), UTF8-NOBOM (Unicode UTF8 without byte-order marker), UTF7 (Unicode UTF7).
• strOutputFile
  The name of the output file for the report. If the reporter generates more than one file, those files will have names based on this one.

Restore ICommonUI

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

IDL	HRESULT Restore()
.NET	void Restore()

SaveComparison IComparison

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

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

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

SaveFile IFileComparison

Saves the file in the nFile panel. If the strSaveTo argument is provided, Merge performs a Save As to the specified file.

IDL	HRESULT SaveFile(     [in] short nFile,     [in, optional] VARIANT strSaveTo)
.NET	void SaveFile(     Int16 nFile,     Object strSaveTo)

• nFile
  The file (0, 1, or 2) to save.
• strSaveTo optional
  An optional file name to use when saving the file.

SaveFileAs IFileComparison

Prompts the user to save the file in the nFile panel with a new name.

IDL	HRESULT SaveFileAs(     [in] short nFile)
.NET	void SaveFileAs(     Int16 nFile)

• nFile
  The file (0, 1, or 2) to save.

SetPanelTitles IComparison

Sets the titles shown above the file panels.

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

• 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.

ThreeWayMerge IFileComparison

Merges the two outer files in a three-way comparison into the central common ancestor file. The number of merging conflicts encountered during the merge is returned.

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

Events

Close IFileComparisonEvents

The file comparison window was closed by the user.

IDL	HRESULT Close()
.NET	void Close()

ComparisonComplete IFileComparisonEvents

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.

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)

• 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.