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

Visual User Interface Design with Eclipse

7.3.2. Setting Component Properties

The property setting sub-panel of the control panel allows setting component properties. The panel has two tabs: Layout and Properties, where the latter defines the various basic properties.

Basic Properties

The top section of the property panel, shown in Figure 7.3, “Basic Component Properties”, allows setting basic component properties. The panel also includes properties such as field properties for field components.

Figure 7.3. Basic Component Properties

The properties are as follows:

Name

The name of the component, which is used for the reference to the component, so it must obey Java notation for variable names.

Style Name

A space-separated list of CSS style class names for the component. See Chapter 8, Themes for information on component styles in themes.

Caption

The caption of a component is usually displayed above the component. Some components, such as Button, display the caption inside the component. For Label text, you should set the value of the label instead of the caption, which should be left empty.

Visual User Interface Design with Eclipse

Description (tooltip)

The description is usually displayed as a tooltip when the mouse pointer hovers over the component for a while. Some components, such as Form have their own way of displaying the description.

Icon

The icon of a component is usually displayed above the component, left of the caption. Some components, such as Button, display the icon inside the component.

Formatting type

Some components allow different formatting types, such as Label, which allow formatting either as Text, XHTML, Preformatted, and Raw.

Value

The component value. The value type and how it is displayed by the component varies between different component types and each value type has its own editor. The editor opens by clicking on the ... button.

Most of the basic component properties are defined in the Component interface; see Section 5.2.1, “Component Interface” for further details.

Layout Properties

The size of a component is determined by its width and height, which you can give in the two edit boxes in the control panel. You can use any unit specifiers for components, as described in Section 5.3.9, “Sizing Components”. Emptying a size box will make the size "automatic", which means setting the size as undefined. In the generated code, the undefined value will be expressed as "-1px".

Setting width of "100px" and auto (undefined or empty) height would result in the following generated settings for a button:

// myButton

myButton = new Button();

...

myButton.setHeight("-1px"); myButton.setWidth("100px");

...

Figure 7.4, “Layout Properties” shows the control panel area for the size and position.

Visual User Interface Design with Eclipse

Figure 7.4. Layout Properties

The generated code for the example would be:

// myButton

myButton = new Button(); myButton.setWidth("-1px"); myButton.setHeight("-1px"); myButton.setImmediate(true); myButton.setCaption("My Button"); mainLayout.addComponent(myButton,

"top:243.0px;left:152.0px;");

The position is given as a CSS position in the second parameter for addComponent(). The values "-1px" for width and height will make the button to be sized automatically to the minimum size required by the caption.

When editing the position of a component inside an AbsoluteLayout, the editor will display vertical and horizontal guides, which you can use to set the position of the component. See Section 7.3.3, “Editing an AbsoluteLayout” for more information about editing absolute layouts.

The ZIndex setting controls the "Z coordinate" of the components, that is, which component will overlay which when they overlap. Value -1 means automatic, in which case the components added to the layout later will be on top.

7.3.3. Editing an AbsoluteLayout

The visual editor has interactive support for the AbsoluteLayout component that allows positioning components exactly at specified coordinates.You can position the components using guides that control the position attributes, shown in the control panel on the right. The position values are measured in pixels from the corresponding edge; the vertical and horizontal rulers show the distances from the top and left edge.

Figure 7.5, “Positioning with AbsoluteLayout” shows three components, a Label, a Table, and a Button, inside an AbsoluteLayout.

Visual User Interface Design with Eclipse

Figure 7.5. Positioning with AbsoluteLayout

Position attributes that are empty are automatic and can be either zero (at the edge) or dynamic to make it shrink to fit the size of the component, depending on the component. Guides are shown also for the automatic position attributes and move automatically; in Figure 7.5, “Positioning with AbsoluteLayout” the right and bottom edges of the Button are automatic.

Moving an automatic guide manually makes the guide and the corresponding the position attribute non-automatic. To make a manually set attribute automatic, empty it in the control panel. Figure 7.6, “Manually positioned Label” shows a Label component with all the four edges set manually. Notice that if an automatic position is 0, the guide is at the edge of the ruler.

Figure 7.6. Manually positioned Label

Visual User Interface Design with Eclipse

7.4. Structure of a Visually Editable Component

A component created by the wizard and later managed by the visual editor has a very specific structure that allows you to insert your user interface logic in the component while keeping a minimal amount of code off-limits.You need to know what you can edit yourself and what exactly is managed by the editor. The managed member variables and methods are marked with the AutoGenerated annotation, as you can see later.

A visually editable component consists of:

•Member variables containing sub-component references

•Sub-component builder methods

•The constructor

The structure of a composite component is hierarchical, a nested hierarchy of layout components containing other layout components as well as regular components. The root layout of the component tree, or the composition root of the CustomComponent, is named mainLayout. See Section 5.22, “Component Composition with CustomComponent” for a detailed description of the structure of custom (composite) components.

7.4.1. Sub-Component References

The CustomComponent class will include a reference to each contained component as a member variable. The most important of these is the mainLayout reference to the composition root layout. Such automatically generated member variables are marked with the @AutoGenerated annotation. They are managed by the editor, so you should not edit them manually, unless you know what you are doing.

A composite component with an AbsoluteLayout as the composition root, containing a Button and a Table would have the references as follows:

public class MyComponent extends CustomComponent {

@AutoGenerated

private AbsoluteLayout mainLayout; @AutoGenerated

private Button myButton; @AutoGenerated

private Table myTable;

...

The names of the member variables are defined in the component properties panel of the visual editor, in the Component name field, as described in the section called “Basic Properties”. While you can change the name of any other components, the name of the root layout is always mainLayout. It is fixed because the editor does not make changes to the constructor, as noted in Section 7.4.3, “The Constructor”. You can, however, change the type of the root layout, which is an AbsoluteLayout by default.

Certain typically static components, such as the Label label component, will not have a reference as a member variable. See the description of the builder methods below for details.

Visual User Interface Design with Eclipse

7.4.2. Sub-Component Builders

Every managed layout component will have a builder method that creates the layout and all its contained components. The builder puts references to the created components in their corresponding member variables, and it also returns a reference to the created layout component.

Below is an example of an initial main layout:

@AutoGenerated

private AbsoluteLayout buildMainLayout() {

//common part: create layout mainLayout = new AbsoluteLayout();

//top-level component properties setHeight("100.0%"); setWidth("100.0%");

return mainLayout;

}

Notice that while the builder methods return a reference to the created component, they also write the reference directly to the member variable. The returned reference might not be used by the generated code at all (in the constructor or in the builder methods), but you can use it for your purposes.

The builder of the main layout is called in the constructor, as explained in Section 7.4.3, “The Constructor”. When you have a layout with nested layout components, the builders of each layout will call the appropriate builder methods of their contained layouts to create their contents.

7.4.3. The Constructor

When you create a new composite component using the wizard, it will create a constructor for the component and fill its basic content.

public MyComponent() { buildMainLayout(); setCompositionRoot(mainLayout);

// TODO add user code here

}

The most important thing to do in the constructor is to set the composition root of the CustomComponent with the setCompositionRoot() (see Section 5.22, “Component Composition with CustomComponent” for more details on the composition root). The generated constructor first builds the root layout of the composite component with buildMainLayout() and then uses the mainLayout reference.

The editor will not change the constructor afterwards, so you can safely change it as you want. The editor does not allow changing the member variable holding a reference to the root layout, so it is always named mainLayout.

Chapter 8

Themes

This chapter provides details about using and creating themes that control the visual look of web applications. Themes are created using Sass, which is an extension of CSS (Cascading Style Sheets), or with plain CSS. We provide an introduction to CSS, especially concerning the styling of HTML by element classes.

8.1. Overview

Vaadin separates the appearance of the user interface from its logic using themes. Themes can include Sass or CSS style sheets, custom HTML layouts, and any necessary graphics. Theme resources can also be accessed from application code as ThemeResource objects.

Custom themes are placed under the VAADIN/themes/ folder of the web application (under WebContent in Eclipse). This location is fixed -- the VAADIN folder contains static resources that are served by the Vaadin servlet. The servlet augments the files stored in the folder by resources found from corresponding VAADIN folders contained in JARs in the class path. For example, the built-in themes are stored in the vaadin-themes.jar.

Figure 8.1, “Contents of a Theme” illustrates the contents of a theme.

Themes

Figure 8.1. Contents of a Theme

The name of a theme folder defines the name of the theme. The name is used in the @Theme annotation that sets the theme. A theme must contain either a styles.scss for Sass themes, or styles.css stylesheet for plain CSS themes, but other contents have free naming. We recommend that you have the actual theme content in a SCSS file named after the theme, such as mytheme.scss, to make the names more unique.

We also suggest a convention for naming the folders as img for images, layouts for custom layouts, and css for additional stylesheets.

Custom themes that use an existing complete theme need to inherit the theme. See Section 8.4.4, “Built-in Themes” and Section 8.4.6, “Theme Inheritance” for details on inheriting a theme. Copying and modifying a complete theme is also possible, but it may need more work to maintain if the modifications are small.

You use a theme by specifying it with the @Theme annotation for the UI class of the application as follows:

@Theme("mytheme")

public class MyUI extends UI { @Override

protected void init(VaadinRequest request) {

...

}

}

A theme can contain alternate styles for user interface components, which can be changed as needed.

In addition to style sheets, a theme can contain HTML templates for custom layouts used with CustomLayout. See Section 6.14, “Custom Layouts” for details.