Package org.eclipse.compare.contentmergeviewer

Class TextMergeViewer

java.lang.Object
org.eclipse.jface.viewers.Viewer
org.eclipse.jface.viewers.ContentViewer
org.eclipse.compare.contentmergeviewer.ContentMergeViewer
org.eclipse.compare.contentmergeviewer.TextMergeViewer
All Implemented Interfaces:
IFlushable, IFlushable2, IPropertyChangeNotifier, IAdaptable, IInputProvider, IInputSelectionProvider, ISelectionProvider
public class TextMergeViewer extends ContentMergeViewer implements IAdaptable
A text merge viewer uses the RangeDifferencer to perform a textual, line-by-line comparison of two (or three) input documents. It is based on the ContentMergeViewer and uses TextViewers to implement the ancestor, left, and right content areas.

In the three-way compare case ranges of differing lines are highlighted and framed with different colors to show whether the difference is an incoming, outgoing, or conflicting change. The TextMergeViewer supports the notion of a current "differing range" and provides toolbar buttons to navigate from one range to the next (or previous).

If there is a current "differing range" and the underlying document is editable the TextMergeViewer enables actions in context menu and toolbar to copy a range from one side to the other side, thereby performing a merge operation.

In addition to a line-by-line comparison the TextMergeViewer uses a token based compare on differing lines. The token compare is activated when navigating into a range of differing lines. At first the lines are selected as a block. When navigating into this block the token compare shows for every line the differing token by selecting them.

The TextMergeViewer's default token compare works on characters separated by whitespace. 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 ITokenComparator interface and overriding the TextMergeViewer.createTokenComparator factory method).

Access to the TextMergeViewer's model is by means of an IMergeViewerContentProvider. Its getXContent methods must return either an IDocument, an IDocumentRange, or an IStreamContentAccessor. In the IDocumentRange case the TextMergeViewer works on a subrange of a document. In the IStreamContentAccessor case a document is created internally and initialized from the stream.

A TextMergeViewer can be used as is. However clients may subclass to customize the behavior. For example a MergeTextViewer for Java would override the configureTextViewer method to configure the TextViewer for Java source code, the createTokenComparator method to create a Java specific tokenizer.

In 3.5 a new API has been introduced to let clients provide their own source viewers implementation with an option to configure them basing on a corresponding editor input.

See Also:

  • Constructor Details

    • TextMergeViewer

      public TextMergeViewer(Composite parent, CompareConfiguration configuration)
      Creates a text merge viewer under the given parent control.
      Parameters:
      parent - the parent control
      configuration - the configuration object

    • TextMergeViewer

      public TextMergeViewer(Composite parent, int style, CompareConfiguration configuration)
      Creates a text merge viewer under the given parent control.
      Parameters:
      parent - the parent control
      style - SWT style bits for top level composite of this viewer
      configuration - the configuration object

  • Method Details

    • setBackgroundColor

      public void setBackgroundColor(RGB background)
      Sets the viewer's background color to the given RGB value. If the value is null the system's default background color is used.
      Parameters:
      background - the background color or null to use the system's default background color
      Since:
      2.0

    • setForegroundColor

      public void setForegroundColor(RGB foreground)
      Sets the viewer's foreground color to the given RGB value. If the value is null the system's default foreground color is used.
      Parameters:
      foreground - the foreground color or null to use the system's default foreground color
      Since:
      2.0

    • invalidateTextPresentation

      public void invalidateTextPresentation()
      Invalidates the current presentation by invalidating the three text viewers.
      Since:
      2.0

    • configureTextViewer

      protected void configureTextViewer(TextViewer textViewer)
      Configures the passed text viewer. This method is called after the three text viewers have been created for the content areas. The TextMergeViewer implementation of this method will configure the viewer with a SourceViewerConfiguration. Subclasses may reimplement to provide a specific configuration for the text viewer.
      Parameters:
      textViewer - the text viewer to configure

    • createTokenComparator

      protected ITokenComparator createTokenComparator(String line)
      Creates an ITokenComparator which is used to show the intra line differences. The TextMergeViewer implementation of this method returns a tokenizer that breaks a line into words separated by whitespace. Subclasses may reimplement to provide a specific tokenizer.
      Parameters:
      line - the line for which to create the ITokenComparator
      Returns:
      a ITokenComparator which is used for a second level token compare.

    • createIgnoreWhitespaceContributor

      protected Optional<IIgnoreWhitespaceContributor> createIgnoreWhitespaceContributor(IDocument document)
      Creates an IIgnoreWhitespaceContributor which allows to hook into the ignore whitespace logic in the compare viewer. Tool specific implementations can overrule which whitespaces can be ignored and which not (e.g. whitespaces in literals).
      Returns:
      a IIgnoreWhitespaceContributor which allows to overrule the platform based whitespace ignore logic in the compare view. Default implementation doesn't supply a contributor.
      Since:
      3.9

    • setupDocument

      protected void setupDocument(IDocument document)
      Setup the given document for use with this viewer. By default, the partitioner returned from getDocumentPartitioner() is registered as the default partitioner for the document. Subclasses that return a partitioner must also override getDocumentPartitioning() if they wish to be able to use shared documents (i.e. file buffers).
      Parameters:
      document - the document to be set up
      Since:
      3.3

    • getDocumentPartitioner

      protected IDocumentPartitioner getDocumentPartitioner()
      Returns a document partitioner which is suitable for the underlying content type. This method is only called if the input provided by the content provider is a IStreamContentAccessor and an internal document must be obtained. This document is initialized with the partitioner returned from this method.

      The TextMergeViewer implementation of this method returns null. Subclasses may reimplement to create a partitioner for a specific content type. Subclasses that do return a partitioner should also return a partitioning from getDocumentPartitioning() in order to make use of shared documents (e.g. file buffers).

      Returns:
      a document partitioner, or null

    • getDocumentPartitioning

      protected String getDocumentPartitioning()
      Return the partitioning to which the partitioner returned from getDocumentPartitioner() is to be associated. Return null only if partitioning is not needed or if the subclass overrode setupDocument(IDocument) directly. By default, null is returned which means that shared documents that return a partitioner from getDocumentPartitioner() will not be able to use shared documents.
      Returns:
      a partitioning
      Since:
      3.3
      See Also:

    • handleDispose

      protected void handleDispose(DisposeEvent event)
      Called on the viewer disposal. Unregisters from the compare configuration. Clients may extend if they have to do additional cleanup.
      Overrides:
      handleDispose in class ContentMergeViewer
      Parameters:
      event - a dispose event
      See Also:

    • createControls

      protected void createControls(Composite composite)
      Description copied from class: ContentMergeViewer
      Creates the SWT controls for the ancestor, left, and right content areas of this compare viewer. Implementations typically hold onto the controls so that they can be initialized with the input objects in method updateContent.
      Specified by:
      createControls in class ContentMergeViewer
      Parameters:
      composite - the container for the three areas

    • handleSetFocus

      protected boolean handleSetFocus()
      Override to give focus to the pane that previously had focus or to a suitable default pane.
      Overrides:
      handleSetFocus in class ContentMergeViewer
      Returns:
      whether particular widget was given focus
      Since:
      3.3
      See Also:

    • createCenterControl

      protected final Control createCenterControl(Composite parent)
      Description copied from class: ContentMergeViewer
      Create the control that divides the left and right sides of the merge viewer.
      Overrides:
      createCenterControl in class ContentMergeViewer
      Parameters:
      parent - the parent composite
      Returns:
      the center control

    • getCenterWidth

      protected final int getCenterWidth()
      Description copied from class: ContentMergeViewer
      Return the desired width of the center control. This width is used to calculate the values used to layout the ancestor, left and right sides.
      Overrides:
      getCenterWidth in class ContentMergeViewer
      Returns:
      the desired width of the center control
      See Also:

    • createSourceViewer

      protected SourceViewer createSourceViewer(Composite parent, int textOrientation)
      Creates a new source viewer. This method is called when creating and initializing the content areas of the merge viewer (see createControls(Composite)). It is called three times for each text part of the comparison: ancestor, left, right. Clients may implement to provide their own type of source viewers. The viewer is not expected to be configured with a source viewer configuration.
      Parameters:
      parent - the parent of the viewer's control
      textOrientation - style constant bit for text orientation
      Returns:
      Default implementation returns an instance of SourceViewer.
      Since:
      3.5

    • isEditorBacked

      protected boolean isEditorBacked(ITextViewer textViewer)
      Tells whether the given text viewer is backed by an editor.
      Parameters:
      textViewer - the text viewer to check
      Returns:
      true if the viewer is backed by an editor
      Since:
      3.5

    • getEditorInput

      protected IEditorInput getEditorInput(ISourceViewer sourceViewer)
      Returns an editor input for the given source viewer. The method returns null when no input is available, for example when the input for the merge viewer has not been set yet.
      Parameters:
      sourceViewer - the source viewer to get input for
      Returns:
      input for the given viewer or null when no input is available
      Since:
      3.5

    • setActionsActivated

      protected void setActionsActivated(SourceViewer sourceViewer, boolean state)
      Activates or deactivates actions of the given source viewer.

      The default implementation does nothing, but clients should override to properly react to viewers switching.

      Parameters:
      sourceViewer - the source viewer
      state - true if activated
      Since:
      3.5

    • doSave

      protected boolean doSave(Object newInput, Object oldInput)
      Overridden to prevent save confirmation if new input is sub document of current input.
      Overrides:
      doSave in class ContentMergeViewer
      Parameters:
      newInput - the new input of this viewer, or null if there is no new input
      oldInput - the old input element, or null if there was previously no input
      Returns:
      true if saving was successful, or if the user didn't want to save (by pressing 'NO' in the confirmation dialog).
      Since:
      2.0

    • updateContent

      protected void updateContent(Object ancestor, Object left, Object right)
      Description copied from class: ContentMergeViewer
      Initializes the controls of the three content areas with the given input objects.
      Specified by:
      updateContent in class ContentMergeViewer
      Parameters:
      ancestor - the input for the ancestor area
      left - the input for the left area
      right - the input for the right area

    • setEditable

      protected void setEditable(ISourceViewer sourceViewer, boolean state)
      Sets the editable state of the given source viewer.
      Parameters:
      sourceViewer - the source viewer
      state - the state
      Since:
      3.5

    • findInsertionPosition

      protected int findInsertionPosition(char type, ICompareInput input)

    • getContents

      protected byte[] getContents(boolean left)
      Returns the contents of the underlying document as an array of bytes using the current workbench encoding.
      Specified by:
      getContents in class ContentMergeViewer
      Parameters:
      left - if true the contents of the left side is returned; otherwise the right side
      Returns:
      the contents of the left or right document or null

    • handleResizeAncestor

      protected final void handleResizeAncestor(int x, int y, int width, int height)
      Description copied from class: ContentMergeViewer
      Lays out the ancestor area of the compare viewer. It is called whenever the viewer is resized or when the sashes between the areas are moved to adjust the size of the areas.
      Specified by:
      handleResizeAncestor in class ContentMergeViewer
      Parameters:
      x - the horizontal position of the ancestor area within its container
      y - the vertical position of the ancestor area within its container
      width - the width of the ancestor area
      height - the height of the ancestor area

    • handleResizeLeftRight

      protected final void handleResizeLeftRight(int x, int y, int width1, int centerWidth, int width2, int height)
      Description copied from class: ContentMergeViewer
      Lays out the left and right areas of the compare viewer. It is called whenever the viewer is resized or when the sashes between the areas are moved to adjust the size of the areas.
      Specified by:
      handleResizeLeftRight in class ContentMergeViewer
      Parameters:
      x - the horizontal position of the left area within its container
      y - the vertical position of the left and right area within its container
      width1 - the width of the left area
      centerWidth - the width of the gap between the left and right areas
      width2 - the width of the right area
      height - the height of the left and right areas

    • updateHeader

      protected void updateHeader()
      Description copied from class: ContentMergeViewer
      Updates the headers of the three areas by querying the content provider for a name and image for the three sides of the input object.

      This method is called whenever the header must be updated.

      Subclasses may extend this method, although this is generally not required.

      Overrides:
      updateHeader in class ContentMergeViewer

    • createToolItems

      protected void createToolItems(ToolBarManager tbm)
      Description copied from class: ContentMergeViewer
      Contributes items to the given ToolBarManager. It is called when this viewer is installed in its container and if the container has a ToolBarManager. The ContentMergeViewer implementation of this method does nothing. Subclasses may reimplement.
      Overrides:
      createToolItems in class ContentMergeViewer
      Parameters:
      tbm - the toolbar manager to contribute to

    • handlePropertyChangeEvent

      protected void handlePropertyChangeEvent(PropertyChangeEvent event)
      Description copied from class: ContentMergeViewer
      Callback that is invoked when a property in the compare configuration (ContentMergeViewer.getCompareConfiguration() changes.
      Overrides:
      handlePropertyChangeEvent in class ContentMergeViewer
      Parameters:
      event - the property change event

    • updateToolItems

      protected void updateToolItems()
      Description copied from class: ContentMergeViewer
      Updates the enabled state of the toolbar items.

      This method is called whenever the state of the items needs updating.

      Subclasses may extend this method, although this is generally not required.

      Overrides:
      updateToolItems in class ContentMergeViewer

    • copy

      protected void copy(boolean leftToRight)
      Description copied from class: ContentMergeViewer
      Copies the content of one side to the other side. Called from the (internal) actions for copying the sides of the viewer's input object.
      Specified by:
      copy in class ContentMergeViewer
      Parameters:
      leftToRight - if true, the left side is copied to the right side; if false, the right side is copied to the left side

    • flushContent

      protected void flushContent(Object oldInput, IProgressMonitor monitor)
      Description copied from class: ContentMergeViewer
      Flushes the modified content back to input elements via the content provider. The provided input may be the current input of the viewer or it may be the previous input (i.e. this method may be called to flush modified content during an input change).
      Overrides:
      flushContent in class ContentMergeViewer
      Parameters:
      oldInput - the compare input
      monitor - a progress monitor or null if the method was call from a place where a progress monitor was not available.

    • getAdapter

      public <T> T getAdapter(Class<T> adapter)
      Description copied from interface: IAdaptable
      Returns an object which is an instance of the given class associated with this object. Returns null if no such object can be found.

      Clients may implement this method but should generally call Adapters.adapt(Object, Class, boolean) rather than invoking it directly.

      Specified by:
      getAdapter in interface IAdaptable
      Type Parameters:
      T - the class type
      Parameters:
      adapter - the adapter class to look up
      Returns:
      a object of the given class, or null if this object does not have an adapter for the given class

    • handleCompareInputChange

      protected void handleCompareInputChange()
      Description copied from class: ContentMergeViewer
      Handle a change to the given input reported from an ICompareInputChangeListener. This class registers a listener with its input and reports any change events through this method. By default, this method prompts for any unsaved changes and then refreshes the viewer. Subclasses may override.
      Overrides:
      handleCompareInputChange in class ContentMergeViewer