public abstract class CompareEditorInput extends PlatformObject implements IEditorInput, IPropertyChangeNotifier, IRunnableWithProgress, ICompareContainer
A CompareEditorInput
defines methods for the following sequence steps:
openCompareEditor
method takes an CompareEditorInput
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 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.
CompareUI
,
CompareEditorInput
Modifier and Type | Field and Description |
---|---|
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 and Description |
---|
CompareEditorInput(CompareConfiguration configuration)
Creates a
CompareEditorInput which is initialized with the given
compare configuration. |
Modifier and Type | Method and Description |
---|---|
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.
|
protected CompareViewerSwitchingPane |
createContentViewerSwitchingPane(Splitter parent,
int style,
CompareEditorInput cei) |
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).
|
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 |
flushLeftViewers(IProgressMonitor monitor) |
protected void |
flushRightViewers(IProgressMonitor monitor) |
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.
|
protected boolean |
isLeftSaveNeeded()
Returns
true if there are unsaved changes for left side. |
protected boolean |
isRightSaveNeeded()
Returns
true if there are unsaved changes for right side. |
boolean |
isSaveNeeded()
Returns
true if there are unsaved changes in either left or
right side. |
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 |
setLeftDirty(boolean dirty)
Sets the dirty state of left site of this input to the given value and
sends out a
PropertyChangeEvent if the new value for whole
input differs from the old value. |
protected void |
setMessage(String message) |
protected void |
setRightDirty(boolean dirty)
Sets the dirty state of right site of this input to the given value and
sends out a
PropertyChangeEvent if the new value for whole
input differs from the old value. |
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.
|
public static final String DIRTY_STATE
"DIRTY_STATE"
).public static final String PROP_TITLE
getTitle()
public static final String PROP_TITLE_IMAGE
getTitleImage()
public static final String PROP_SELECTED_EDITION
isEditionSelectionDialog()
,
getSelectedEdition()
public CompareEditorInput(CompareConfiguration configuration)
CompareEditorInput
which is initialized with the given
compare configuration.
The compare configuration is passed to subsequently created viewers.configuration
- the compare configurationpublic Object getAdapter(Class adapter)
PlatformObject
null
if
no such object can be found.
This implementation of the method declared by IAdaptable
passes the request along to the platform's adapter manager; roughly
Platform.getAdapterManager().getAdapter(this, adapter)
.
Subclasses may override this method (however, if they do so, they
should invoke the method on their superclass to ensure that the
Platform's adapter manager is consulted).
getAdapter
in interface IAdaptable
getAdapter
in class PlatformObject
adapter
- the class to adapt tonull
IAdaptable.getAdapter(Class)
public ICompareNavigator getNavigator()
ICompareContainer
ICompareNavigator
associated with this container or null
if the container does not have a global navigator.getNavigator
in interface ICompareContainer
ICompareNavigator
associated with this container or null
public ImageDescriptor getImageDescriptor()
IEditorInput
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()).
getImageDescriptor
in interface IEditorInput
null
if
there is no image.public String getToolTipText()
IEditorInput
getToolTipText
in interface IEditorInput
null
.public String getName()
IEditorInput
For instance, when the input is from a file, the return value would ordinarily be just the file name.
getName
in interface IEditorInput
null
;public IPersistableElement getPersistable()
null
since this editor cannot be persisted.getPersistable
in interface IEditorInput
null
because this editor cannot be persistedpublic boolean exists()
false
to indicate that this input
should not appear in the "File Most Recently Used" menu.exists
in interface IEditorInput
false
protected void setMessage(String message)
public String getMessage()
public String getTitle()
setTitle
.public void setTitle(String title)
title
- the title to use for the CompareEditorpublic Image getTitleImage()
null
if nonepublic CompareConfiguration getCompareConfiguration()
public void contributeToToolBar(ToolBarManager toolBarManager)
ToolBarManager
.
Subclasses may override to add their own actions.
toolBarManager
- the ToolBarManager
to which to contributepublic void run(IProgressMonitor monitor) throws InterruptedException, InvocationTargetException
run
in interface IRunnableWithProgress
monitor
- the progress monitor to use to display progress and receive
requests for cancelationInvocationTargetException
- 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 contextInterruptedException
- if the operation detects a request to cancel,
using IProgressMonitor.isCanceled()
, it should exit by throwing
InterruptedException
IRunnableContext.run(boolean, boolean, org.eclipse.jface.operation.IRunnableWithProgress)
protected abstract Object prepareInput(IProgressMonitor monitor) throws InvocationTargetException, InterruptedException
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.
monitor
- the progress monitor to use to display progress and receive
requests for cancelationnull
if there are no differencesInvocationTargetException
- 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 contextInterruptedException
- if the operation detects a request to cancel,
using IProgressMonitor.isCanceled()
, it should exit by throwing
InterruptedException
public Object getCompareResult()
run
method. Returns null
if no
differences were found.prepareInput
or null
if there were no differencespublic Control createContents(Composite parent)
Subclasses may override if they need to change the layout or wiring between panes.
parent
- the parent control under which the control must be createdprotected CompareViewerSwitchingPane createContentViewerSwitchingPane(Splitter parent, int style, CompareEditorInput cei)
parent
- the parent control under which the control must be createdstyle
- the style of widget to constructcei
- the compare editor input for the viewerprotected void handleDispose()
createContents(Composite)
.
Subclasses can extend this method but ensure that the overridden method
is invoked.protected void contentsCreated()
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.public Control createOutlineContents(Composite parent, int direction)
parent
- the parent control under which the control must be createddirection
- the layout direction of the contents, either SWT.HORIZONTAL or
SWT.VERTICAL
protected CompareViewerPane createStructureInputPane(Composite parent)
CompareViewerSwitchingPane
is returned. Subclasses
may override to provide an alternate pane.parent
- the parent compositepublic void setFocus()
setFocus2()
instead.public boolean setFocus2()
true
if the input got focus, and false
if it was unable to.public Viewer createDiffViewer(Composite parent)
createContents
and returns a DiffTreeViewer
.
Subclasses may override if they need a different viewer.
parent
- the SWT parent control under which to create the viewer's SWT controlspublic Viewer findStructureViewer(Viewer oldViewer, ICompareInput input, Composite parent)
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.
oldViewer
- a new viewer is only created if this old viewer cannot show the given inputinput
- the input object for which to find a structure viewerparent
- the SWT parent composite under which the new viewer is creatednull
public Viewer findContentViewer(Viewer oldViewer, ICompareInput input, Composite parent)
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.
oldViewer
- a new viewer is only created if this old viewer cannot show the given inputinput
- the input object for which to find a structure viewerparent
- the SWT parent composite under which the new viewer is creatednull
public void setContentViewerDescriptor(org.eclipse.compare.internal.ViewerDescriptor vd)
vd
- the content viewer descriptorpublic org.eclipse.compare.internal.ViewerDescriptor getContentViewerDescriptor()
public void setStructureViewerDescriptor(org.eclipse.compare.internal.ViewerDescriptor vd)
vd
- the structure viewer descriptorpublic org.eclipse.compare.internal.ViewerDescriptor getStructureViewerDescriptor()
public boolean isSaveNeeded()
true
if there are unsaved changes in either left or
right side. The value returned is the value of the
DIRTY_STATE
property of this input object.
Returns true
if left or right side has unsaved changes
Subclasses don't have to override if the functionality provided by
setDirty
is sufficient.true
if there are changes that need to be savedprotected boolean isLeftSaveNeeded()
true
if there are unsaved changes for left side.true
if there are changes that need to be savedprotected boolean isRightSaveNeeded()
true
if there are unsaved changes for right side.true
if there are changes that need to be savedpublic boolean isDirty()
true
if there are unsaved changes.
The method should be called by any parts or dialogs
that contain the input.
By default, this method calls isSaveNeeded()
but subclasses may extend.true
if there are unsaved changespublic void setDirty(boolean dirty)
PropertyChangeEvent
if the new value differs from the old
value. Direct calling this method with parameter dirty equal to
false
when there are unsaved changes in viewers, results in
inconsistent state. The dirty state of compare input should be based only
on the information if there are changes in viewers for left or right
side.dirty
- the dirty state for this compare inputprotected void setLeftDirty(boolean dirty)
PropertyChangeEvent
if the new value for whole
input differs from the old value. Direct calling this method with
parameter dirty equal to false
when there are unsaved
changes in left viewer, results in inconsistent state. The dirty state of
compare input should be based only on the information if there are
changes in viewers for left side.dirty
- the dirty state for this compare inputprotected void setRightDirty(boolean dirty)
PropertyChangeEvent
if the new value for whole
input differs from the old value. Direct calling this method with
parameter dirty equal to false
when there are unsaved
changes in right viewer, results in inconsistent state. The dirty state
of compare input should be based only on the information if there are
changes in viewers for right side.dirty
- the dirty state for this compare inputpublic void addPropertyChangeListener(IPropertyChangeListener listener)
IPropertyChangeNotifier
addPropertyChangeListener
in interface IPropertyChangeNotifier
listener
- a property change listenerpublic void removePropertyChangeListener(IPropertyChangeListener listener)
IPropertyChangeNotifier
removePropertyChangeListener
in interface IPropertyChangeNotifier
listener
- a property change listenerpublic void save(IProgressMonitor pm)
pm
- an IProgressMonitor
that the implementation of save may use to show progresspublic void saveChanges(IProgressMonitor monitor) throws CoreException
ISavable.save
on them.monitor
- an IProgressMonitor
that the implementation of save may use to show progressCoreException
protected void flushViewers(IProgressMonitor monitor)
monitor
- a progress monitorprotected void flushLeftViewers(IProgressMonitor monitor)
monitor
- protected void flushRightViewers(IProgressMonitor monitor)
monitor
- public void addCompareInputChangeListener(ICompareInput input, ICompareInputChangeListener listener)
ICompareContainer
addCompareInputChangeListener
in interface ICompareContainer
input
- the compare inputlistener
- the compare input change listenerpublic void removeCompareInputChangeListener(ICompareInput input, ICompareInputChangeListener listener)
ICompareContainer
removeCompareInputChangeListener
in interface ICompareContainer
input
- the compare inputlistener
- the compare input change listenerpublic void registerContextMenu(MenuManager menu, ISelectionProvider selectionProvider)
ICompareContainer
IWorkbenchActionConstants.MB_ADDITIONS
separator as this is where the container will add actions.registerContextMenu
in interface ICompareContainer
menu
- the menu being registeredselectionProvider
- the selection providerpublic void setStatusMessage(String message)
ICompareContainer
setStatusMessage
in interface ICompareContainer
message
- the status messagepublic IActionBars getActionBars()
ICompareContainer
null
if the container
does not have an action bars.getActionBars
in interface ICompareContainer
null
public IServiceLocator getServiceLocator()
ICompareContainer
null
if the container
does not have one.getServiceLocator
in interface ICompareContainer
null
public IWorkbenchPart getWorkbenchPart()
ICompareContainer
null
if there is no part or it is not available.getWorkbenchPart
in interface ICompareContainer
null
public void run(boolean fork, boolean cancelable, IRunnableWithProgress runnable) throws InvocationTargetException, InterruptedException
IRunnableContext
Runs the given IRunnableWithProgress
in this context.
For example, if this is a ProgressMonitorDialog
then the runnable
is run using this dialog's progress monitor.
If fork
is false
, the current thread is used
to run the runnable. Note that if fork
is true
,
it is unspecified whether or not this method blocks until the runnable
has been run. Implementers should document whether the runnable is run
synchronously (blocking) or asynchronously (non-blocking), or if no
assumption can be made about the blocking behaviour.
run
in interface IRunnableContext
fork
- true
if the runnable should be run in a separate thread,
and false
to run in the same threadcancelable
- true
to enable the cancelation, and
false
to make the operation uncancellablerunnable
- the runnable to runInvocationTargetException
- wraps any exception or error which occurs
while running the runnableInterruptedException
- propagated by the context if the runnable
acknowledges cancelation by throwing this exception. This should not be thrown
if cancelable is false
.public void runAsynchronously(IRunnableWithProgress runnable)
ICompareContainer
This method should be treated as a request to run the given task asynchronously. However, clients should not assume that the code will be run asynchronously. Depending on the container implementation, a call to this method may or may not block the caller until the task is completed. Also, the task may be executed in a modal or non-modal fashion.
runAsynchronously
in interface ICompareContainer
runnable
- the task to be performedpublic void setContainer(ICompareContainer container)
container
- the containerpublic final ICompareContainer getContainer()
null
if there is no container
set.null
protected void firePropertyChange(PropertyChangeEvent event)
event
- the property change eventpublic boolean canRunAsJob()
false
is returned since traditionally inputs
were prepared in the foreground (i.e the UI was blocked when the
run(IProgressMonitor)
method (and indirectly the
prepareInput(IProgressMonitor)
method) was invoked. Subclasses
may override.public boolean belongsTo(Object family)
family
- the job familycanRunAsJob()
,
Job.belongsTo(Object)
public boolean isEditionSelectionDialog()
false
is returned.getOKButtonLabel()
,
okPressed()
,
getSelectedEdition()
public String getOKButtonLabel()
OK
button when this input is displayed in a dialog.
By default, different labels are used depending on
whether the input is editable or is for edition selection
(see isEditionSelectionDialog()
.OK
button when this input is displayed in a dialogpublic String getCancelButtonLabel()
CANCEL
button when this input is shown in a compare dialog
using CompareUI.openCompareDialog(CompareEditorInput)
.CANCEL
buttonpublic boolean okPressed()
OK
button was pressed in a dialog. If one or both of
the sides of the input is editable then any changes will be saved. If the
input is for edition selection (see isEditionSelectionDialog()
),
it is up to subclasses to override this method in order to perform the
appropriate operation on the selected edition.public void cancelPressed()
CANCEL
button was pressed in a dialog.
By default, nothing is done. Subclasses may override.public Object getSelectedEdition()
null
if no edition is selected.
The result of this method should only be considered if isEditionSelectionDialog()
returns true
.null
public void setHelpContextId(String helpContextId)
helpContextId
- the help context id.
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.