1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
---
title: GridLayout
order: 4
layout: page
---
[[layout.gridlayout]]
= [classname]#GridLayout#
ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/layout/grid-layout"]
endif::web[]
[classname]#GridLayout# container lays components out on a grid consisting of rows and columns.
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()# method takes the component to be added 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 the 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 is shown in <<figure.layout.gridlayout>>.
The borders have been made visible to illustrate the layout cells.
[[figure.layout.gridlayout]]
.The [classname]#GridLayout# component
image::img/gridlayout.png[width=50%, scaledwidth=75%]
A component to be placed on the grid must not overlap with existing components.
A conflict causes throwing a [classname]#GridLayout.OverlapsException#.
[[layout.gridlayout.sizing]]
== 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">>.
====
[[layout.gridlayout.sizing.expanding]]
=== Expanding Rows and Columns
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);
ifdef::web[]
// 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);
}
endif::web[]
// 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);
ifdef::web[]
// 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%");
}
}
endif::web[]
----
[[figure.ui.gridlayout.sizing.expanding]]
.Expanding rows and columns in [classname]#GridLayout#
image::img/gridlayout_sizing_expanding.png[width=100%, scaledwidth=100%]
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.
[[layout.gridlayout.css]]
== CSS Style Rules
[source, css]
----
.v-gridlayout {}
.v-gridlayout-margin {}
----
The root element of the [classname]#GridLayout# component has `v-gridlayout` style.
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.
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 wrap a component inside a layout component just for styling the cell.
|
