From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001
From: Markus Koivisto <markus@vaadin.com>
Date: Fri, 22 Jan 2016 14:55:18 +0200
Subject: Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674
---
 documentation/layout/layout-settings.asciidoc | 376 ++++++++++++++++++++++++++
 1 file changed, 376 insertions(+)
 create mode 100644 documentation/layout/layout-settings.asciidoc

(limited to 'documentation/layout/layout-settings.asciidoc')

diff --git a/documentation/layout/layout-settings.asciidoc b/documentation/layout/layout-settings.asciidoc
new file mode 100644
index 0000000000..682cf93563
--- /dev/null
+++ b/documentation/layout/layout-settings.asciidoc
@@ -0,0 +1,376 @@
+---
+title: Layout Formatting
+order: 13
+layout: page
+---
+
+[[layout.settings]]
+= Layout Formatting
+
+While the formatting of layouts is mainly done with style sheets, just as with
+other components, style sheets are not ideal or even possible to use in some
+situations. For example, CSS does not allow defining the spacing of table cells,
+which is done with the [parameter]#cellspacing# attribute in HTML.
+
+Moreover, as many layout sizes are calculated dynamically in the Client-Side
+Engine of Vaadin, some CSS settings can fail altogether.
+
+[[layout.settings.size]]
+== Layout Size
+
+The size of a layout component can be specified with the
+[methodname]#setWidth()# and [methodname]#setHeight()# methods defined in the
+[classname]#Sizeable# interface, just like for any component. It can also be
+undefined, in which case the layout shrinks to fit the component(s) inside it.
+<<dummy/../../../framework/components/components-features#components.features.sizeable,"Sizing
+Components">> gives details on the interface.
+
+[[figure.layout.settings.size.undefined]]
+.[classname]#HorizontalLayout# with Undefined vs Defined size
+image::img/layout_size_undefined_vs_defined.png[]
+
+Many layout components take 100% width by default, while they have the height
+undefined.
+
+The sizes of components inside a layout can also be defined as a percentage of
+the space available in the layout, for example with
+[methodname]#setWidth("100%");# or with the (most commonly used method)
+[methodname]#setFullSize()# that sets 100% size in both directions. If you use a
+percentage in a [classname]#HorizontalLayout#, [classname]#VerticalLayout#, or
+[classname]#GridLayout#, you will also have to set the component as
+__expanding__, as noted below.
+
+
+[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 will try to fill the space given by the layout, while the layout
+will 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.hierarchy,"Inspecting
+Component Hierarchy">>.
+
+====
+
+
+
+For example:
+
+
+[source, java]
+----
+// This takes 100% width but has undefined height.
+VerticalLayout layout = new VerticalLayout();
+
+// A button that takes all the space available in the layout.
+Button button = new Button("100%x100% button");
+button.setSizeFull();
+layout.addComponent(button);
+
+// We must set the layout to a defined height vertically, in
+// this case 100% of its parent layout, which also must
+// not have undefined size.
+layout.setHeight("100%");
+----
+
+If you have a layout with undefined height, such as [classname]#VerticalLayout#,
+in a [classname]#UI#, [classname]#Window#, or [classname]#Panel#, and put enough
+content in it so that it extends outside the bottom of the view area, scrollbars
+will appear. If you want your application to use all the browser view, nothing
+more or less, you should use [methodname]#setFullSize()# for the root layout.
+
+
+[source, java]
+----
+// Create the UI content
+VerticalLayout content = new VerticalLayout();
+
+// Use entire view area
+content.setSizeFull();
+
+setContent(content);
+----
+
+
+[[layout.settings.size.expanding]]
+== Expanding Components
+
+If you set a [classname]#HorizontalLayout# to a defined size horizontally or a
+[classname]#VerticalLayout# vertically, and there is space left over from the
+contained components, the extra space is distributed equally between the
+component cells. The components are aligned within these cells, according to
+their alignment setting, top left by default, as in the example below.
+
+Often, you don't want such empty space, but want one or more components to take
+all the leftover space. You need to set such a component to 100% size and use
+[methodname]#setExpandRatio()#. If there is just one such expanding component in
+the layout, the ratio parameter is irrelevant.
+
+If you set multiple components as expanding, the expand ratio dictates how large
+proportion of the available space (overall or excess depending on whether the
+components are sized as a percentage or not) each component takes. In the
+example below, the buttons have 1:2:3 ratio for the expansion.
+
+[classname]#GridLayout# has corresponding method for both of its directions,
+[methodname]#setRowExpandRatio()# and [methodname]#setColumnExpandRatio()#.
+
+Expansion is dealt in detail in the documentation of the layout components that
+support it. See
+<<dummy/../../../framework/layout/layout-orderedlayout#layout.orderedlayout,"VerticalLayout
+and HorizontalLayout">> and
+<<dummy/../../../framework/layout/layout-gridlayout#layout.gridlayout,"GridLayout">>
+for details on components with relative sizes.
+
+
+[[layout.settings.alignment]]
+== Layout Cell Alignment
+
+((("Alignment", id="term.alignment", range="startofrange")))
+
+
+((("[methodname]#setComponentAlignment()#", id="term.setcomponentalignment", range="startofrange")))
+
+
+When a component in a layout cell has size (width or height) smaller than the
+size of the cell, it will by default be aligned in the top-left corner of the
+cell. You can set the alignment with the [methodname]#setComponentAlignment()#
+method. The method takes as its parameters the component contained in the cell
+to be formatted, and the horizontal and vertical alignment. The component must
+have been added to the layout before setting the alignment.
+
+<<figure.layout.settings.alignment>> illustrates the alignment of components
+within a [classname]#GridLayout#.
+
+[[figure.layout.settings.alignment]]
+.Cell Alignments
+image::img/layout_alignment.png[]
+
+Note that __a component with 100% relative size can not be aligned__, as it will
+take the entire width or height of the cell, in which case alignment is
+meaningless. This should especially be noted with the [classname]#Label#
+component, which has 100% default width, and the text alignment __within__ the
+component is separate, defined by the CSS [literal]#++text-align++# property.
+
+The easiest way to set alignments is to use the constants defined in the
+[classname]#Alignment# class. Let us look how the buttons in the top row of the
+above [classname]#GridLayout# are aligned with constants:
+
+
+[source, java]
+----
+// Create a grid layout
+GridLayout grid = new GridLayout(3, 3);
+
+grid.setWidth(400, Sizeable.UNITS_PIXELS);
+grid.setHeight(200, Sizeable.UNITS_PIXELS);
+
+Button topleft = new Button("Top Left");
+grid.addComponent(topleft, 0, 0);
+grid.setComponentAlignment(topleft, Alignment.TOP_LEFT);
+
+Button topcenter = new Button("Top Center");
+grid.addComponent(topcenter, 1, 0);
+grid.setComponentAlignment(topcenter, Alignment.TOP_CENTER);
+
+Button topright = new Button("Top Right");
+grid.addComponent(topright, 2, 0);
+grid.setComponentAlignment(topright, Alignment.TOP_RIGHT);
+...
+----
+
+The following table lists all the [classname]#Alignment# constants by their
+respective locations:
+
+.Alignment Constants
+
+|===============
+|[parameter]#TOP_LEFT#|[parameter]#TOP_CENTER#|[parameter]#TOP_RIGHT#
+|[parameter]#MIDDLE_LEFT#|[parameter]#MIDDLE_CENTER#|[parameter]#MIDDLE_RIGHT#
+|[parameter]#BOTTOM_LEFT#|[parameter]#BOTTOM_CENTER#|[parameter]#BOTTOM_RIGHT#
+
+|===============
+
+
+
+Another way to specify the alignments is to create an [classname]#Alignment#
+object and specify the horizontal and vertical alignment with separate
+constants. You can specify either of the directions, in which case the other
+alignment direction is not modified, or both with a bitmask operation between
+the two directions.
+
+
+[source, java]
+----
+Button middleleft = new Button("Middle Left");
+grid.addComponent(middleleft, 0, 1);
+grid.setComponentAlignment(middleleft,
+          new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER | 
+                        Bits.ALIGNMENT_LEFT));
+
+Button middlecenter = new Button("Middle Center");
+grid.addComponent(middlecenter, 1, 1);
+grid.setComponentAlignment(middlecenter,
+          new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER |
+                        Bits.ALIGNMENT_HORIZONTAL_CENTER));
+
+Button middleright = new Button("Middle Right");
+grid.addComponent(middleright, 2, 1);
+grid.setComponentAlignment(middleright,
+          new Alignment(Bits.ALIGNMENT_VERTICAL_CENTER |
+                        Bits.ALIGNMENT_RIGHT));
+----
+
+Obviously, you may combine only one vertical bitmask with one horizontal
+bitmask, though you may leave either one out. The following table lists the
+available alignment bitmask constants:
+
+.Alignment Bitmasks
+
+|===============
+|Horizontal|[parameter]#Bits.ALIGNMENT_LEFT#
+|[parameter]#Bits.ALIGNMENT_HORIZONTAL_CENTER#
+|[parameter]#Bits.ALIGNMENT_RIGHT#
+|Vertical|[parameter]#Bits.ALIGNMENT_TOP#
+|[parameter]#Bits.ALIGNMENT_VERTICAL_CENTER#
+|[parameter]#Bits.ALIGNMENT_BOTTOM#
+
+|===============
+
+
+
+You can determine the current alignment of a component with
+[methodname]#getComponentAlignment()#, which returns an [classname]#Alignment#
+object. The class provides a number of getter methods for decoding the
+alignment, which you can also get as a bitmask value.
+
+[[layout.settings.alignment.size]]
+=== Size of Aligned Components
+
+You can only align a component that is smaller than its containing cell in the
+direction of alignment. If a component has 100% width, as many components have
+by default, horizontal alignment does not have any effect. For example,
+[classname]#Label# is 100% wide by default and can not therefore be horizontally
+aligned as such. The problem can be hard to notice, as the text inside a
+[classname]#Label# is left-aligned.
+
+You usually need to set either a fixed size, undefined size, or less than a 100%
+relative size for the component to be aligned - a size that is smaller than the
+containing layout has.
+
+For example, assuming that a [classname]#Label# has short content that is less
+wide than the containing [classname]#VerticalLayout#, you could center it as
+follows:
+
+
+[source, java]
+----
+VerticalLayout layout = new VerticalLayout(); // 100% default width
+Label label = new Label("Hello"); // 100% default width
+label.setSizeUndefined();
+layout.addComponent(label);
+layout.setComponentAlignment(label, Alignment.MIDDLE_CENTER);
+----
+
+If you set the size as undefined and the component itself contains components,
+make sure that the contained components also have either undefined or fixed
+size. For example, if you set the size of a [classname]#Form# as undefined, its
+containing layout [classname]#FormLayout# has 100% default width, which you also
+need to set as undefined. But then, any components inside the
+[classname]#FormLayout# must have either undefined or fixed size.
+
+
+(((range="endofrange", startref="term.alignment")))
+(((range="endofrange", startref="term.setcomponentalignment")))
+
+[[layout.settings.spacing]]
+== Layout Cell Spacing
+
+The [classname]#VerticalLayout#, [classname]#HorizontalLayout#, and
+[classname]#GridLayout# layouts offer a [methodname]#setSpacing()# method to
+enable spacing between the cells of the layout.
+
+For example:
+
+
+[source, java]
+----
+VerticalLayout layout = new VerticalLayout();
+layout.setSpacing(true);
+layout.addComponent(new Button("Component 1"));
+layout.addComponent(new Button("Component 2"));
+layout.addComponent(new Button("Component 3"));
+----
+
+The effect of spacing in [classname]#VerticalLayout# and
+[classname]#HorizontalLayout# is illustrated in <<figure.layout.spacing>>.
+
+[[figure.layout.spacing]]
+.Layout Spacings
+image::img/layout_spacing.png[]
+
+The exact amount of spacing is defined in CSS. If the default is not suitable,
+you can customize it in a custom theme.
+
+In the Valo theme, you can specify the spacing with the
+$v-layout-spacing-vertical and $v-layout-spacing-horizontal parameters, as
+described in
+<<dummy/../../../framework/themes/themes-valo#themes.valo.variables,"Common
+Settings">>. The spacing defaults to the $v-unit-size measure.
+
+When adjusting spacing in other themes, you should note that it is implemented
+in a bit different ways in different layouts. In the ordered layouts, it is done
+with spacer elements, while in the [classname]#GridLayout# it has special
+handling. Please see the sections on the individual components for more details.
+
+
+[[layout.settings.margins]]
+== Layout Margins
+
+Most layout components do not have any margin around them by default. The
+ordered layouts, as well as [classname]#GridLayout#, support enabling a margin
+with [methodname]#setMargin()#. This enables CSS classes for each margin in the
+HTML element of the layout component.
+
+In the Valo theme, the margin sizes default to $v-unit-size. You can customize
+them with $v-layout-margin-top, right, bottom, and left. See
+<<dummy/../../../framework/themes/themes-valo#themes.valo.variables,"Common
+Settings">> for a description of the parameters.
+
+To customize the default margins in other themes, you can define each margin
+with the [literal]#++padding++# property in CSS. You may want to have a custom
+CSS class for the layout component to enable specific customization of the
+margins, as is done in the following with the [literal]#++mymargins++# class:
+
+[subs="normal"]
+----
+
+.**mymargins**.v-margin-left   {padding-left:   **10**px;}
+.**mymargins**.v-margin-right  {padding-right:  **20**px;}
+.**mymargins**.v-margin-top    {padding-top:    **40**px;}
+.**mymargins**.v-margin-bottom {padding-bottom: **80**px;}
+----
+You can enable only specific margins by passing a [classname]#MarginInfo# to the
+[methodname]#setMargin()#. The margins are specified in clockwise order for top,
+right, bottom, and left margin. The following would enable the left and right
+margins:
+
+
+[source, java]
+----
+layout.setMargin(new MarginInfo(false, true, false, true));
+----
+
+The resulting margins are shown in <<figure.layout.margin>> below. The two ways
+produce identical margins.
+
+[[figure.layout.margin]]
+.Layout Margins
+image::img/layout_margin.png[]
+
+
+
+
-- 
cgit v1.2.3

