Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 239 insertions, 0 deletions

diff --git a/documentation/layout/layout-gridlayout.asciidoc b/documentation/layout/layout-gridlayout.asciidoc
new file mode 100644
index 0000000000..17666d0e8e
--- /dev/null
+++ b/documentation/layout/layout-gridlayout.asciidoc
@@ -0,0 +1,239 @@
+---
+title: GridLayout
+order: 4
+layout: page
+---
+
+[[layout.gridlayout]]
+= [classname]#GridLayout#
+
+[classname]#GridLayout# container lays components out on a grid, defined by the
+number of columns and rows. The columns and rows of the grid serve as
+coordinates that are used for laying out components on the grid. Each component
+can use multiple cells from the grid, defined as an area (x1,y1,x2,y2), although
+they typically take up only a single grid cell.
+
+The grid layout maintains a cursor for adding components in left-to-right,
+top-to-bottom order. If the cursor goes past the bottom-right corner, it will
+automatically extend the grid downwards by adding a new row.
+
+The following example demonstrates the use of [classname]#GridLayout#. The
+[methodname]#addComponent# takes a component and optional coordinates. The
+coordinates can be given for a single cell or for an area in x,y (column,row)
+order. The coordinate values have a base value of 0. If coordinates are not
+given, the cursor will be used.
+
+
+[source, java]
+----
+// Create a 4 by 4 grid layout.
+GridLayout grid = new GridLayout(4, 4);
+grid.addStyleName("example-gridlayout");
+
+// Fill out the first row using the cursor.
+grid.addComponent(new Button("R/C 1"));
+for (int i = 0; i < 3; i++) {
+    grid.addComponent(new Button("Col " + (grid.getCursorX() + 1)));
+}
+
+// Fill out the first column using coordinates.
+for (int i = 1; i < 4; i++) {
+    grid.addComponent(new Button("Row " + i), 0, i);
+}
+
+// Add some components of various shapes.
+grid.addComponent(new Button("3x1 button"), 1, 1, 3, 1);
+grid.addComponent(new Label("1x2 cell"), 1, 2, 1, 3);
+InlineDateField date = new InlineDateField("A 2x2 date field");
+date.setResolution(DateField.RESOLUTION_DAY);
+grid.addComponent(date, 2, 2, 3, 3);
+----
+
+The resulting layout will look as follows. The borders have been made visible to
+illustrate the layout cells.
+
+[[figure.ui.gridlayout]]
+.The Grid Layout Component
+image::img/gridlayout.png[]
+
+A component to be placed on the grid must not overlap with existing components.
+A conflict causes throwing a [classname]#GridLayout.OverlapsException#.
+
+== Sizing Grid Cells
+
+You can define the size of both a grid layout and its components in either fixed
+or percentual units, or leave the size undefined altogether, as described in
+<<dummy/../../../framework/components/components-features#components.features.sizeable,"Sizing
+Components">>.
+<<dummy/../../../framework/layout/layout-settings#layout.settings.size,"Layout
+Size">> gives an introduction to sizing of layouts.
+
+The size of the [classname]#GridLayout# component is undefined by default, so it
+will shrink to fit the size of the components placed inside it. In most cases,
+especially if you set a defined size for the layout but do not set the contained
+components to full size, there will be some unused space. The position of the
+non-full components within the grid cells will be determined by their
+__alignment__. See
+<<dummy/../../../framework/layout/layout-settings#layout.settings.alignment,"Layout
+Cell Alignment">> for details on how to align the components inside the cells.
+
+The components contained within a [classname]#GridLayout# layout can be laid out
+in a number of different ways depending on how you specify their height or
+width. The layout options are similar to [classname]#HorizontalLayout# and
+[classname]#VerticalLayout#, as described in
+<<dummy/../../../framework/layout/layout-orderedlayout#layout.orderedlayout,"VerticalLayout
+and HorizontalLayout">>.
+
+
+[WARNING]
+.A layout that contains components with percentual size must have a defined size!
+====
+If a layout has undefined size and a contained component has, say, 100% size,
+the component would fill the space given by the layout, while the layout would
+shrink to fit the space taken by the component, which is a paradox. This
+requirement holds for height and width separately. The debug mode allows
+detecting such invalid cases; see
+<<dummy/../../../framework/advanced/advanced-debug#advanced.debug.mode,"Enabling
+the Debug Mode">>.
+
+====
+
+
+
+Often, you want to have one or more rows or columns that take all the available
+space left over from non-expanding rows or columns. You need to set the rows or
+columns as __expanding__ with [methodname]#setRowExpandRatio()# and
+[methodname]#setColumnExpandRatio()#. The first parameter for these methods is
+the index of the row or column to set as expanding. The second parameter for the
+methods is an expansion ratio, which is relevant if there are more than one
+expanding row or column, but its value is irrelevant if there is only one. With
+multiple expanding rows or columns, the ratio parameter sets the relative
+portion how much a specific row/column will take in relation with the other
+expanding rows/columns.
+
+
+[source, java]
+----
+GridLayout grid = new GridLayout(3,2);
+
+// Layout containing relatively sized components must have
+// a defined size, here is fixed size.
+grid.setWidth("600px");
+grid.setHeight("200px");
+
+// Add some content
+String labels [] = {
+        "Shrinking column<br/>Shrinking row",
+        "Expanding column (1:)<br/>Shrinking row",
+        "Expanding column (5:)<br/>Shrinking row",
+        "Shrinking column<br/>Expanding row",
+        "Expanding column (1:)<br/>Expanding row",
+        "Expanding column (5:)<br/>Expanding row"
+};
+for (int i=0; i<labels.length; i++) {
+    Label label = new Label(labels[i], ContentMode.HTML);
+    label.setWidth(null); // Set width as undefined
+    grid.addComponent(label);
+}
+
+// Set different expansion ratios for the two columns
+grid.setColumnExpandRatio(1, 1);
+grid.setColumnExpandRatio(2, 5);
+
+// Set the bottom row to expand
+grid.setRowExpandRatio(1, 1);
+
+// Align and size the labels.
+for (int col=0; col<grid.getColumns(); col++) {
+    for (int row=0; row<grid.getRows(); row++) {
+        Component c = grid.getComponent(col, row);
+        grid.setComponentAlignment(c, Alignment.TOP_CENTER);
+        
+        // Make the labels high to illustrate the empty
+        // horizontal space.
+        if (col != 0 || row != 0)
+            c.setHeight("100%");
+    }
+}
+----
+
+[[figure.ui.gridlayout.sizing.expanding]]
+.Expanding Rows and Columns in [classname]#GridLayout#
+image::img/gridlayout_sizing_expanding.png[]
+
+If the size of the contained components is undefined or fixed, the expansion
+ratio is of the __excess__ space, as in
+<<figure.ui.gridlayout.sizing.expanding>> (excess horizontal space is shown in
+white). However, if the size of the all the contained components in the
+expanding rows or columns is defined as a percentage, the ratio is calculated
+from the __overall__ space available for the percentually sized components. For
+example, if we had a 100 pixels wide grid layout with two columns with 1.0 and
+4.0 respective expansion ratios, and all the components in the grid were set as
+[methodname]#setWidth("100%")#, the columns would have respective widths of 20
+and 80 pixels, regardless of the minimum size of their contained components.
+
+
+== CSS Style Rules
+
+
+[source, css]
+----
+.v-gridlayout {}
+.v-gridlayout-margin {}
+----
+
+The v-gridlayout is the root element of the [classname]#GridLayout# component.
+The v-gridlayout-margin is a simple element inside it that allows setting a
+padding between the outer element and the cells.
+
+For styling the individual grid cells, you should style the components inserted
+in the cells. The implementation structure of the grid can change, so depending
+on it, as is done in the example below, is not generally recommended. Normally,
+if you want to have, for example, a different color for a certain cell, just
+make set the component inside it [methodname]#setSizeFull()#, and add a style
+name for it. Sometimes you may need to use a layout component between a cell and
+its actual component just for styling.
+
+The following example shows how to make the grid borders visible, as in
+<<figure.ui.gridlayout.sizing.expanding>>.
+
+
+[source, java]
+----
+.v-gridlayout-gridexpandratio {
+    background: blue; /* Creates a "border" around the grid. */
+    margin:     10px; /* Empty space around the layout. */
+}
+
+/* Add padding through which the background color shows. */
+.v-gridlayout-gridexpandratio .v-gridlayout-margin {
+    padding: 2px;     
+}
+
+/* Add cell borders and make the cell backgrounds white.
+ * Warning: This depends heavily on the HTML structure. */
+.v-gridlayout-gridexpandratio > div > div > div {
+    padding:    2px;   /* Layout background will show through. */
+    background: white; /* The cells will be colored white. */
+}
+
+/* Components inside the layout are a safe way to style cells. */
+.v-gridlayout-gridexpandratio .v-label {
+    text-align: left;
+    background: #ffffc0; /* Pale yellow */
+}
+----
+
+You should beware of [literal]#++margin++#, [literal]#++padding++#, and
+[literal]#++border++# settings in CSS as they can mess up the layout. The
+dimensions of layouts are calculated in the Client-Side Engine of Vaadin and
+some settings can interfere with these calculations. For more information, on
+margins and spacing, see
+<<dummy/../../../framework/layout/layout-settings#layout.settings.spacing,"Layout
+Cell Spacing">> and
+<<dummy/../../../framework/layout/layout-settings#layout.settings.margins,"Layout
+Margins">>
+
+
+
+