Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 93 insertions, 0 deletions

diff --git a/documentation/components/components-tree.asciidoc b/documentation/components/components-tree.asciidoc
new file mode 100644
index 0000000000..d32ce8d19b
--- /dev/null
+++ b/documentation/components/components-tree.asciidoc
@@ -0,0 +1,93 @@
+---
+title: Tree
+order: 22
+layout: page
+---
+
+[[components.tree]]
+= [classname]#Tree#
+
+The [classname]#Tree# component allows a natural way to represent data that has
+hierarchical relationships, such as filesystems or message threads. The
+[classname]#Tree# component in Vaadin works much like the tree components of
+most modern desktop user interface toolkits, for example in directory browsing.
+
+The typical use of the [classname]#Tree# component is for displaying a
+hierachical menu, like a menu on the left side of the screen, as in
+<<figure.components.tree>>, or for displaying filesystems or other hierarchical
+datasets. The [parameter]#menu# style makes the appearance of the tree more
+suitable for this purpose.
+
+
+[source, java]
+----
+final Object[][] planets = new Object[][]{
+        new Object[]{"Mercury"}, 
+        new Object[]{"Venus"},
+        new Object[]{"Earth", "The Moon"},    
+        new Object[]{"Mars", "Phobos", "Deimos"},
+        new Object[]{"Jupiter", "Io", "Europa", "Ganymedes",
+                                "Callisto"},
+        new Object[]{"Saturn",  "Titan", "Tethys", "Dione",
+                                "Rhea", "Iapetus"},
+        new Object[]{"Uranus",  "Miranda", "Ariel", "Umbriel",
+                                "Titania", "Oberon"},
+        new Object[]{"Neptune", "Triton", "Proteus", "Nereid",
+                                "Larissa"}};
+        
+Tree tree = new Tree("The Planets and Major Moons");
+
+/* Add planets as root items in the tree. */
+for (int i=0; i<planets.length; i++) {
+    String planet = (String) (planets[i][0]);
+    tree.addItem(planet);
+    
+    if (planets[i].length == 1) {
+        // The planet has no moons so make it a leaf.
+        tree.setChildrenAllowed(planet, false);
+    } else {
+        // Add children (moons) under the planets.
+        for (int j=1; j<planets[i].length; j++) {
+            String moon = (String) planets[i][j];
+            
+            // Add the item as a regular item.
+            tree.addItem(moon);
+            
+            // Set it to be a child.
+            tree.setParent(moon, planet);
+            
+            // Make the moons look like leaves.
+            tree.setChildrenAllowed(moon, false);
+        }
+
+        // Expand the subtree.
+        tree.expandItemsRecursively(planet);
+    }
+}
+
+main.addComponent(tree);
+----
+
+<<figure.components.tree>> below shows the tree from the code example in a
+practical situation.
+
+[[figure.components.tree]]
+.A [classname]#Tree# Component as a Menu
+image::img/tree-example1.png[]
+
+You can read or set the currently selected item by the value property of the
+[classname]#Tree# component, that is, with [methodname]#getValue()# and
+[methodname]#setValue()#. When the user clicks an item on a tree, the tree will
+receive an [classname]#ValueChangeEvent#, which you can catch with a
+[classname]#ValueChangeListener#. To receive the event immediately after the
+click, you need to set the tree as [classname]#setImmediate(true)#.
+
+The [classname]#Tree# component uses [classname]#Container# data sources much
+like the [classname]#Table# component, with the addition that it also utilizes
+hierarchy information maintained by a [classname]#HierarchicalContainer#. The
+contained items can be of any item type supported by the container. The default
+container and its [methodname]#addItem()# assume that the items are strings and
+the string value is used as the item ID.
+
+
+