|
Eclipse Platform Release 3.6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Objectorg.eclipse.core.runtime.PlatformObject
org.eclipse.compare.CompareEditorInput
public abstract class CompareEditorInput
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:
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| Field Summary | |
|---|---|
static java.lang.String |
DIRTY_STATE
The name of the "dirty" property (value "DIRTY_STATE"). |
static java.lang.String |
PROP_SELECTED_EDITION
The name of the "selected edition" property. |
static java.lang.String |
PROP_TITLE
The name of the "title" property. |
static java.lang.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(java.lang.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 |
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. |
java.lang.Object |
getAdapter(java.lang.Class adapter)
Returns an object which is an instance of the given class associated with this object. |
java.lang.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. |
java.lang.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. |
java.lang.String |
getMessage()
|
java.lang.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. |
java.lang.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. |
java.lang.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()
|
java.lang.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. |
java.lang.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 java.lang.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(java.lang.String helpContextId)
Set the help context id for this input. |
protected void |
setMessage(java.lang.String message)
|
void |
setStatusMessage(java.lang.String message)
Set the status message displayed by the container to the given message |
void |
setStructureViewerDescriptor(org.eclipse.compare.internal.ViewerDescriptor vd)
|
void |
setTitle(java.lang.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 |
|---|
public static final java.lang.String DIRTY_STATE
"DIRTY_STATE").
public static final java.lang.String PROP_TITLE
getTitle()public static final java.lang.String PROP_TITLE_IMAGE
getTitleImage()public static final java.lang.String PROP_SELECTED_EDITION
isEditionSelectionDialog(),
getSelectedEdition()| Constructor Detail |
|---|
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 configuration| Method Detail |
|---|
public java.lang.Object getAdapter(java.lang.Class adapter)
PlatformObjectnull 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 IAdaptablegetAdapter in class PlatformObjectadapter - the class to adapt to
nullIAdaptable.getAdapter(Class)public ICompareNavigator getNavigator()
ICompareContainerICompareNavigator associated with this container or null
if the container does not have a global navigator.
getNavigator in interface ICompareContainerICompareNavigator associated with this container or nullpublic ImageDescriptor getImageDescriptor()
IEditorInputNote: 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 IEditorInputnull if
there is no image.public java.lang.String getToolTipText()
IEditorInput
getToolTipText in interface IEditorInputnull.public java.lang.String getName()
IEditorInputFor instance, when the input is from a file, the return value would ordinarily be just the file name.
getName in interface IEditorInputnull;public IPersistableElement getPersistable()
null since this editor cannot be persisted.
getPersistable in interface IEditorInputnull 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 IEditorInputfalseprotected void setMessage(java.lang.String message)
public java.lang.String getMessage()
public java.lang.String getTitle()
setTitle.
public void setTitle(java.lang.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 contribute
public void run(IProgressMonitor monitor)
throws java.lang.InterruptedException,
java.lang.reflect.InvocationTargetException
run in interface IRunnableWithProgressmonitor - the progress monitor to use to display progress and receive
requests for cancelation
java.lang.reflect.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
java.lang.InterruptedException - if the operation detects a request to cancel,
using IProgressMonitor.isCanceled(), it should exit by throwing
InterruptedExceptionIRunnableContext.run(boolean, boolean, org.eclipse.jface.operation.IRunnableWithProgress)
protected abstract java.lang.Object prepareInput(IProgressMonitor monitor)
throws java.lang.reflect.InvocationTargetException,
java.lang.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 cancelation
null if there are no differences
java.lang.reflect.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
java.lang.InterruptedException - if the operation detects a request to cancel,
using IProgressMonitor.isCanceled(), it should exit by throwing
InterruptedExceptionpublic java.lang.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 created
protected 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 viewer
protected 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
- Returns:
- the SWT control hierarchy for the outline part of the compare editor
- Since:
- 3.0
protected CompareViewerPane createStructureInputPane(Composite parent)
CompareViewerSwitchingPane is returned. Subclasses
may override to provide an alternate pane.
parent - the parent composite
public 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 controls
public 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 created
null
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 created
nullpublic 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.
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.
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.
dirty - the dirty state for this compare inputpublic void addPropertyChangeListener(IPropertyChangeListener listener)
IPropertyChangeNotifier
addPropertyChangeListener in interface IPropertyChangeNotifierlistener - a property change listenerpublic void removePropertyChangeListener(IPropertyChangeListener listener)
IPropertyChangeNotifier
removePropertyChangeListener in interface IPropertyChangeNotifierlistener - a property change listenerpublic void save(IProgressMonitor pm)
pm - an IProgressMonitor that the implementation of save may use to show progress
public void saveChanges(IProgressMonitor monitor)
throws CoreException
ISavable.save on them.
monitor - an IProgressMonitor that the implementation of save may use to show progress
CoreExceptionprotected void flushViewers(IProgressMonitor monitor)
monitor - a progress monitor
public void addCompareInputChangeListener(ICompareInput input,
ICompareInputChangeListener listener)
ICompareContainer
addCompareInputChangeListener in interface ICompareContainerinput - the compare inputlistener - the compare input change listener
public void removeCompareInputChangeListener(ICompareInput input,
ICompareInputChangeListener listener)
ICompareContainer
removeCompareInputChangeListener in interface ICompareContainerinput - the compare inputlistener - the compare input change listener
public void registerContextMenu(MenuManager menu,
ISelectionProvider selectionProvider)
ICompareContainerIWorkbenchActionConstants.MB_ADDITIONS
separator as this is where the container will add actions.
registerContextMenu in interface ICompareContainermenu - the menu being registeredselectionProvider - the selection providerpublic void setStatusMessage(java.lang.String message)
ICompareContainer
setStatusMessage in interface ICompareContainermessage - the status messagepublic IActionBars getActionBars()
ICompareContainernull if the container
does not have an action bars.
getActionBars in interface ICompareContainernullpublic IServiceLocator getServiceLocator()
ICompareContainernull if the container
does not have one.
getServiceLocator in interface ICompareContainernullpublic IWorkbenchPart getWorkbenchPart()
ICompareContainernull if there is no part or it is not available.
getWorkbenchPart in interface ICompareContainernull
public void run(boolean fork,
boolean cancelable,
IRunnableWithProgress runnable)
throws java.lang.reflect.InvocationTargetException,
java.lang.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 IRunnableContextfork - 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 run
java.lang.reflect.InvocationTargetException - wraps any exception or error which occurs
while running the runnable
java.lang.InterruptedException - 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)
ICompareContainerThis 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 ICompareContainerrunnable - the task to be performedpublic void setContainer(ICompareContainer container)
container - the containerpublic final ICompareContainer getContainer()
null if there is no container
set.
nullprotected 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(java.lang.Object family)
family - the job family
canRunAsJob(),
Job.belongsTo(Object)public boolean isEditionSelectionDialog()
false is returned.
getOKButtonLabel(),
okPressed(),
getSelectedEdition()public java.lang.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 java.lang.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 java.lang.Object getSelectedEdition()
null if no edition is selected.
The result of this method should only be considered if isEditionSelectionDialog()
returns true.
nullpublic void setHelpContextId(java.lang.String helpContextId)
helpContextId - the help context id.
|
Eclipse Platform Release 3.6 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2010. All rights reserved.