1
|
/*******************************************************************************
|
2
|
* Copyright (c) 2006, 2010 IBM Corporation and others.
|
3
|
* All rights reserved. This program and the accompanying materials
|
4
|
* are made available under the terms of the Eclipse Public License v1.0
|
5
|
* which accompanies this distribution, and is available at
|
6
|
* http://www.eclipse.org/legal/epl-v10.html
|
7
|
*
|
8
|
* Contributors:
|
9
|
* IBM Corporation - initial API and implementation
|
10
|
*******************************************************************************/
|
11
|
|
12
|
package org.eclipse.ui.navigator;
|
13
|
|
14
|
import java.util.Set;
|
15
|
|
16
|
/**
|
17
|
*
|
18
|
* To correctly implement pipelining you should implement
|
19
|
* {@link IPipelinedTreeContentProvider2} which provides the
|
20
|
* additional
|
21
|
* {@link IPipelinedTreeContentProvider2#hasChildren(Object)} method.
|
22
|
* This allows the calculation of hasChildren to match what will be provided in
|
23
|
* calculating the children. If you don't implement the hasChildren, you may get
|
24
|
* "false positive" hasChildrens which will result in a "+" indication in the
|
25
|
* tree in the event that the pipelined children calculation.
|
26
|
*
|
27
|
* The only reason these are two separate interfaces is historical.
|
28
|
*
|
29
|
* @since 3.2
|
30
|
*
|
31
|
*/
|
32
|
public interface IPipelinedTreeContentProvider extends ICommonContentProvider {
|
33
|
|
34
|
/**
|
35
|
* Intercept the children that would be contributed to the viewer and
|
36
|
* determine how to change the shape of those children. The set of children
|
37
|
* should be modified to contain the correct children to return to the
|
38
|
* viewer.
|
39
|
*
|
40
|
* @param aParent
|
41
|
* A parent from the viewer
|
42
|
* @param theCurrentChildren
|
43
|
* The set of children contributed thus far from upstream content
|
44
|
* providers.
|
45
|
*/
|
46
|
void getPipelinedChildren(Object aParent, Set theCurrentChildren);
|
47
|
|
48
|
/**
|
49
|
* Intercept the elements that would be contributed to the root of the
|
50
|
* viewer and determine how to change the shape of those children. The given
|
51
|
* set of elements should be modified to contain the correct elements to
|
52
|
* return to the viewer.
|
53
|
*
|
54
|
* @param anInput
|
55
|
* An input from the viewer
|
56
|
* @param theCurrentElements
|
57
|
* The set of children contributed thus far from upstream content
|
58
|
* providers.
|
59
|
*/
|
60
|
void getPipelinedElements(Object anInput, Set theCurrentElements);
|
61
|
|
62
|
/**
|
63
|
* Intercept requests for a parent of the given object.
|
64
|
*
|
65
|
* @param anObject
|
66
|
* The object being queried for a parent.
|
67
|
* @param aSuggestedParent
|
68
|
* The parent already suggested from upstream extensions.
|
69
|
* @return The intended parent from this pipelined content provider. If you
|
70
|
* wish to not influence the parent, then return the
|
71
|
* aSuggestedParent value.
|
72
|
*/
|
73
|
Object getPipelinedParent(Object anObject, Object aSuggestedParent);
|
74
|
|
75
|
/**
|
76
|
* Intercept attempts to add elements directly to the viewer.
|
77
|
*
|
78
|
* <p>
|
79
|
* For content extensions that reshape the structure of children in a
|
80
|
* viewer, their overridden extensions may sometimes use optimized refreshes
|
81
|
* to add elements to the tree. These attempts must be intercepted and
|
82
|
* mapped to the correct set of model elements in the overriding extension.
|
83
|
* Clients may add, remove, or modify elements in the given set of added
|
84
|
* children. Clients should return a set for downstream extensions to
|
85
|
* massage further.
|
86
|
* </p>
|
87
|
* <p>
|
88
|
* Clients may change what parent the reshaped elements are added to, so
|
89
|
* long as that parent is not the root of the viewer.
|
90
|
* </p>
|
91
|
* <p>
|
92
|
* Clients should never create their own pipeline shape modifications, but
|
93
|
* instead return the shape modification that was passed in with appropriate
|
94
|
* changes.
|
95
|
* </p>
|
96
|
* <p>
|
97
|
* <b>Clients should not call any of the add, remove, refresh, or update
|
98
|
* methods on the viewer from this method or any code invoked by the
|
99
|
* implementation of this method.</b>
|
100
|
* </p>
|
101
|
*
|
102
|
* @param anAddModification
|
103
|
* The shape modification which contains the current suggested
|
104
|
* parent and children. Clients may modify this parameter
|
105
|
* directly and return it as the new shape modification.
|
106
|
* @return The new shape modification to use. Clients should <b>never</b>
|
107
|
* return <b>null</b> from this method.
|
108
|
*/
|
109
|
PipelinedShapeModification interceptAdd(PipelinedShapeModification anAddModification);
|
110
|
|
111
|
/**
|
112
|
* Intercept attempts to remove elements directly from the viewer.
|
113
|
*
|
114
|
* <p>
|
115
|
* For content extensions that reshape the structure of children in a
|
116
|
* viewer, their overridden extensions may sometimes use optimized refreshes
|
117
|
* to remove elements to the tree. These attempts must be intercepted and
|
118
|
* mapped to the correct set of model elements in the overriding extension.
|
119
|
* Clients may add, remove, or modify elements in the given set of removed
|
120
|
* children. Clients should return a set for downstream extensions to
|
121
|
* massage further.
|
122
|
* </p>
|
123
|
* <p>
|
124
|
* The parent will be <b>null</b> for remove modifications.
|
125
|
* <p>
|
126
|
* Clients should never create their own pipeline shape modifications, but
|
127
|
* instead return the shape modification that was passed in with appropriate
|
128
|
* changes.
|
129
|
* </p>
|
130
|
* <p>
|
131
|
* <b>Clients should not call any of the add, remove, refresh, or update
|
132
|
* methods on the viewer from this method or any code invoked by the
|
133
|
* implementation of this method.</b>
|
134
|
* </p>
|
135
|
*
|
136
|
* @param aRemoveModification
|
137
|
* The shape modification which contains the current suggested
|
138
|
* parent and children. Clients may modify this parameter
|
139
|
* directly and return it as the new shape modification.
|
140
|
* @return The new shape modification to use. Clients should <b>never</b>
|
141
|
* return <b>null</b> from this method.
|
142
|
*/
|
143
|
PipelinedShapeModification interceptRemove(PipelinedShapeModification aRemoveModification);
|
144
|
|
145
|
/**
|
146
|
* Intercept calls to viewer <code>refresh()</code> methods.
|
147
|
*
|
148
|
* <p>
|
149
|
* Clients may modify the given update to add or remove the elements to be
|
150
|
* refreshed. Clients may return the same instance that was passed in for
|
151
|
* the next downstream extension.
|
152
|
* </p>
|
153
|
*
|
154
|
* <p>
|
155
|
* <b>Clients should not call any of the add, remove, refresh, or update
|
156
|
* methods on the viewer from this method or any code invoked by the
|
157
|
* implementation of this method.</b>
|
158
|
* </p>
|
159
|
*
|
160
|
* @param aRefreshSynchronization
|
161
|
* The (current) refresh update to execute against the viewer.
|
162
|
* @return True if the viewer update was modified.
|
163
|
*/
|
164
|
boolean interceptRefresh(PipelinedViewerUpdate aRefreshSynchronization);
|
165
|
|
166
|
/**
|
167
|
* Intercept calls to viewer <code>update()</code> methods.
|
168
|
*
|
169
|
* <p>
|
170
|
* Clients may modify the given update to add or remove the elements to be
|
171
|
* updated. Clients may also add or remove properties for the given targets
|
172
|
* to optimize the refresh. Clients may return the same instance that was
|
173
|
* passed in for the next downstream extension.
|
174
|
* </p>
|
175
|
*
|
176
|
* <p>
|
177
|
* <b>Clients should not call any of the add, remove, refresh, or update
|
178
|
* methods on the viewer from this method or any code invoked by the
|
179
|
* implementation of this method.</b>
|
180
|
* </p>
|
181
|
*
|
182
|
* @param anUpdateSynchronization
|
183
|
* The (current) update to execute against the viewer.
|
184
|
* @return True if the viewer update was modified.
|
185
|
*/
|
186
|
boolean interceptUpdate(PipelinedViewerUpdate anUpdateSynchronization);
|
187
|
|
188
|
}
|