123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244 |
- ---
- 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, 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">>
-
-
-
|