| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en"> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2010. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <TITLE>Implementing a Content Viewer</TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| <H2> |
| Implementing a content viewer</H2> |
| |
| |
| <p> |
| The compare plug-in allows you to supply specialized viewers for viewing and |
| merging content differences between unstructured elements.</p> |
| |
| |
| <h3> |
| Simple content viewers</h3> |
| |
| |
| <p> |
| A <b>content viewer</b> is used in places where only a single input is available and therefore |
| no compare is necessary. A typical example for this is the "<b>Restore from Local |
| History</b>" function. The <a href="../reference/extension-points/org_eclipse_compare_contentViewers.html"><b>org.eclipse.compare.contentViewers</b></a> |
| extension point allows you to define a specialized content viewer that does not |
| compare its inputs. </p> |
| <pre><extension |
| point="org.eclipse.compare.contentViewers"> |
| <viewer |
| extensions="java,java2" |
| class="org.eclipse.jdt.internal.ui.compare.JavaTextViewerCreator" |
| id="org.eclipse.jdt.internal.ui.compare.JavaTextViewerCreator"> |
| </viewer> |
| <contentTypeBinding |
| contentTypeId="org.eclipse.jdt.core.javaSource" |
| contentViewerId="org.eclipse.jdt.internal.ui.compare.JavaTextViewerCreator"> |
| </contentTypeBinding> |
| </extension> |
| </pre> |
| <p>Specialized viewers contributed by your plug-in are designated in the |
| <b>viewer</b> element. You must specify the <b>id </b>of the viewer and the <b>class</b> that |
| creates it. You may also specify any file <b>extensions</b> for which the content viewer should be used. </p> |
| <p>You may also use the <b>contentTypeBinding</b> element to associate a <a href="runtime_content.htm">content type</a> |
| with a content viewer. |
| </p> |
| <h3>Content merge viewers</h3> |
| <p> A <b> content merge viewer </b> performs a two-way or three-way compare of its inputs |
| and presents the result side-by-side or in any other suitable way. The viewer lets the user |
| merge between the inputs. Content merge viewers are common for text or images.</p> |
| <p>If the standard merge viewers are not appropriate for your plug-in's |
| function, you may choose to implement your own content merge viewer. Your |
| content merge viewer should be registered with the platform using the |
| <a href="../reference/extension-points/org_eclipse_compare_contentMergeViewers.html"><b>org.eclipse.compare.contentMergeViewers</b></a> |
| extension point. The following markup shows |
| the definition of specialized content merge viewers for viewing Java files and |
| properties files in the Java IDE: |
| </p> |
| <pre><extension |
| point="org.eclipse.compare.contentMergeViewers"> |
| <viewer |
| extensions="java,java2" |
| class="org.eclipse.jdt.internal.ui.compare.JavaContentViewerCreator" |
| id="org.eclipse.jdt.internal.ui.compare.JavaContentViewerCreator"> |
| </viewer> |
| <contentTypeBinding |
| contentTypeId="org.eclipse.jdt.core.javaSource" |
| contentMergeViewerId="org.eclipse.jdt.internal.ui.compare.JavaContentViewerCreator"> |
| </contentTypeBinding> |
| </extension> |
| <extension |
| point="org.eclipse.compare.contentMergeViewers"> |
| <viewer |
| extensions="properties,properties2" |
| class="org.eclipse.jdt.internal.ui.compare.PropertiesFileMergeViewerCreator" |
| id="org.eclipse.jdt.internal.ui.compare.PropertiesFileMergeViewerCreator"> |
| </viewer> |
| <contentTypeBinding |
| contentTypeId="org.eclipse.jdt.core.javaProperties" |
| contentMergeViewerId="org.eclipse.jdt.internal.ui.compare.PropertiesFileMergeViewerCreator"> |
| </contentTypeBinding> |
| </extension> |
| </pre> |
| <p> |
| Similar to content viewers, specialized merge viewers contributed by your plug-in are designated in the |
| <b>viewer</b> element. You must specify the <b>id </b>of the viewer and the <b>class</b> that |
| creates it. You may also specify any file <b>extensions</b> for which the content merge viewer should be used. |
| </p> |
| <p>Also similar to content viewers, you can use <b>contentTypeBinding</b> to associate a <a href="runtime_content.htm">content type</a> |
| with a merge viewer. The JDT plug-in binds content merge viewers to two different content types: Java source and Java properties files. |
| </p> |
| |
| |
| <p> <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ContentMergeViewer.html"><b>ContentMergeViewer</b></a> |
| is an abstract compare and merge viewer |
| with two side-by-side content areas and an optional content area for a |
| common ancestor (for three-way compare). Because the implementation makes |
| no assumptions about the content type, the subclass is responsible for dealing |
| with the specific content type. </p> |
| |
| |
| <p> <b>ImageMergeViewer</b> in <b> org.eclipse.compare.internal</b> shows how to |
| implement a simple merge viewer for images using a <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ContentMergeViewer.html"><b>ContentMergeViewer</b></a>. |
| A <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ContentMergeViewer.html"><b>ContentMergeViewer</b></a> |
| accesses its model by means of a content |
| provider which must implement the |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/IMergeViewerContentProvider.html"><b>IMergeViewerContentProvider</b></a> interface.</p> |
| |
| |
| <h4><a name="Text">Text merging</a></h4> |
| |
| |
| <p> If your viewer uses text, additional classes that compare |
| and merge text content can be used.</p> |
| <p> |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/TextMergeViewer.html"><b>TextMergeViewer</b></a> |
| is the concrete subclass of |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ContentMergeViewer.html"><b>ContentMergeViewer</b></a> |
| used for comparing and merging text content. A text merge viewer uses the |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/RangeDifferencer.html"><b>RangeDifferencer</b></a> |
| to perform a textual, line-by-line comparison of two (or three) input documents.</p> |
| <p> |
| For text lines that differ, the |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/TextMergeViewer.html"><b>TextMergeViewer</b></a> |
| uses an |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ITokenComparator.html"><b>ITokenComparator</b></a> |
| to find the longest sequences of matching and non-matching tokens. |
| The |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/TextMergeViewer.html"><b>TextMergeViewer</b></a>'s |
| default token compare works on characters separated by white space. If a |
| different strategy is needed (for example, Java tokens in a Java-aware |
| merge viewer), clients can create their own token comparators by implementing |
| the |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/ITokenComparator.html"><b>ITokenComparator</b></a> |
| interface.</p> |
| <p> |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/TextMergeViewer.html"><b>TextMergeViewer</b></a> |
| works on whole documents and on sub ranges of documents. For partial documents, |
| the viewer's input must adapt to an |
| <a href="../reference/api/org/eclipse/compare/contentmergeviewer/IDocumentRange.html"><b>IDocumentRange</b></a> |
| instead of an |
| <a href="../reference/api/org/eclipse/jface/text/IDocument.html"><b>IDocument</b></a>.</p> |
| |
| <p>The <a href="../reference/api/org/eclipse/compare/contentmergeviewer/TextMergeViewer.html"><b>TextMergeViewer</b></a> also |
| supports the use of a shared document (i.e. document's that are shared by multiple open editors) when the input adapts to an |
| <a href="../reference/api/org/eclipse/compare/ISharedDocumentAdapter.html"><b>ISharedDocumentAdapter</b></a>. Subclasses of |
| TextMergeViewer that provide syntax highlighting must implement both the <code>getDocumentPartitioner()</code> and |
| <code>getDocumentPartitioning()</code> methods to support shared documents. </p> |
| |
| <h4>Range differencing</h4> |
| <p> |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/RangeDifferencer.html"><b>RangeDifferencer</b></a> |
| finds the longest sequences of matching and |
| non-matching comparable entities in text content. |
| Clients must supply |
| an input to the differencer that implements the |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/IRangeComparator.html"><b>IRangeComparator</b></a> |
| interface. |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/IRangeComparator.html"><b>IRangeComparator</b></a> |
| breaks the input data into a sequence |
| of entities and provides a method for comparing |
| one entity with the entity in another |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/IRangeComparator.html"><b>IRangeComparator</b></a>. |
| </p><p> |
| For example, to compare two text documents and find the longest common |
| sequences of matching and non-matching lines, |
| the implementation of |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/IRangeComparator.html"><b>IRangeComparator</b> </a> |
| must break the document into lines and provide a method for testing |
| whether two lines are considered equal. |
| See <b>org.eclipse.compare.internal.DocLineComparator</b> for an example of how this can be done.</p> |
| <p>The differencer returns the differences among these sequences as an |
| array of |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/RangeDifference.html"><b>RangeDifference</b></a> |
| objects. |
| Every single |
| <a href="../reference/api/org/eclipse/compare/rangedifferencer/RangeDifference.html"><b>RangeDifference</b></a> |
| describes the kind of difference |
| (no change, change, addition, deletion) and the corresponding ranges |
| of the underlying comparable entities in the two or three inputs. |
| </p> |
| </BODY> |
| </HTML> |
