Changeset 746
- Timestamp:
- 09/03/12 10:20:16 (12 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/quest-core-events/src/main/java/de/ugoe/cs/quest/eventcore/guimodel/GUIModel.java
r709 r746 3 3 import java.io.OutputStream; 4 4 import java.io.PrintStream; 5 import java.io.UnsupportedEncodingException; 5 6 import java.util.ArrayList; 6 7 import java.util.LinkedList; 7 8 import java.util.List; 9 import java.util.logging.Level; 10 11 import de.ugoe.cs.util.console.Console; 8 12 9 13 /** 10 14 * <p> 11 * The goal of a GUI model is to correctly l 15 * A GUI model is a tree of {@link IGUIElements} and represents a complete GUI of a software. It is 16 * platform independent. It may have several root nodes, as some GUIs are made up of several Frames 17 * being independent from each other. The GUI model is filled using the 18 * {@link #integratePath(List, IGUIElementFactory)} method. 12 19 * </p> 13 20 * … … 18 25 19 26 /** 20 * 27 * <p> 28 * the root node of the tree not provided externally. 29 * </p> 21 30 */ 22 31 private TreeNode root = new TreeNode(); 23 32 24 33 /** 34 * <p> 35 * a list with all nodes currently known 36 * </p> 37 */ 38 private List<TreeNode> allNodes = new ArrayList<TreeNode>(); 39 40 /** 41 * <p> 42 * Integrates a path of GUI elements into the GUI model. The GUI model itself is a tree and 43 * therefore a set of different paths through the tree that start with a root node and end with 44 * a leaf node. Such a path can be added to the tree. The method checks, if any of the GUI 45 * elements denoted by the path already exists. If so, it reuses it. It may therefore also 46 * return an existing GUI element being the leaf node of the provided path. If a GUI element 47 * of the path does not exist yet, it creates a new one using the provided GUI element factory. 48 * </p> 49 * <p> 50 * If a GUI element specification describes an existing GUI element or not is determined 51 * through comparing the GUI element specifications of the existing GUI elements with the 52 * ones provided in the path. The comparison is done using the 53 * {@link IGUIElementSpec#getSimilarity(IGUIElementSpec)} method. The comparison is only done 54 * on the correct levels. I.e. the currently known root elements of the tree are only compared 55 * to the first element in the path. If the correct one is found or created, its children are 56 * compared only to the second specification in the path, and so on. 57 * </p> 58 * <p> 59 * The returned GUI elements are singletons. I.e. it is tried to return always the identical 60 * object for the same denoted element. However, while creating the GUI model, the similarity 61 * of GUI elements may change. Therefore, the method might determine, that two formerly 62 * different nodes are now similar. (This may happen, e.g. if GUI elements do not have initial 63 * names which are set afterwards. Therefore, first they are handled differently and later 64 * they can be identified as being the same.) In such a case, there are already several GUI 65 * element objects instantiated for the same GUI element. The singleton paradigm gets broken. 66 * Therefore, such GUI element objects are registered with each other, so that their equal 67 * method can determine equality again correctly, although the objects are no singletons 68 * anymore. 69 * </p> 70 * 71 * @param guiElementPath the path to integrate into the model 72 * @param guiElementFactory the GUI element factory to be used for instantiating GUI element 73 * objects 74 * 75 * @return The GUI element object representing the GUI element denoted by the provided path 25 76 * 26 */ 27 private List<TreeNode> allNodes = new ArrayList<TreeNode>(); 28 29 /** 30 * TODO: comment 31 * 32 * @param currentGUIElementPath 33 * @return 34 * @throws GUIModelException 77 * @throws GUIModelException thrown in cases such as the GUI element object could not be 78 * instantiated 79 * @throws IllegalArgumentException if the provided path is invalid. 35 80 */ 36 81 public IGUIElement integratePath(List<? extends IGUIElementSpec> guiElementPath, 37 82 IGUIElementFactory guiElementFactory) 38 throws GUIModelException 83 throws GUIModelException, IllegalArgumentException 39 84 { 40 85 if ((guiElementPath == null) || (guiElementPath.size() <= 0)) { … … 54 99 55 100 /** 56 * TODO: comment 57 * 58 * @param root 59 * @return 101 * <p> 102 * Returns all children of the provided GUI element or null, if it does not have any or the 103 * node is unknown. 104 * </p> 105 * 106 * @param guiElement the GUI element of which the children shall be returned 107 * 108 * @return As described 60 109 */ 61 110 public List<IGUIElement> getChildren(IGUIElement guiElement) { … … 79 128 /** 80 129 * <p> 81 * TODO: comment 82 * </p> 83 * 84 * @param guiElement 85 * @return 130 * Returns the parent GUI element of the provided GUI element or null, if it does not have a 131 * parent (i.e. if it is a root node) or if the node is unknown. 132 * </p> 133 * 134 * @param guiElement the GUI element of which the parent shall be returned 135 * 136 * @return As described 86 137 */ 87 138 public IGUIElement getParent(IGUIElement guiElement) { … … 98 149 99 150 /** 100 * TODO: comment 101 * 102 * @return 151 * <p> 152 * Returns all root GUI elements of the model or an empty list, if the model is empty 153 * </p> 154 * 155 * @return As described 103 156 */ 104 157 public List<IGUIElement> getRootElements() { … … 115 168 116 169 /** 117 * TODO: comment 118 * 119 * @return 120 */ 121 public void dump(OutputStream out) { 170 * <p> 171 * dumps the GUI model to the provided stream. Each node is represented through its toString() 172 * method. If a node has children, those are dumped indented and surrounded by braces. 173 * </p> 174 * 175 * @param out The stream to dump the textual representation of the model to 176 * @param encoding The encoding to be used while dumping 177 */ 178 public void dump(OutputStream out, String encoding) { 122 179 PrintStream stream; 123 180 … … 126 183 } 127 184 else { 128 stream = new PrintStream(out); 185 String enc = encoding == null ? "UTF-8" : encoding; 186 try { 187 stream = new PrintStream(out, true, enc); 188 } 189 catch (UnsupportedEncodingException e) { 190 stream = new PrintStream(out); 191 } 129 192 } 130 193 … … 136 199 /** 137 200 * <p> 138 * TODO: comment 139 * </p> 140 * 141 * @param root2 142 * @param guiElementPath 143 * @param guiElementFactory 144 * @return 145 * @throws GUIModelException 201 * internally integrates a path as the children of the provided parent node. This method 202 * is recursive and calls itself, for the child of the parent node, that matches the first 203 * element in the remaining path. 204 * </p> 205 * 206 * @param parentNode the parent node to add children for 207 * @param guiElementPath the path of children to be created starting with the parent node 208 * @param guiElementFactory the GUI element factory to be used for instantiating GUI element 209 * objects 210 * 211 * @return The GUI element object representing the GUI element denoted by the provided path 212 * 213 * @throws GUIModelException thrown in cases such as the GUI element object could not be 214 * instantiated 146 215 */ 147 216 private IGUIElement integratePath(TreeNode parentNode, … … 174 243 // based on the children of the existing and new GUI elements. The one for which 175 244 // the existing children match best is selected to be the right one. 176 similarNodes = 177 considerSubChildren(similarNodes, specToIntegrateElementFor, remainingPath); 245 similarNodes = considerSubChildren(similarNodes, remainingPath); 178 246 179 247 if (similarNodes.size() > 1) { 180 System.out.println("TODO: implement handling to many similar children:" +181 248 Console.traceln(Level.WARNING, "TODO: implement handling to many similar" + 249 "children: " + specToIntegrateElementFor); 182 250 for (TreeNode similarNode : similarNodes) { 183 System.out.println(" " + similarNode.guiElement);251 Console.traceln(Level.WARNING, " " + similarNode.guiElement); 184 252 } 185 System.out.println();253 Console.traceln(Level.WARNING, ""); 186 254 } 187 255 } … … 208 276 /** 209 277 * <p> 210 * TODO: comment 211 * </p> 212 * 213 * @param parentNode 214 * @param specToIntegrateElementFor 215 * @return 278 * Determines all children of the provided node, which are similar to the provided 279 * specification. 280 * </p> 216 281 */ 217 282 private List<TreeNode> determineSimilarChildNodes(TreeNode parentNode, … … 233 298 /** 234 299 * <p> 235 * TODO: comment 236 * </p> 237 * 238 * @param similarChildren 239 * @param remove 240 * @return 300 * This method is called in the case, that several child nodes of a parent node are similar 301 * to a node to be integrated into the model. This method tries to determine the similar child 302 * nodes of which the sub children match best to the further path to be integrated. This method 303 * does nothing, if the similar children do not have children yet of if the remaining path 304 * does not denote further children. 305 * </p> 306 * 307 * @return a hopefully reduced list of similar nodes based on their children. 241 308 */ 242 309 private List<TreeNode> considerSubChildren(List<TreeNode> similarNodes, 243 IGUIElementSpec specToMatch,244 310 List<? extends IGUIElementSpec> remainingPath) 245 311 { … … 276 342 /** 277 343 * <p> 278 * TODO: comment279 * </p>280 * 281 * @param parentNode344 * merges similar children of a parent node. The method compares all children of the parent 345 * node with each other. If two of them are similar, it merges them, registers them with each 346 * other for equality checks, and removes one of them from the list of children. 347 * </p> 282 348 */ 283 349 private void mergeSimilarChildren(TreeNode parentNode) { … … 309 375 /** 310 376 * <p> 311 * TODO: comment312 * </p>313 * 314 * @param treeNode315 * @param treeNode2316 * @return 377 * merges two nodes with each other. Merging means registering the GUI element objects with 378 * each other for equality checks. Further it add all children of both nodes to a new 379 * replacing node. Afterwards, all similar nodes of the replacement node are merged as well. 380 * </p> 381 * 382 * @return a tree node being the merge of the two provided nodes. 317 383 */ 318 384 private TreeNode mergeTreeNodes(TreeNode treeNode1, TreeNode treeNode2) { … … 349 415 350 416 /** 351 * TODO: comment352 * 353 * @param root354 * @param root2417 * <p> 418 * dumps a GUI element to the stream. A dump contains the toString() representation of the 419 * GUI element as well as a indented list of its children surrounded by braces. 420 * </p> 355 421 */ 356 422 private void dumpGUIElement(PrintStream out, IGUIElement guiElement, String indent) { … … 376 442 /** 377 443 * <p> 378 * TODO comment 379 * </p> 380 * 381 * @version $Revision: $ $Date: 17.08.2012$ 382 * @author 2012, last modified by $Author: pharms$ 444 * used internally for building up the tree of GUI elements. 445 * </p> 383 446 */ 384 447 private class TreeNode … … 395 458 /** 396 459 * <p> 397 * TODO: comment460 * adds a child to the current node while keeping all lists of nodes up to date 398 461 * </p> 399 *400 * @param guiElement401 * @return402 462 */ 403 463 private TreeNode addChild(IGUIElement guiElement)
Note: See TracChangeset
for help on using the changeset viewer.