Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `TextViewer`s 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 `getX`Content 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 using the current workbench encoding.
`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`

### 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 aware 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 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)

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.