/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved. | |
*/ | |
package org.eclipse.compare.structuremergeviewer; | |
import org.eclipse.compare.ITypedElement; | |
import org.eclipse.swt.graphics.Image; | |
/** | |
* Interface for objects used as input to a two-way or three-way compare viewer. | |
* It defines API for accessing the three sides for the compare, | |
* and a name and image which is used when displaying the three way input | |
* in the UI, for example, in a title bar. | |
* <p> | |
* Note: at most two sides of an <code>ICompareInput</code> can be <code>null</code>, | |
* (as it is normal for additions or deletions) but not all three. | |
* <p> | |
* <code>ICompareInput</code> provides methods for registering | |
* <code>ICompareInputChangeListener</code>s | |
* that get informed if one (or more) | |
* of the three sides of an <code>ICompareInput</code> object changes its value. | |
* <p> | |
* For example when accepting an incoming addition | |
* the (non-<code>null</code>) left side of an <code>ICompareInput</code> | |
* is copied to the right side by means of method <code>copy</code>. | |
* This should trigger a call to <code>compareInputChanged</code> of registered | |
* <code>ICompareInputChangeListener</code>s. | |
* <p> | |
* Clients can implement this interface, or use the convenience implementation | |
* <code>DiffNode</code>. | |
* </p> | |
* | |
* @see StructureDiffViewer | |
* @see org.eclipse.compare.contentmergeviewer.ContentMergeViewer | |
* @see DiffNode | |
*/ | |
public interface ICompareInput { | |
/** | |
* Returns name of input. | |
* This name is displayed when this input is shown in a viewer. | |
* In many cases this name is the name of one of the non-<code>null</code> sides or a combination | |
* thereof. | |
* | |
* @return name of input | |
*/ | |
String getName(); | |
/** | |
* Returns an image representing this input. | |
* This image is typically displayed when this input is shown in a viewer. | |
* In many cases this image is the image of one of the non-<code>null</code> sides. | |
* | |
* @return image representing this input, or <code>null</code> if no icon should be shown | |
*/ | |
Image getImage(); | |
/** | |
* Returns the kind of difference between the | |
* three sides ancestor, left and right. | |
* This field is only meaningful if the <code>ICompareInput</code> | |
* is the result of another compare. In this case it is used | |
* together with <code>getImage</code> to compose a icon | |
* which reflects the kind of difference between the two or three elements. | |
* | |
* @return kind of difference (see <code>Differencer</code>) | |
*/ | |
int getKind(); | |
/** | |
* Returns the ancestor side of this input. | |
* Returns <code>null</code> if this input has no ancestor | |
* or in the two-way compare case. | |
* | |
* @return the ancestor of this input, or <code>null</code> | |
*/ | |
ITypedElement getAncestor(); | |
/** | |
* Returns the left side of this input. | |
* Returns <code>null</code> if there is no left side (deletion or addition). | |
* | |
* @return the left side of this input, or <code>null</code> | |
*/ | |
ITypedElement getLeft(); | |
/** | |
* Returns the right side of this input. | |
* Returns <code>null</code> if there is no right side (deletion or addition). | |
* | |
* @return the right side of this input, or <code>null</code> | |
*/ | |
ITypedElement getRight(); | |
/** | |
* Registers the given listener for notification. | |
* If the identical listener is already registered the method has no effect. | |
* | |
* @param listener the listener to register for changes of this input | |
*/ | |
void addCompareInputChangeListener(ICompareInputChangeListener listener); | |
/** | |
* Unregisters the given listener. | |
* If the identical listener is not registered the method has no effect. | |
* | |
* @param listener the listener to unregister | |
*/ | |
void removeCompareInputChangeListener(ICompareInputChangeListener listener); | |
/** | |
* Copy one side (source) to the other side (destination) depending on the | |
* value of <code>leftToRight</code>. This method is called from | |
* a merge viewer if a corresponding action ("take left" or "take right") | |
* has been pressed. | |
* <p> | |
* The implementation should handle the following cases: | |
* <UL> | |
* <LI> | |
* if the source side is <code>null</code> the destination must be deleted, | |
* <LI> | |
* if the destination is <code>null</code> the destination must be created | |
* and filled with the contents from the source, | |
* <LI> | |
* if both sides are non-<code>null</code> the contents of source must be copied to destination. | |
* </UL> | |
* In addition the implementation should send out notification to the registered | |
* <code>ICompareInputChangeListener</code>. | |
* | |
* @param leftToRight if <code>true</code> the left side is copied to the right side. | |
* If <code>false</code> the right side is copied to the left side | |
*/ | |
void copy(boolean leftToRight); | |
} | |