5.3. Common Component Features
The component base classes and interfaces provide a large number of
features. Let us look at some of the most commonly needed features. Features
not documented here can be found from the Java API Reference.
5.3.1. Description and Tooltips
All components (that inherit AbstractComponent) have a description separate from their caption. The description is usually shown as a tooltip that appears when the mouse pointer hovers over the component for a short time.
You can set the description with setDescription() and retrieve with getDescription().
Button button = new Button("A Button");
button.setDescription("This is the tooltip"); The tooltip is shown in Figure 5.5, “Component Description as a Tooltip”.
A description is rendered as a tooltip in most components. Form shows it as text in the top area of the component, as described in Section 5.17.1, “Form as a User Interface Component”.
When a component error has been set with setComponentError(), the error is usually also displayed in the tooltip, below the description (Form displays it in the bottom area of the form). Components that are in error state will also display the error indicator. See Section 4.7.1, “Error Indicator and message”.
The description is actually not plain text, but you can use XHTML tags to format it. Such a rich text description can contain any HTML elements, including images.
button.setDescription(
"<h2><img src=\"../VAADIN/themes/sampler/icons/comment_yellow.gif\"/>"+
"A richtext tooltip</h2>"+
"<ul>"+
" <li>Use rich formatting with XHTML</li>"+
" <li>Include images from themes</li>"+
" <li>etc.</li>"+
"</ul>"); The result is shown in Figure 5.6, “A Rich Text Tooltip”.
Notice that the setter and getter are defined for all fields in the Field interface, not for all components in the Component interface.
Vaadin components are sizeable; not in the sense that they were fairly large or that the number of the components and their features are sizeable, but in the sense that you can make them fairly large on the screen if you like, or small or whatever size.
The Sizeable interface, shared by all components, provides a number of manipulation methods and constants for setting the height and width of a component in absolute or relative units, or for leaving the size undefined.
The size of a component can be set with setWidth() and setHeight() methods. The methods take the size as a floating-point value. You need to give the unit of the measure as the second parameter for the above methods. The available units are listed in Table 5.1, “Size Units” below.
mycomponent.setWidth(100, Sizeable.UNITS_PERCENTAGE);
mycomponent.setWidth(400, Sizeable.UNITS_PIXELS);
Alternatively, you can speficy the size as a string. The format of such a string must follow the HTML/CSS standards for specifying measures.
mycomponent.setWidth("100%");
mycomponent.setHeight("400px"); The "100%" percentage value makes the component take all available size in the particular direction (see the description of Sizeable.UNITS_PERCENTAGE in the table below). You can also use the shorthand method setSizeFull() to set the size to 100% in both directions.
The size can be undefined in either or both dimensions, which means that the component will take the minimum necessary space. Most components have undefined size by default, but some layouts have full size in horizontal direction. You can set the height or width as undefined with Sizeable.SIZE_UNDEFINED parameter for setWidth() and setHeight().
You always need to keep in mind that a layout with undefined size may not contain components with defined relative size, such as "full size". See Section 6.10.1, “Layout Size” for details.
The Table 5.1, “Size Units” lists the available units and their codes defined in the Sizeable interface.
Table 5.1. Size Units
UNITS_PIXELS | px | The pixel is the basic hardware-specific measure of one physical display pixel. |
UNITS_POINTS | pt | The point is a typographical unit, which is usually defined as 1/72 inches or about 0.35 mm. However, on displays the size can vary significantly depending on display metrics. |
UNITS_PICAS | pc | The pica is a typographical unit, defined as 12 points, or 1/7 inches or about 4.233 mm. On displays, the size can vary depending on display metrics. |
UNITS_EM | em | A unit relative to the used font, the width of the upper-case "M" letter. |
UNITS_EX | ex | A unit relative to the used font, the height of the lower-case "x" letter. |
UNITS_MM | mm | A physical length unit, millimeters on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. |
UNITS_CM | cm | A physical length unit, centimeters on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. |
UNITS_INCH | in | A physical length unit, inches on the surface of a display device. However, the actual size depends on the display, its metrics in the operating system, and the browser. |
UNITS_PERCENTAGE | % | A relative percentage of the available size. For example, for the top-level layout 100% would be the full width or height of the browser window. The percentage value must be between 0 and 100. |
If a component inside HorizontalLayout or VerticalLayout has full size in the namesake direction of the layout, the component will expand to take all available space not needed by the other components. See Section 6.10.1, “Layout Size” for details.
5.3.3. Managing Input Focus
When the user clicks on a component, the component gets the input focus, which is indicated by highlighting according to style definitions. If the component allows inputting text, the focus and insertion point are indicated by a cursor. Pressing the Tab key moves the focus to the component next in the focus order.
Focusing is supported by all Field components and also by Form and Upload.
The focus order or tab index of a component is defined as a positive integer value, which you can set with setTabIndex() and get with getTabIndex(). The tab index is managed in the context of the application-level Window in which the components are contained. The focus order can therefore jump between two any lower-level component containers, such as sub-windows or panels.
The default focus order is determined by the natural hierarchical order of components in the order in which they were added under their parents. The default tab index is 0 (zero).
Giving a negative integer as the tab index removes the component from the focus order entirely.
The component having the focus will have an additional style class with the -focus prefix. For example, a TextField would have style v-textfield-focus.
For example (if we have the focusexample style defined for a parent of a text field), the following would make a text field blue when it has focus.
.focusexample .v-textfield-focus {
background: lightblue;
} 
