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
Class CompareEditorInput

    java.lang.Object
      org.eclipse.compare.CompareEditorInput

All Implemented Interfaces:
  IAdaptable, IEditorInput, IPropertyChangeNotifier, IRunnableWithProgress

Direct Known Subclasses:
  SyncInfoCompareInput

public abstract class CompareEditorInput
extends Object
implements IEditorInput, IPropertyChangeNotifier, IRunnableWithProgress

A compare operation which can present its results in a special editor. Running the compare operation and presentating the results in a compare editor are combined in one class because it allows a client to keep the implementation all in one place while separating it from the innards of a specific UI implementation of compare/merge.

A `CompareEditorInput` defines methods for the following sequence steps:

- running a lengthy compare operation under progress monitor control,
- creating a UI for displaying the model and initializing the some widgets with the compare result,
- tracking the dirty state of the model in case of merge,
- saving the model.

The Compare plug-in's `openCompareEditor` method takes an `ICompareEditorInput` and starts sequencing through the above steps. If the compare result is not empty a new compare editor is opened and takes over the sequence until eventually closed.

The `prepareInput` method should contain the code of the compare operation. It is executed under control of a progress monitor and can be canceled. If the result of the compare is not empty, that is if there are differences that needs to be presented, the `ICompareEditorInput` should hold onto them and return them with the `getCompareResult` method. If the value returned from `getCompareResult` is not `null` a compare editor is opened on the `ICompareEditorInput` with title and title image initialized by the corresponding methods of the `ICompareEditorInput`.

Creation of the editor's SWT controls is delegated to the `createContents` method. Here the SWT controls must be created and initialized with the result of the compare operation.

If merging is allowed, the modification state of the compared constituents must be tracked and the dirty state returned from method `isSaveNeeded`. The value `true` triggers a subsequent call to `save` where the modified resources can be saved.

The most important part of this implementation is the setup of the compare/merge UI. The UI uses a simple browser metaphor to present compare results. The top half of the layout shows the structural compare results (e.g. added, deleted, and changed files), the bottom half the content compare results (e.g. textual differences between two files). A selection in the top pane is fed to the bottom pane. If a content viewer is registered for the type of the selected object, this viewer is installed in the pane. In addition if a structure viewer is registered for the selection type the top pane is split horizontally to make room for another pane and the structure viewer is installed in it. When comparing Java files this second structure viewer would show the structural differences within a Java file, e.g. added, deleted or changed methods and fields.

Subclasses provide custom setups, e.g. for a Catchup/Release operation by passing a subclass of `CompareConfiguration` and by implementing the `prepareInput` method. If a subclass cannot use the `DiffTreeViewer` which is installed by default in the top left pane, method `createDiffViewer` can be overridden.

See Also:
  `CompareUI`, `CompareEditorInput`

Field Summary
`static String` | `DIRTY_STATE` The name of the "dirty" property (value `"DIRTY_STATE"`).

Constructor Summary
`CompareEditorInput(CompareConfiguration configuration)` Creates a `CompareEditorInput` which is initialized with the given compare configuration.

Method Summary
`void` | `addPropertyChangeListener(IPropertyChangeListener listener)` Adds a listener for property changes to this notifier.
`void` | `contributeToToolBar(ToolBarManager toolBarManager)` Adds standard actions to the given `ToolBarManager`.
`Control` | `createContents(Composite parent)` Create the SWT controls that are used to display the result of the compare operation.
`Viewer` | `createDiffViewer(Composite parent)` Factory method for creating a differences viewer for the top left pane.
`Control` | `createOutlineContents(Composite parent, int direction)`
`boolean` | `exists()` Returns `false` to indicate that this input should not appear in the "File Most Recently Used" menu.
`Viewer` | `findContentViewer(Viewer oldViewer, ICompareInput input, Composite parent)` Implements the dynamic viewer switching for content viewers.
`Viewer` | `findStructureViewer(Viewer oldViewer, ICompareInput input, Composite parent)` Implements the dynamic viewer switching for structure viewers.
`Object` | `getAdapter(Class adapter)` Returns an object which is an instance of the given class associated with this object.
`CompareConfiguration` | `getCompareConfiguration()` Returns the configuration object for the viewers within the compare editor.
`Object` | `getCompareResult()` Returns the compare result computed by the most recent call to the `run` method.
`ImageDescriptor` | `getImageDescriptor()` Returns the image descriptor for this input.
`String` | `getMessage()`
`String` | `getName()` Returns the name of this editor input for display purposes.
`IPersistableElement` | `getPersistable()` Returns `null` since this editor cannot be persisted.
`String` | `getTitle()` Returns the title which will be used in the compare editor's title bar.
`Image` | `getTitleImage()` Returns the title image which will be used in the compare editor's title bar.
`String` | `getToolTipText()` Returns the tool tip text for this editor input.
`boolean` | `isSaveNeeded()` Returns `true` if there are unsaved changes.
`protected abstract Object` | `prepareInput(IProgressMonitor monitor)` Runs the compare operation and returns the compare result.
`void` | `removePropertyChangeListener(IPropertyChangeListener listener)` Removes the given content change listener from this notifier.
`void` | `run(IProgressMonitor monitor)` Runs the compare operation and stores the compare result.
`void` | `save(IProgressMonitor pm)` Deprecated. Override method saveChanges instead.
`void` | `saveChanges(IProgressMonitor pm)` Save any unsaved changes.
`void` | `setDirty(boolean dirty)` Sets the dirty state of this input to the given value and sends out a `PropertyChangeEvent` if the new value differs from the old value.
`void` | `setFocus()` Asks this input to take focus within its container (editor).
`protected void` | `setMessage(String message)`
`void` | `setTitle(String title)` Sets the title which will be used when presenting the compare result.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DIRTY_STATE

    public static final String DIRTY_STATE

  The name of the "dirty" property (value `"DIRTY_STATE"`).

  See Also:
    Constant Field Values

Constructor Detail

### CompareEditorInput

    public CompareEditorInput(CompareConfiguration configuration)

  Creates a `CompareEditorInput` which is initialized with the given compare configuration. The compare configuration is passed to subsequently created viewers.

Parameters:
  `configuration` - the compare configuration

Method Detail

### getAdapter

    public Object getAdapter(Class 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.

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

### getImageDescriptor

    public ImageDescriptor getImageDescriptor()

  Description copied from interface: `IEditorInput`
  Returns the image descriptor for this input.

  Specified by:
    `getImageDescriptor` in interface `IEditorInput`
  Returns:
    the image descriptor for this input

### getToolTipText

    public String getToolTipText()

  Description copied from interface: `IEditorInput`
  Returns the tool tip text for this editor input. This text is used to differentiate between two input with the same name. For instance, MyClass.java in folder X and MyClass.java in folder Y. The format of the text varies between input types.

  Specified by:
    `getToolTipText` in interface `IEditorInput`
  Returns:
    the tool tip text

### getName

    public String getName()

  Description copied from interface: `IEditorInput`
  Returns the name of this editor input for display purposes.

  For instance, when the input is from a file, the return value would ordinarily be just the file name.

  Specified by:
    `getName` in interface `IEditorInput`
  Returns:
    the name string

### getPersistable

    public IPersistableElement getPersistable()

  Returns `null` since this editor cannot be persisted.

  Specified by:
    `getPersistable` in interface `IEditorInput`
  Returns:
    `null` because this editor cannot be persisted

### exists

    public boolean exists()

  Returns `false` to indicate that this input should not appear in the "File Most Recently Used" menu.

  Specified by:
    `exists` in interface `IEditorInput`
  Returns:
    `false`

### setMessage

    protected void setMessage(String message)

### getMessage

    public String getMessage()

### getTitle

    public String getTitle()

  Returns the title which will be used in the compare editor's title bar. It can be set with `setTitle`.

  Returns:
    the title

### setTitle

    public void setTitle(String title)

  Sets the title which will be used when presenting the compare result. This method must be called before the editor is opened.

  Parameters:
    `title` - the title to use for the CompareEditor

### getTitleImage

    public Image getTitleImage()

  Returns the title image which will be used in the compare editor's title bar. Returns the title image which will be used when presenting the compare result. This implementation returns a generic compare icon. Subclasses can override.

  Returns:
    the title image, or `null` if none

### getCompareConfiguration

    public CompareConfiguration getCompareConfiguration()

  Returns the configuration object for the viewers within the compare editor. Returns the configuration which was passed to the constructor.

  Returns:
    the compare configuration

### contributeToToolBar

    public void contributeToToolBar(ToolBarManager toolBarManager)

  Adds standard actions to the given `ToolBarManager`.

  Subclasses may override to add their own actions.

  Parameters:
    `toolBarManager` - the `ToolBarManager` to which to contribute

### run

    public void run(IProgressMonitor monitor)
             throws InterruptedException,
                    InvocationTargetException

  Runs the compare operation and stores the compare result.

  Specified by:
    `run` in interface `IRunnableWithProgress`
  Parameters:
    `monitor` - the progress monitor to use to display progress and receive requests for cancelation
  Throws:
    `InvocationTargetException` - if the `prepareInput` method must propagate a checked exception, it should wrap it inside an `InvocationTargetException`; runtime exceptions are automatically wrapped in an `InvocationTargetException` by the calling context
    `InterruptedException` - if the operation detects a request to cancel, using `IProgressMonitor.isCanceled()`, it should exit by throwing `InterruptedException`
  See Also:
    `IRunnableContext.run(boolean, boolean, org.eclipse.jface.operation.IRunnableWithProgress)`

### prepareInput

    protected abstract Object prepareInput(IProgressMonitor monitor)
                                    throws InvocationTargetException,
                                           InterruptedException

  Runs the compare operation and returns the compare result. If `null` is returned no differences were found and no compare editor needs to be opened. Progress should be reported to the given progress monitor. A request to cancel the operation should be honored and acknowledged by throwing `InterruptedException`.

  Note: this method is typically called in a modal context thread which doesn't have a Display assigned. Implementors of this method shouldn't therefore allocated any SWT resources in this method.

  Parameters:
    `monitor` - the progress monitor to use to display progress and receive requests for cancelation
  Returns:
    the result of the compare operation, or `null` if there are no differences
  Throws:
    `InvocationTargetException` - if the `prepareInput` method must propagate a checked exception, it should wrap it inside an `InvocationTargetException`; runtime exceptions are automatically wrapped in an `InvocationTargetException` by the calling context
    `InterruptedException` - if the operation detects a request to cancel, using `IProgressMonitor.isCanceled()`, it should exit by throwing `InterruptedException`

### getCompareResult

    public Object getCompareResult()

  Returns the compare result computed by the most recent call to the `run` method. Returns `null` if no differences were found.

  Returns:
    the compare result prepared in method `prepareInput` or `null` if there were no differences

### createContents

    public Control createContents(Composite parent)

  Create the SWT controls that are used to display the result of the compare operation. Creates the SWT Controls and sets up the wiring between the individual panes. This implementation creates all four panes but makes only the necessary ones visible. Finally it feeds the compare result into the top left structure viewer and the content viewer.

  Subclasses may override if they need to change the layout or wiring between panes.

  Parameters:
    `parent` - the parent control under which the control must be created
  Returns:
    the SWT control hierarchy for the compare editor

### createOutlineContents

    public Control createOutlineContents(Composite parent,
                                         int direction)

  Parameters:
    `parent` - the parent control under which the control must be created
  Returns:
    the SWT control hierarchy for the outline part of the compare editor
  Since:
    3.0

### setFocus

    public void setFocus()

  Asks this input to take focus within its container (editor).

  Clients should not call this method but they may override if they implement a different layout with different visual components. Clients are free to call the inherited method.

### createDiffViewer

    public Viewer createDiffViewer(Composite parent)

  Factory method for creating a differences viewer for the top left pane. It is called from `createContents` and returns a `DiffTreeViewer`.

  Subclasses may override if they need a different viewer.

  Parameters:
    `parent` - the SWT parent control under which to create the viewer's SWT controls
  Returns:
    a compare viewer for the top left pane

### findStructureViewer

    public Viewer findStructureViewer(Viewer oldViewer,
                                      ICompareInput input,
                                      Composite parent)

  Implements the dynamic viewer switching for structure viewers. The method must return a compare viewer based on the old (or current) viewer and a new input object. If the old viewer is suitable for showing the new input the old viewer can be returned. Otherwise a new viewer must be created under the given parent composite or `null` can be returned to indicate that no viewer could be found.

  This implementation forwards the request to `CompareUI.findStructureViewer`.

  Subclasses may override to implement a different strategy.

  Returns:
    a compare viewer which is suitable for the given input object or `null`

### findContentViewer

    public Viewer findContentViewer(Viewer oldViewer,
                                    ICompareInput input,
                                    Composite parent)

  Implements the dynamic viewer switching for content viewers. The method must return a compare viewer based on the old (or current) viewer and a new input object. If the old viewer is suitable for showing the new input the old viewer can be returned. Otherwise a new viewer must be created under the given parent composite or `null` can be returned to indicate that no viewer could be found.

  This implementation forwards the request to `CompareUI.findContentViewer`.

  Subclasses may override to implement a different strategy.

  Returns:
    a compare viewer which is suitable for the given input object or `null`

### isSaveNeeded

    public boolean isSaveNeeded()

  Returns `true` if there are unsaved changes. The value returned is the value of the `DIRTY_STATE` property of this input object. Returns `true` if this input has unsaved changes, that is if `setDirty(true)` has been called. Subclasses don't have to override if the functionality provided by setDirty is sufficient.

  Returns:
    `true` if there are changes that need to be saved

### setDirty

    public void setDirty(boolean dirty)

  Sets the dirty state of this input to the given value and sends out a `PropertyChangeEvent` if the new value differs from the old value.

  Parameters:
    `dirty` - the dirty state for this compare input

### addPropertyChangeListener

    public void addPropertyChangeListener(IPropertyChangeListener listener)

  Description copied from interface: `IPropertyChangeNotifier`
  Adds a listener for property changes to this notifier. Has no effect if an identical listener is already registered.

  Specified by:
    `addPropertyChangeListener` in interface `IPropertyChangeNotifier`
  Parameters:
    `listener` - a property change listener

### removePropertyChangeListener

    public void removePropertyChangeListener(IPropertyChangeListener listener)

  Description copied from interface: `IPropertyChangeNotifier`
  Removes the given content change listener from this notifier. Has no effect if the identical listener is not registered.

  Specified by:
    `removePropertyChangeListener` in interface `IPropertyChangeNotifier`
  Parameters:
    `listener` - a property change listener

### save

    public void save(IProgressMonitor pm)

  Deprecated. Override method saveChanges instead.

  Save any unsaved changes. Empty implementation. Subclasses must override to save any changes.

  Parameters:
    `pm` - an `IProgressMonitor` that the implementation of save may use to show progress

### saveChanges

    public void saveChanges(IProgressMonitor pm)
                     throws CoreException

  Save any unsaved changes. Subclasses must override to save any changes. This implementation tries to flush changes in all viewers by calling `ISavable.save` on them.

  Parameters:
    `pm` - an `IProgressMonitor` that the implementation of save may use to show progress
  Throws:
    `CoreException`
  Since:
    2.0

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.