org.eclipse.compare.structuremergeviewer.ICompareInput Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.compare Show documentation
This is org.eclipse.compare jar used by Scout SDK
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2011 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
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.
 * 
 * Note: at most two sides of an ICompareInput can be null,
 * (as it is normal for additions or deletions) but not all three.
 * 

 * ICompareInput provides methods for registering
 * ICompareInputChangeListeners
 * that get informed if one (or more)
 * of the three sides of an ICompareInput object changes its value.
 * 

 * For example when accepting an incoming addition
 * the (non-null) left side of an ICompareInput
 * is copied to the right side by means of method copy.
 * This should trigger a call to compareInputChanged of registered
 * ICompareInputChangeListeners. 
 * 

 * Clients can implement this interface, or use the convenience implementation 
 * DiffNode.
 * 
 * 
 * @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-null 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-null sides.
	 *
	 * @return image representing this input, or null 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 ICompareInput
	 * is the result of another compare. In this case it is used
	 * together with getImage to compose a icon
	 * which reflects the kind of difference between the two or three elements.
	 *
	 * @return kind of difference (see Differencer)
	 */
	int getKind();
	
	/**
	 * Returns the ancestor side of this input.
	 * Returns null if this input has no ancestor
	 * or in the two-way compare case.
	 *
	 * @return the ancestor of this input, or null
	 */
	ITypedElement getAncestor();
	
	/**
	 * Returns the left side of this input.
	 * Returns null if there is no left side (deletion or addition).
	 *
	 * @return the left side of this input, or null
	 */
	ITypedElement getLeft();
	
	/**
	 * Returns the right side of this input.
	 * Returns null if there is no right side (deletion or addition).
	 *
	 * @return the right side of this input, or null
	 */
	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 leftToRight. This method is called from
	 * a merge viewer if a corresponding action ("take left" or "take right")
	 * has been pressed.
	 * 
	 * The implementation should handle the following cases:
	 * 

	 * 
	 * if the source side is null the destination must be deleted,
	 * 

	 * if the destination is null the destination must be created
	 * and filled with the contents from the source,
	 * 

	 * if both sides are non-null the contents of source must be copied to destination.
	 * 
	 * In addition the implementation should send out notification to the registered
	 * ICompareInputChangeListener.
	 * 
	 * @param leftToRight if true the left side is copied to the right side.
	 * If false the right side is copied to the left side
	 */
	void copy(boolean leftToRight);
}