Файл: book-of-vaadin.pdf

Managing Layout

6.11. AbsoluteLayout

AbsoluteLayout allows placing components in arbitrary positions in the layout area.The positions are specified in the addComponent() method with horizontal and vertical coordinates relative to an edge of the layout area. The positions can include a third depth dimension, the z-index, which specifies which components are displayed in front and which behind other components.

The positions are specified by a CSS absolute position string, using the left, right, top, bottom, and z-index properties known from CSS. In the following example, we have a 300 by 150 pixels large layout and position a text field 50 pixels from both the left and the top edge:

//A 400x250 pixels size layout AbsoluteLayout layout = new AbsoluteLayout(); layout.setWidth("400px"); layout.setHeight("250px");

//A component with coordinates for its top-left corner TextField text = new TextField("Somewhere someplace"); layout.addComponent(text, "left: 50px; top: 50px;");

The left and top specify the distance from the left and top edge, respectively. The right and bottom specify the distances from the right and top edge.

// At the top-left corner

Button button = new Button( "left: 0px; top: 0px;"); layout.addComponent(button, "left: 0px; top: 0px;");

// At the bottom-right corner

Button buttCorner = new Button( "right: 0px; bottom: 0px;"); layout.addComponent(buttCorner, "right: 0px; bottom: 0px;");

// Relative to the bottom-right corner

Button buttBrRelative = new Button( "right: 50px; bottom: 50px;"); layout.addComponent(buttBrRelative, "right: 50px; bottom: 50px;");

// On the bottom, relative to the left side

Button buttBottom = new Button( "left: 50px; bottom: 0px;"); layout.addComponent(buttBottom, "left: 50px; bottom: 0px;");

// On the right side, up from the bottom

Button buttRight = new Button( "right: 0px; bottom: 100px;"); layout.addComponent(buttRight, "right: 0px; bottom: 100px;");

The result of the above code examples is shown in Figure 6.16, “Components Positioned Relative to Various Edges”.

Managing Layout

Figure 6.16. Components Positioned Relative to Various Edges

In the above examples, we had components of undefined size and specified the positions of components by a single pair of coordinates. The other possibility is to specify an area and let the component fill the area by specifying a proportinal size for the component, such as "100%". Normally, you use setSizeFull() to take the entire area given by the layout.

// Specify an area that a component should fill Panel panel = new Panel("A Panel filling an area"); panel.setSizeFull(); // Fill the entire given area

layout.addComponent(panel, "left: 25px; right: 50px; "+ "top: 100px; bottom: 50px;");

The result is shown in Figure 6.17, “Component Filling an Area Specified by Coordinates”

Figure 6.17. Component Filling an Area Specified by Coordinates

You can also use proportional coordinates to specify the coordinates:

//A panel that takes 30% to 90% horizontally and

//20% to 80% vertically

Panel panel = new Panel("A Panel"); panel.setSizeFull(); // Fill the specified area layout.addComponent(panel, "left: 30%; right: 10%;" +

"top: 20%; bottom: 20%;");

The result is shown in Figure 6.18, “Specifying an Area by Proportional Coordinates”

Managing Layout

Figure 6.18. Specifying an Area by Proportional Coordinates

Drag and drop is very useful for moving the components contained in an AbsoluteLayout. Check out the example in Section 11.11.6, “Dropping on a Component”.

Styling with CSS

.v-absolutelayout {}

.v-absolutelayout-wrapper {}

The AbsoluteLayout component has v-absolutelayout root style. Each component in the layout is contained within an element that has the v-absolutelayout-wrapper.The component captions are outside the wrapper elements, in a separate element with the usual v-caption style.

6.12. CssLayout

CssLayout allows strong control over styling of the components contained inside the layout. The components are contained in a simple DOM structure consisting of <div> elements. By default, the contained components are laid out horizontally and wrap naturally when they reach the width of the layout, but you can control this and most other behaviour with CSS. You can also inject custom CSS for each contained component. As CssLayout has a very simple DOM structure and no dynamic rendering logic, relying purely on the built-in rendering logic of the browsers, it is the fastest of the layout components.

The basic use of CssLayout is just like with any other layout component:

CssLayout layout = new CssLayout();

//Component with a layout-managed caption and icon TextField tf = new TextField("A TextField"); tf.setIcon(new ThemeResource("icons/user.png")); layout.addComponent(tf);

//Labels are 100% wide by default so must unset width Label label = new Label("A Label"); label.setWidth(Sizeable.SIZE_UNDEFINED, 0); layout.addComponent(label);

layout.addComponent(new Button("A Button"));

Managing Layout

The result is shown in Figure 6.19, “Basic Use of CssLayout”. Notice that the default spacing and alignment of the layout is quite crude and CSS styling is nearly always needed.

Figure 6.19. Basic Use of CssLayout

The display attribute of CssLayout is inline-block by default, so the components are laid out horizontally following another. CssLayout has 100% width by default. If the components reach the width of the layout, they are wrapped to the next "line" just as text would be. If you add a component with 100% width, it will take an entire line by wrapping before and after the component.

Overriding the getCss() method allows injecting custom CSS for each component. The CSS returned by the method is inserted in the style attribute of the <div> element of the component, so it will override any style definitions made in CSS files.

CssLayout layout = new CssLayout() { @Override

protected String getCss(Component c) { if (c instanceof Label) {

// Color the boxes with random colors int rgb = (int) (Math.random()*(1<<24));

return "background: #" + Integer.toHexString(rgb);

}

return null;

}

};

layout.setWidth("400px"); // Causes to wrap the contents

// Add boxes of various sizes for (int i=0; i<40; i++) {

Label box = new Label(" ", Label.CONTENT_XHTML); box.addStyleName("flowbox");

box.setWidth((float) Math.random()*50, Sizeable.UNITS_PIXELS);

box.setHeight((float) Math.random()*50, Sizeable.UNITS_PIXELS);

layout.addComponent(box);

}

The style name added to the components allows making common styling in a CSS file:

.v-label-flowbox {

border: thin black solid;

}

Figure 6.20, “Use of getCss() and line wrap” shows the rendered result.

Managing Layout

Figure 6.20. Use of getCss() and line wrap

The stregth of the CssLayout is also its weakness. Much of the logic behind the other layout components is there to give nice default behaviour and to handle the differences in different browsers. Some browsers, no need to say which, are notoriously incompatible with the CSS standards, so they require a lot of custom CSS. You may need to make use of the browser-spe- cific style classes in the root element of the application. Some features in the other layouts are not even solvable in pure CSS, at least in all browsers.

Styling with CSS

.v-csslayout {}

.v-csslayout-margin {}

.v-csslayout-container {}

The CssLayout component has v-csslayout root style. The margin element with v-csslayout-margin style is always enabled. The components are contained in an element with v-csslayout-container style.

For example, we could style the basic CssLayout example shown earlier as follows:

/* Have the caption right of the text box, bottom-aligned */

.csslayoutexample .mylayout .v-csslayout-container { direction: rtl;

line-height: 24px; vertical-align: bottom;

}

/* Have some space before and after the caption */

.csslayoutexample .mylayout .v-csslayout-container .v-caption { padding-left: 3px;

padding-right: 10px;

}

The example would now be rendered as shown in Figure 6.21, “Styling CssLayout”.

Figure 6.21. Styling CssLayout

Captions and icons that are managed by the layout are contained in an element with v-caption style. These caption elements are contained flat at the same level as the actual component elements.This may cause problems with wrapping in inline-block mode, as wrapping can occur between the caption and its corresponding component element just as well as between components. Such use case is therefore not feasible.

Managing Layout

6.13. 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 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.

6.13.1. Layout Size

The size of a layout component can be specified with the setWidth() and setHeight() methods defined in the 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. Section 5.3.9, “Sizing Components” gives details on the interface.

Figure 6.22. HorizontalLayout with Undefined vs Defined size

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 setWidth("100%"); or with the (most commonly used method) setFullSize() that sets 100% size in both directions. If you use a percentage in a

HorizontalLayout, VerticalLayout, or 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 Section 11.3.1, “Debug Mode”.

For example:

//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%");