org.eclipse.compare
Class CompareEditorInput

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

All Implemented Interfaces:

ICompareContainer, IPropertyChangeNotifier, IAdaptable, IRunnableContext, IRunnableWithProgress, IEditorInput

Direct Known Subclasses:

PageCompareEditorInput, SaveableCompareEditorInput

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

A compare operation which can present its results in a special editor. Running the compare operation and presenting 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 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 ICompareInput 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 ICompareInput with title and title image initialized by the corresponding methods of the ICompareInput.

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 vertically 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 Catch-up/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.

If subclasses of this class implement ISaveablesSource, the compare editor will pass these models through to the workbench. The editor will still show the dirty indicator if one of these underlying models is dirty. It is the responsibility of subclasses that implement this interface to call setDirty(boolean) when the dirty state of any of the models managed by the subclass change dirty state.

See Also:

CompareUI, CompareEditorInput

Field Summary
static  String	DIRTY_STATE           The name of the "dirty" property (value "DIRTY_STATE").
static  String	PROP_SELECTED_EDITION           The name of the "selected edition" property.
static  String	PROP_TITLE           The name of the "title" property.
static  String	PROP_TITLE_IMAGE           The name of the "title image" property.

 

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

 

Method Summary
void	addCompareInputChangeListener ( ICompareInput input, ICompareInputChangeListener listener)           Register for change events for the given compare input.
void	addPropertyChangeListener ( IPropertyChangeListener listener)           Adds a listener for property changes to this notifier.
boolean	belongsTo ( Object family)           Return whether this input belongs to the given family when it is run as a job.
void	cancelPressed ()           The CANCEL button was pressed in a dialog.
boolean	canRunAsJob ()           Return whether this compare editor input can be run as a job.
protected  void	contentsCreated ()           Callback that occurs after the control for the input has been created.
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)
protected   CompareViewerPane	createStructureInputPane ( Composite parent)           Create the pane that will contain the structure input pane (upper left).
void	dispose ()           Disposes this editor input.
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.
protected  void	firePropertyChange ( PropertyChangeEvent event)           Fire the given property change event to all listeners registered with this compare editor input.
protected  void	flushViewers ( IProgressMonitor monitor)           Flush the viewer contents into the input.
IActionBars	getActionBars ()           Return the action bars for the container or null if the container does not have an action bars.
Object	getAdapter ( Class adapter)           Returns an object which is an instance of the given class associated with this object.
String	getCancelButtonLabel ()           Return the label used for the CANCEL button when this input is shown in a compare dialog using CompareUI.openCompareDialog(CompareEditorInput).
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.
ICompareContainer	getContainer ()           Return the container of this input or null if there is no container set.
org.eclipse.compare.internal.ViewerDescriptor	getContentViewerDescriptor ()
ImageDescriptor	getImageDescriptor ()           Returns the image descriptor for this input.
String	getMessage ()
String	getName ()           Returns the name of this editor input for display purposes.
ICompareNavigator	getNavigator ()           Return the ICompareNavigator associated with this container or null if the container does not have a global navigator.
String	getOKButtonLabel ()           Return the label to be used for the OK button when this input is displayed in a dialog.
IPersistableElement	getPersistable ()           Returns null since this editor cannot be persisted.
Object	getSelectedEdition ()           Return the selected edition or null if no edition is selected.
IServiceLocator	getServiceLocator ()           Return the service locator for the container or null if the container does not have one.
org.eclipse.compare.internal.ViewerDescriptor	getStructureViewerDescriptor ()
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.
IWorkbenchPart	getWorkbenchPart ()           Return the workbench part associated with this container or null if there is no part or it is not available.
protected  void	handleDispose ()           Callback that occurs when the UI associated with this compare editor input is disposed.
boolean	isDirty ()           Returns true if there are unsaved changes.
boolean	isEditionSelectionDialog ()           Return whether this input is intended to be used to select a particular edition of an element in a dialog.
boolean	isSaveNeeded ()           Returns true if there are unsaved changes.
boolean	okPressed ()           The OK button was pressed in a dialog.
protected abstract   Object	prepareInput ( IProgressMonitor monitor)           Runs the compare operation and returns the compare result.
void	registerContextMenu ( MenuManager menu, ISelectionProvider selectionProvider)           Register the content menu with the container to give the container a chance to add additional items to the context menu such as popup menu object contributions.
void	removeCompareInputChangeListener ( ICompareInput input, ICompareInputChangeListener listener)           Remove the change listener from the given compare input.
void	removePropertyChangeListener ( IPropertyChangeListener listener)           Removes the given content change listener from this notifier.
void	run (boolean fork, boolean cancelable, IRunnableWithProgress runnable)            Runs the given IRunnableWithProgress in this context.
void	run ( IProgressMonitor monitor)           Runs the compare operation and stores the compare result.
void	runAsynchronously ( IRunnableWithProgress runnable)           Queue the given task to be run asynchronously.
void	save ( IProgressMonitor pm)           Deprecated. Override method saveChanges instead.
void	saveChanges ( IProgressMonitor monitor)           Save any unsaved changes.
void	setContainer ( ICompareContainer container)           Set the container of this input to the given container
void	setContentViewerDescriptor (org.eclipse.compare.internal.ViewerDescriptor vd)
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 ()           Deprecated. Please use setFocus2() instead.
boolean	setFocus2 ()           Asks this input to take focus within its container (editor).
void	setHelpContextId ( String helpContextId)           Set the help context id for this input.
protected  void	setMessage ( String message)
void	setStatusMessage ( String message)           Set the status message displayed by the container to the given message
void	setStructureViewerDescriptor (org.eclipse.compare.internal.ViewerDescriptor vd)
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

PROP_TITLE

public static final 
String PROP_TITLE

The name of the "title" property. This property is fired when the title of the compare input changes. Clients should also re-obtain the tool tip when this property changes.

Since:

3.3

See Also:

getTitle()

PROP_TITLE_IMAGE

public static final 
String PROP_TITLE_IMAGE

The name of the "title image" property. This property is fired when the title image of the compare input changes.

Since:

3.3

See Also:

getTitleImage()

PROP_SELECTED_EDITION

public static final 
String PROP_SELECTED_EDITION

The name of the "selected edition" property. This property is fired when the selected edition of the compare input changes.

Since:

3.3

See Also:

isEditionSelectionDialog(), getSelectedEdition()

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

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

getNavigator

public 
ICompareNavigator getNavigator()

Description copied from interface: ICompareContainer

Return the ICompareNavigator associated with this container or null if the container does not have a global navigator.

Specified by:

getNavigator in interface ICompareContainer

Returns:

the ICompareNavigator associated with this container or null

getImageDescriptor

public 
ImageDescriptor getImageDescriptor()

Description copied from interface: IEditorInput

Returns the image descriptor for this input.

Note: although a null return value has never been permitted from this method, there are many known buggy implementations that return null. Clients that need the image for an editor are advised to use IWorkbenchPart.getImage() instead of IEditorInput.getImageDescriptor(), or to recover from a null return value in a manner that records the ID of the problematic editor input. Implementors that have been returning null from this method should pick some other default return value (such as ImageDescriptor.getMissingImageDescriptor()).

Specified by:

getImageDescriptor in interface IEditorInput

Returns:

the image descriptor for this input; may be null if there is no image.

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; never null.

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; never null;

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

dispose

public void dispose()

Disposes this editor input. Clients should not call this method. The Compare Editor calls this method at appropriate times i.e. when disposing.

Since:

3.5

Restriction:

This method is not intended to be referenced by clients.

Restriction:

This method is not intended to be re-implemented or extended by clients.

handleDispose

protected void handleDispose()

Callback that occurs when the UI associated with this compare editor input is disposed. This method will only be invoked if the UI has been created (i.e. after the call to createContents(Composite). Subclasses can extend this method but ensure that the overridden method is invoked.

Since:

3.3

contentsCreated

protected void contentsCreated()

Callback that occurs after the control for the input has been created. If this method gets invoked then handleDispose() will be invoked when the control is disposed. Subclasses may extend this method to register any listeners that need to be de-registered when the input is disposed.

Since:

3.3

createOutlineContents

public 
Control createOutlineContents(
Composite parent,
                                     int direction)

Parameters:

parent - the parent control under which the control must be created

direction - the layout direction of the contents, either SWT.HORIZONTAL or SWT.VERTICAL

Returns:

the SWT control hierarchy for the outline part of the compare editor

Since:

3.0

protected 
CompareViewerPane createStructureInputPane(
Composite parent)

public void setFocus()

public boolean setFocus2()

public 
Viewer createDiffViewer(
Composite parent)

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

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

public void setContentViewerDescriptor(org.eclipse.compare.internal.ViewerDescriptor vd)

public org.eclipse.compare.internal.ViewerDescriptor getContentViewerDescriptor()

public void setStructureViewerDescriptor(org.eclipse.compare.internal.ViewerDescriptor vd)

public org.eclipse.compare.internal.ViewerDescriptor getStructureViewerDescriptor()

public boolean isSaveNeeded()

public boolean isDirty()

public void setDirty(boolean dirty)

public void addPropertyChangeListener(
IPropertyChangeListener listener)

public void removePropertyChangeListener(
IPropertyChangeListener listener)

public void save(
IProgressMonitor pm)

public void saveChanges(
IProgressMonitor monitor)
                 throws 
CoreException

protected void flushViewers(
IProgressMonitor monitor)

public void addCompareInputChangeListener(
ICompareInput input,
                                          
ICompareInputChangeListener listener)

public void removeCompareInputChangeListener(
ICompareInput input,
                                             
ICompareInputChangeListener listener)

public void registerContextMenu(
MenuManager menu,
                                
ISelectionProvider selectionProvider)

public void setStatusMessage(
String message)

public 
IActionBars getActionBars()

public 
IServiceLocator getServiceLocator()

public 
IWorkbenchPart getWorkbenchPart()

public void run(boolean fork,
                boolean cancelable,
                
IRunnableWithProgress runnable)
         throws 
InvocationTargetException,
                
InterruptedException

public void runAsynchronously(
IRunnableWithProgress runnable)

public void setContainer(
ICompareContainer container)

public final 
ICompareContainer getContainer()

protected void firePropertyChange(
PropertyChangeEvent event)

public boolean canRunAsJob()

public boolean belongsTo(
Object family)

public boolean isEditionSelectionDialog()

public 
String getOKButtonLabel()

public 
String getCancelButtonLabel()

public boolean okPressed()

public void cancelPressed()

public 
Object getSelectedEdition()

public void setHelpContextId(
String helpContextId)