1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
/*******************************************************************************
* Copyright (c) 2000, 2006 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.
* <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);
}
|
