- * The goal of a GUI model is to correctly l + * A GUI model is a tree of {@link IGUIElements} and represents a complete GUI of a software. It is + * platform independent. It may have several root nodes, as some GUIs are made up of several Frames + * being independent from each other. The GUI model is filled using the + * {@link #integratePath(List, IGUIElementFactory)} method. *
* @@ -18,23 +25,61 @@ /** - * + *+ * the root node of the tree not provided externally. + *
*/ private TreeNode root = new TreeNode(); /** + *+ * a list with all nodes currently known + *
+ */ + private List+ * Integrates a path of GUI elements into the GUI model. The GUI model itself is a tree and + * therefore a set of different paths through the tree that start with a root node and end with + * a leaf node. Such a path can be added to the tree. The method checks, if any of the GUI + * elements denoted by the path already exists. If so, it reuses it. It may therefore also + * return an existing GUI element being the leaf node of the provided path. If a GUI element + * of the path does not exist yet, it creates a new one using the provided GUI element factory. + *
+ *+ * If a GUI element specification describes an existing GUI element or not is determined + * through comparing the GUI element specifications of the existing GUI elements with the + * ones provided in the path. The comparison is done using the + * {@link IGUIElementSpec#getSimilarity(IGUIElementSpec)} method. The comparison is only done + * on the correct levels. I.e. the currently known root elements of the tree are only compared + * to the first element in the path. If the correct one is found or created, its children are + * compared only to the second specification in the path, and so on. + *
+ *+ * The returned GUI elements are singletons. I.e. it is tried to return always the identical + * object for the same denoted element. However, while creating the GUI model, the similarity + * of GUI elements may change. Therefore, the method might determine, that two formerly + * different nodes are now similar. (This may happen, e.g. if GUI elements do not have initial + * names which are set afterwards. Therefore, first they are handled differently and later + * they can be identified as being the same.) In such a case, there are already several GUI + * element objects instantiated for the same GUI element. The singleton paradigm gets broken. + * Therefore, such GUI element objects are registered with each other, so that their equal + * method can determine equality again correctly, although the objects are no singletons + * anymore. + *
+ * + * @param guiElementPath the path to integrate into the model + * @param guiElementFactory the GUI element factory to be used for instantiating GUI element + * objects + * + * @return The GUI element object representing the GUI element denoted by the provided path * - */ - private List+ * Returns all children of the provided GUI element or null, if it does not have any or the + * node is unknown. + *
+ * + * @param guiElement the GUI element of which the children shall be returned + * + * @return As described */ public List- * TODO: comment - *
- * - * @param guiElement - * @return + * Returns the parent GUI element of the provided GUI element or null, if it does not have a + * parent (i.e. if it is a root node) or if the node is unknown. + * + * + * @param guiElement the GUI element of which the parent shall be returned + * + * @return As described */ public IGUIElement getParent(IGUIElement guiElement) { @@ -98,7 +149,9 @@ /** - * TODO: comment - * - * @return + *+ * Returns all root GUI elements of the model or an empty list, if the model is empty + *
+ * + * @return As described */ public List+ * dumps the GUI model to the provided stream. Each node is represented through its toString() + * method. If a node has children, those are dumped indented and surrounded by braces. + *
+ * + * @param out The stream to dump the textual representation of the model to + * @param encoding The encoding to be used while dumping + */ + public void dump(OutputStream out, String encoding) { PrintStream stream; @@ -126,5 +183,11 @@ } else { - stream = new PrintStream(out); + String enc = encoding == null ? "UTF-8" : encoding; + try { + stream = new PrintStream(out, true, enc); + } + catch (UnsupportedEncodingException e) { + stream = new PrintStream(out); + } } @@ -136,12 +199,18 @@ /** *- * TODO: comment - *
- * - * @param root2 - * @param guiElementPath - * @param guiElementFactory - * @return - * @throws GUIModelException + * internally integrates a path as the children of the provided parent node. This method + * is recursive and calls itself, for the child of the parent node, that matches the first + * element in the remaining path. + * + * + * @param parentNode the parent node to add children for + * @param guiElementPath the path of children to be created starting with the parent node + * @param guiElementFactory the GUI element factory to be used for instantiating GUI element + * objects + * + * @return The GUI element object representing the GUI element denoted by the provided path + * + * @throws GUIModelException thrown in cases such as the GUI element object could not be + * instantiated */ private IGUIElement integratePath(TreeNode parentNode, @@ -174,14 +243,13 @@ // based on the children of the existing and new GUI elements. The one for which // the existing children match best is selected to be the right one. - similarNodes = - considerSubChildren(similarNodes, specToIntegrateElementFor, remainingPath); + similarNodes = considerSubChildren(similarNodes, remainingPath); if (similarNodes.size() > 1) { - System.out.println("TODO: implement handling to many similar children: " + - specToIntegrateElementFor); + Console.traceln(Level.WARNING, "TODO: implement handling to many similar" + + "children: " + specToIntegrateElementFor); for (TreeNode similarNode : similarNodes) { - System.out.println(" " + similarNode.guiElement); + Console.traceln(Level.WARNING, " " + similarNode.guiElement); } - System.out.println(); + Console.traceln(Level.WARNING, ""); } } @@ -208,10 +276,7 @@ /** *- * TODO: comment - *
- * - * @param parentNode - * @param specToIntegrateElementFor - * @return + * Determines all children of the provided node, which are similar to the provided + * specification. + * */ private List- * TODO: comment - *
- * - * @param similarChildren - * @param remove - * @return + * This method is called in the case, that several child nodes of a parent node are similar + * to a node to be integrated into the model. This method tries to determine the similar child + * nodes of which the sub children match best to the further path to be integrated. This method + * does nothing, if the similar children do not have children yet of if the remaining path + * does not denote further children. + * + * + * @return a hopefully reduced list of similar nodes based on their children. */ private List- * TODO: comment - *
- * - * @param parentNode + * 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. + * */ private void mergeSimilarChildren(TreeNode parentNode) { @@ -309,10 +375,10 @@ /** *- * TODO: comment - *
- * - * @param treeNode - * @param treeNode2 - * @return + * merges two nodes with each other. Merging means registering the GUI element objects with + * each other for equality checks. Further it add all children of both nodes to a new + * replacing node. Afterwards, all similar nodes of the replacement node are merged as well. + * + * + * @return a tree node being the merge of the two provided nodes. */ private TreeNode mergeTreeNodes(TreeNode treeNode1, TreeNode treeNode2) { @@ -349,8 +415,8 @@ /** - * TODO: comment - * - * @param root - * @param root2 + *+ * dumps a GUI element to the stream. A dump contains the toString() representation of the + * GUI element as well as a indented list of its children surrounded by braces. + *
*/ private void dumpGUIElement(PrintStream out, IGUIElement guiElement, String indent) { @@ -376,9 +442,6 @@ /** *- * TODO comment - *
- * - * @version $Revision: $ $Date: 17.08.2012$ - * @author 2012, last modified by $Author: pharms$ + * used internally for building up the tree of GUI elements. + * */ private class TreeNode @@ -395,9 +458,6 @@ /** *- * TODO: comment + * adds a child to the current node while keeping all lists of nodes up to date *
- * - * @param guiElement - * @return */ private TreeNode addChild(IGUIElement guiElement)