diff options
Diffstat (limited to 'documentation/layout/layout-gridlayout.asciidoc')
| -rw-r--r-- | documentation/layout/layout-gridlayout.asciidoc | 239 |
1 files changed, 0 insertions, 239 deletions
diff --git a/documentation/layout/layout-gridlayout.asciidoc b/documentation/layout/layout-gridlayout.asciidoc deleted file mode 100644 index 17666d0e8e..0000000000 --- a/documentation/layout/layout-gridlayout.asciidoc +++ /dev/null @@ -1,239 +0,0 @@ ---- -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">> - - - - |