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:

IInputProvider, IInputSelectionProvider, IPropertyChangeNotifier, org.eclipse.compare.internal.ISavable, ISelectionProvider

public class TextMergeViewer

extends ContentMergeViewer

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.

See Also:

RangeDifferencer, TextViewer, ITokenComparator, IDocumentRange, IStreamContentAccessor

Field Summary

Fields inherited from class org.eclipse.jface.viewers.Viewer

WIDGET_DATA_KEY

Constructor Summary

TextMergeViewer(Composite parent, CompareConfiguration configuration)
Creates a text merge viewer under the given parent control.

TextMergeViewer(Composite parent, int style, CompareConfiguration configuration)
Creates a text merge viewer under the given parent control.

Method Summary

protected void	configureTextViewer(TextViewer textViewer) Configures the passed text viewer.
protected void	copy(boolean leftToRight) Copies the content of one side to the other side.
protected void	createControls(Composite composite) Creates the specific SWT controls for the content areas.
protected ITokenComparator	createTokenComparator(String s) Creates an ITokenComparator which is used to show the intra line differences.
protected void	createToolItems(ToolBarManager tbm) Creates the two items for copying a difference range from one side to the other and adds them to the given toolbar manager.
protected boolean	doSave(Object newInput, Object oldInput) Overridden to prevent save confirmation if new input is sub document of current input.
protected int	findInsertionPosition(char type, ICompareInput input) This method is called if a range of text on one side is copied into an empty subdocument on the other side.
protected byte[]	getContents(boolean left) Returns the contents of the underlying document as an array of bytes.
protected IDocumentPartitioner	getDocumentPartitioner() Returns a document partitioner which is suitable for the underlying content type.
protected void	handleDispose(DisposeEvent event) Called on the viewer disposal.
protected void	handleResizeAncestor(int x, int y, int width, int height) Lays out the ancestor area of the compare viewer.
protected void	handleResizeLeftRight(int x, int y, int width1, int centerWidth, int width2, int height) Lays out everything.
void	invalidateTextPresentation() Invalidates the current presentation by invalidating the three text viewers.
void	setBackgroundColor(RGB background) Sets the viewer's background color to the given RGB value.
void	setForegroundColor(RGB foreground) Sets the viewer's foreground color to the given RGB value.
protected void	updateContent(Object ancestor, Object left, Object right) Initializes the text viewers of the three content areas with the given input objects.
protected void	updateHeader() 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.
protected void	updateToolItems() Updates the enabled state of the toolbar items.

Methods inherited from class org.eclipse.compare.contentmergeviewer.ContentMergeViewer

addPropertyChangeListener, buildControl, getCompareConfiguration, getControl, getResourceBundle, getSelection, getTitle, inputChanged, refresh, removePropertyChangeListener, save, setConfirmSave, setContentProvider, setLeftDirty, setRightDirty, setSelection

Methods inherited from class org.eclipse.jface.viewers.ContentViewer

getContentProvider, getInput, getLabelProvider, handleLabelProviderChanged, hookControl, labelProviderChanged, setInput, setLabelProvider

Methods inherited from class org.eclipse.jface.viewers.Viewer

addHelpListener, addSelectionChangedListener, fireHelpRequested, fireSelectionChanged, getData, handleHelpRequest, removeHelpListener, removeSelectionChangedListener, scrollDown, scrollUp, setData, setSelection

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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 Detail

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 does nothing. Subclasses may reimplement to provide a specific configuration for the text viewer.

Parameters:

textViewer - the text viewer to configure

createTokenComparator

protected ITokenComparator createTokenComparator(String s)

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.

Returns:

a ITokenComparator which is used for a second level token compare.

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

Returns:

a document partitioner, or null

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

createControls

protected void createControls(Composite composite)

Creates the specific SWT controls for the content areas. Clients must not call or override this method.

Specified by:

createControls in class ContentMergeViewer

Parameters:

composite - the container for the three areas

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)

Initializes the text viewers of the three content areas with the given input objects. Subclasses may extend.

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

findInsertionPosition

protected int findInsertionPosition(char type,
                                    ICompareInput input)

This method is called if a range of text on one side is copied into an empty subdocument on the other side. The method returns the position where the subdocument is placed into the base document. This default implementation determines the position by using the text range differencer. However this position is not always optimal for specific types of text. So subclasses (which are awrae of the type of text they are dealing with) may override this method to find a better position where to insert a newly added piece of text.

Parameters:

type - the side for which the insertion position should be determined: 'A' for ancestor, 'L' for left hand side, 'R' for right hand side.

input - the current input object of this viewer

Since:

2.0

getContents

protected byte[] getContents(boolean left)

Returns the contents of the underlying document as an array of bytes.

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)

Lays out everything.

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)

Creates the two items for copying a difference range from one side to the other and adds them to the given toolbar manager.

Overrides:

createToolItems in class ContentMergeViewer

Parameters:

tbm - the toolbar manager to contribute to

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