diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java index f5c41273d5f..4eabc6cdb49 100644 --- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java +++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/DefaultVMModelProxyStrategy.java @@ -259,6 +259,10 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy { * determine how elements of those types may be (or are) affected by * [event], the answer being a collection of IModelDelta flags. * + * A response of IModeDelta.CONTENT has a special meaning. If we return that + * flag for an IVMNode, it means the collection of elements of that + * type are affected. It is not a statement on the elements themselves. + * * Optimization 1: If the first-level child node does not have * IModelDelta.CONTENT but one of its descendants does, then * for optimization reasons we return IModelDelta.STATE @@ -621,25 +625,30 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy { } } - /** - * Calls the specified child nodes to build the delta for the given event. - * @param childNodes Map of nodes to be invoked, and the corresponding delta - * flags that they will generate. This map is generated with a call to - * {@link #getChildNodesWithDeltaFlags(Object)}. - * @param delta The delta object to build on. This delta should have been - * generated by this node, unless the full delta path is not being calculated - * due to an optimization. - * @param event The event object that the delta is being built for. - * @param rm The result token to invoke when the delta is completed. - */ + /** + * Calls the specified child nodes (of [node]) to build the delta for the + * given event. + * + * @param childNodes + * Map of nodes to be invoked, and the corresponding delta flags + * that they may (or will) generate. This map is generated with a + * call to {@link #getChildNodesWithDeltaFlags(Object)}. + * @param delta + * The delta object to build on. This delta should have been + * generated by this node, unless the full delta path is not + * being calculated due to an optimization. + * @param event + * The event object that the delta is being built for. + * @param rm + * The result monitor to invoke when the delta is completed. + */ protected void callChildNodesToBuildDelta(final IVMNode node, final Map childNodes, final VMDelta delta, final Object event, final RequestMonitor rm) { assert childNodes.size() != 0; - // Check if any of the child nodes are will generate IModelDelta.SELECT or - // IModelDelta.EXPAND flags. If so, we must calculate the index for this - // VMC. + // Check if any of the child nodes might generate a delta that requires + // us to calculate the index for this VMC. boolean calculateOffsets = false; for (int childDelta : childNodes.values()) { if ( (childDelta & (IModelDelta.SELECT | IModelDelta.EXPAND | IModelDelta.INSERTED | IModelDelta.REMOVED)) != 0 ) { @@ -752,7 +761,8 @@ public class DefaultVMModelProxyStrategy implements IVMModelProxy { /** * Convenience method that returns what each of the child nodes returns from - * {@link #getDeltaFlags(IVMNode, ModelDelta, Object)}. + * {@link #getDeltaFlags(IVMNode, ModelDelta, Object)}. Children that return + * IModelDelta.NO_CHANGE are omitted. */ protected Map getChildNodesWithDeltaFlags(IVMNode node, ModelDelta parentDelta, Object e) { Map nodes = new HashMap(); diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java index 09452c03bec..f380088ae6a 100644 --- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java +++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/IVMNode.java @@ -52,45 +52,64 @@ public interface IVMNode extends IElementContentProvider * Retrieves the view model provider that this node is configured with. */ public IVMProvider getVMProvider(); - - /** - * Returns the potential delta flags that would be generated by this node - * for the given event. - * @param event Event to process. - * @return IModelDelta flags - * @see #buildDelta(Object, VMDelta, int, RequestMonitor) - * @see IModelDelta - */ + + /** + * Returns a set of IModelDelta delta flags that indicate how elements of + * this node (type) may be, or are, affected by the given event. If the + * implementation cannot make a definitive assessment synchronously, then it + * should provide the "worst case scenario" (all ways in which the elements + * may be affected). If a delta flag is not returned, it means for + * certain that elements of this node will not be affected in that way. That + * information allows us to optimize the delta creation. + * + *

+ * A response of IModeDelta.CONTENT has a special meaning. If we return that + * flag, it means the collection of elements of our type are + * affected. It is not a statement on the elements themselves. + * + * @param event + * the event the caller is processing + * @return IModelDelta flags + * @see #buildDelta(Object, VMDelta, int, RequestMonitor) + * @see IModelDelta + */ public int getDeltaFlags(Object event); - - /** - * Builds model delta information based on the given event. - *

- * Model deltas, which are used to control the state of elements in the viewer, are - * generated by the layout nodes by recursively calling this method on all the nodes - * in the layout tree. Each node implements two methods: {@link #getDeltaFlags(Object)}, - * and buildDelta(). A parent node which is processing a - * buildDelta operation needs to determine which of its elements are - * affected by a given event, set appropriate flags on these elements, and then - * it needs to call its child nodes with those elements to give the child nodes a - * chance to add onto the delta. - *

- *

- * The getDeltaFlags() is a synchronous - * call which tells the parent node whether on not to call the child node's - * buildDelta with the given event. If a child node return - * true, it only indicates that the node may add delta flags, but it - * does not require it to do so. - *

- * - * @param event Event to process. - * @param parent Parent model delta node that this object should add delta - * data to. - * @param nodeOffset The offset of the first element in this node. This offset - * depends on the elements returned by the siblings of this layout node. - * @param requestMonitor Return token, which notifies the caller that the calculation is - * complete. - */ + + /** + * Builds model delta information based on the given event. + *

+ * Model deltas, which are used to control the state of elements in the + * viewer, are generated by the layout nodes by recursively calling this + * method on all the nodes in the layout tree. Each node implements two + * methods: {@link #getDeltaFlags(Object)}, and buildDelta(). A + * parent node which is processing a buildDelta operation needs + * to determine which of its elements are affected by a given event, set + * appropriate flags on these elements, and then it needs to call its child + * nodes with those elements to give the child nodes a chance to add onto + * the delta. + *

+ *

+ * The getDeltaFlags() is a synchronous call which tells the + * parent node whether on not it needs to call us for a given child node, + * given the event it is processing. If a child node returns something other + * than IModelDelta.NO_CHANGE, then it is providing the set of flags that we + * might end up adding to the delta, but it doesn't mean we are + * obligated to or will. + *

+ * + * @param event + * Event to process. + * @param parent + * Parent model delta node that this object should add delta data + * to. + * @param nodeOffset + * The offset of the first element in this node. This offset + * depends on the elements returned by the siblings of this + * layout node. + * @param requestMonitor + * Return token, which notifies the caller that the calculation + * is complete. + */ public void buildDelta(Object event, VMDelta parent, int nodeOffset, RequestMonitor requestMonitor); /**