Changeset 821 for trunk/quest-core-events

Timestamp:

09/19/12 09:40:07 (12 years ago)

Author:

sherbold

Message:

• updated getChildren() and getParent() of GUIModel to issue warnings in case there looked-up GUI element exists multiple times in the internal GUI model.
• code documentation and clean-up

File:

• trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/guimodel/GUIModel.java (modified) (14 diffs)

trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/guimodel/GUIModel.java

@@ -8 +8 @@
 import java.util.LinkedList;
 import java.util.List;
+import java.util.logging.Level;
+
+import de.ugoe.cs.util.console.Console;
 
 /**
@@ -17 +20 @@
  * </p>
  * 
- * TODO: getChildren and getParent should be rewritten to at least throw warnings, in case there are
- * multiple nodes in allNodes that match the current GUI element.
- * 
- * @version $Revision: $ $Date: 14.08.2012$
+ * @version 1.0
  * @author Patrick Harms, Steffen Herbold
  */
@@ -110 +110 @@
      */
     public List<IGUIElement> getChildren(IGUIElement guiElement) {
+        List<IGUIElement> result = null;
         for (TreeNode node : allNodes) {
             if (node.guiElement.equals(guiElement)) {
-                List<IGUIElement> result = new ArrayList<IGUIElement>();
-
-                if (node.children != null) {
-                    for (TreeNode child : node.children) {
-                        result.add(child.guiElement);
+                if (result == null) {
+                    result = new ArrayList<IGUIElement>();
+
+                    if (node.children != null) {
+                        for (TreeNode child : node.children) {
+                            result.add(child.guiElement);
+                        }
                     }
                 }
-
-                return result;
-            }
-        }
-
-        return null;
+                else {
+                    Console
+                        .traceln(Level.SEVERE,
+                                 "Multiple nodes in the internal GUI model match the same GUI element. "
+                                     + "This should not be the case and the GUI model is probably invalid.");
+                }
+            }
+        }
+
+        return result;
     }
 
@@ -139 +146 @@
      */
     public IGUIElement getParent(IGUIElement guiElement) {
+        IGUIElement parent = null;
+
         for (TreeNode node : allNodes) {
             for (TreeNode child : node.children) {
                 if (child.guiElement.equals(guiElement)) {
-                    return node.guiElement;
+                    if (parent != null) {
+                        parent = node.guiElement;
+                    }
+                    else {
+                        Console
+                            .traceln(Level.SEVERE,
+                                     "Multiple nodes in the internal GUI model match the same GUI element. "
+                                         + "This should not be the case and the GUI model is probably invalid.");
+                    }
                 }
             }
         }
 
-        return null;
+        return parent;
     }
 
@@ -203 +220 @@
     /**
      * <p>
-     * TODO: comment
+     * By calling this method, the GUIModel is traversed and similar nodes are merged.
      * </p>
      * 
      */
     public void condenseModel() {
-        mergeSimilarChildren(root);
+        mergeSubTree(root);
     }
 
@@ -238 +255 @@
 
         TreeNode child = findEqualChild(parentNode, specToIntegrateElementFor);
-        if (child != null) {
-            // TODO this call should be deprecated and change nothing
-            child.guiElement.updateSpecification(specToIntegrateElementFor);
-        }
-        else {
+        if (child == null) {
             IGUIElement newElement =
                 guiElementFactory.instantiateGUIElement(specToIntegrateElementFor,
@@ -260 +273 @@
     /**
      * <p>
-     * TODO: comment
-     * </p>
-     * 
-     * @param parentNode
-     * @param specToMatch
-     * @return
+     * Searches the children of a tree node to see if the {@link IGUIElementSpec} of equals the
+     * specification of the {@link TreeNode#guiElement} of the child. If a match is found, the child
+     * is returned.
+     * </p>
      */
     private TreeNode findEqualChild(TreeNode parentNode, IGUIElementSpec specToMatch) {
@@ -280 +291 @@
     /**
      * <p>
-     * merges similar children of a parent node. The method compares all children of the parent node
-     * with each other. If two of them are similar, it merges them, registers them with each other
-     * for equality checks, and removes one of them from the list of children.
-     * </p>
-     */
-    private void mergeSimilarChildren(TreeNode parentNode) {
-        if (parentNode.children == null || parentNode.children.isEmpty()) {
+     * Merges all similar nodes in the sub-tree of the GUI model defined by the subTreeRoot.
+     * </p>
+     * <p>
+     * The merging order is a bottom-up. This means, that we first call mergeSubTree recursively for
+     * the grand children of the subTreeRoot, before we merge subTreeRoot.
+     * </p>
+     * <p>
+     * The merging strategy is top-down. This means, that every time we merge two child nodes, we
+     * call mergeSubTree recursively for all children of the merged nodes in order to check if we
+     * can merge the children, too.
+     * </p>
+     */
+    private void mergeSubTree(TreeNode subTreeRoot) {
+        if (subTreeRoot.children == null || subTreeRoot.children.isEmpty()) {
             return;
         }
 
-        // lets first merge the grandchildren
-        for (TreeNode child : parentNode.children) {
-            mergeSimilarChildren(child);
+        // lets first merge the grand children of the parentNode
+        for (TreeNode child : subTreeRoot.children) {
+            mergeSubTree(child);
         }
 
@@ -299 +317 @@
         do {
             performedMerge = false;
-            for (int i = 0; !performedMerge && i < parentNode.children.size(); i++) {
+            for (int i = 0; !performedMerge && i < subTreeRoot.children.size(); i++) {
                 IGUIElementSpec elemSpec1 =
-                    parentNode.children.get(i).guiElement.getSpecification();
-                for (int j = i + 1; !performedMerge && j < parentNode.children.size(); j++) {
+                    subTreeRoot.children.get(i).guiElement.getSpecification();
+                for (int j = i + 1; !performedMerge && j < subTreeRoot.children.size(); j++) {
                     IGUIElementSpec elemSpec2 =
-                        parentNode.children.get(j).guiElement.getSpecification();
+                        subTreeRoot.children.get(j).guiElement.getSpecification();
                     if (elemSpec1.getSimilarity(elemSpec2)) {
                         TreeNode replacement =
-                            mergeTreeNodes(parentNode.children.get(i), parentNode.children.get(j));
-
-                        parentNode.children.set(i, replacement);
-                        parentNode.children.remove(j);
+                            mergeTreeNodes(subTreeRoot.children.get(i), subTreeRoot.children.get(j));
+
+                        subTreeRoot.children.set(i, replacement);
+                        subTreeRoot.children.remove(j);
                         performedMerge = true;
                         i--;
@@ -344 +362 @@
         if (treeNode1.children != null) {
             for (TreeNode child : treeNode1.children) {
-                // replacement.addChild(child.guiElement);
                 replacement.addChildNode(child);
             }
@@ -350 +367 @@
         if (treeNode2.children != null) {
             for (TreeNode child : treeNode2.children) {
-                // replacement.addChild(child.guiElement);
                 replacement.addChildNode(child);
             }
         }
 
-        mergeSimilarChildren(replacement);
+        mergeSubTree(replacement);
 
         replacement.guiElement.updateSpecification(treeNode2.guiElement.getSpecification());
@@ -405 +421 @@
         /** */
         private List<TreeNode> children;
-
-        /** */
-        // private TreeNode parent;
 
         /**
@@ -421 +434 @@
             TreeNode child = new TreeNode();
             child.guiElement = guiElement;
-            // child.parent = this;
             children.add(child);
 
@@ -432 +444 @@
          * 
          * <p>
-         * TODO: comment
+         * Adds a TreeNode as child to the current node. This way, the whole sub-tree is added.
          * </p>
-         * 
-         * @param node
-         * @return
          */
         private TreeNode addChildNode(TreeNode node) {