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.
The interface defines a number of properties, which you can retrieve or manipulate with the corresponding setters and getters.
A caption is an explanatory textual label accompanying a user interface component, usually shown above, left of, or inside the component. The contents of a caption are automatically quoted, so no raw XHTML can be rendered in a caption.
The caption text can usually be given as the first parameter of a
constructor of a component or with setCaption()
.
// New text field with caption "Name" TextField name = new TextField("Name"); layout.addComponent(name);
The caption of a component is, by default, managed and displayed by the
layout component or component container inside which the component is
placed. For example, the VerticalLayout
component
shows the captions left-aligned above the contained components, while the
FormLayout
component shows the captions on the left
side of the vertically laid components, with the captions and their
associated components left-aligned in their own columns. The
CustomComponent
does not manage the caption of its
composition root, so if the root component has a caption, it will not be
rendered.
Some components, such as Button
and
Panel
, manage the caption themselves and display it
inside the component.
Icon (see Section 5.3.4, “Icon”) is closely related to caption and is usually displayed horizontally before or after it, depending on the component and the containing layout. Also the required indicator in field components is usually shown before or after the caption.
An alternative way to implement a caption is to use another component as
the caption, typically a Label
, a
TextField
, or a Panel
. A
Label
, for example, allows highlighting a shortcut
key with XHTML markup or to bind the caption to a data source. The
Panel
provides an easy way to add both a caption
and a border around a component.
.v-caption {} .v-captiontext {} .v-caption-clearelem {} .v-required-field-indicator {}
A caption is be rendered inside an HTML element that has the
v-caption
CSS style class. The containing layout
may enclose a caption inside other caption-related elements.
Some layouts put the caption text in a
v-captiontext
element. A
v-caption-clearelem
is used in some layouts to
clear a CSS float
property in captions. An optional
required indicator in field components is contained in a separate
element with v-required-field-indicator
style.
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.6, “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.19.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.7, “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.
The enabled property controls whether the user can actually use the component. A disabled component is visible, but grayed to indicate the disabled state.
Components are always enabled by default. You can disable a component with
setEnabled(false)
.
Button enabled = new Button("Enabled"); enabled.setEnabled(true); // The default layout.addComponent(enabled); Button disabled = new Button("Disabled"); disabled.setEnabled(false); layout.addComponent(disabled);
Figure 5.8, “An Enabled and Disabled Button
” shows the
enabled and disabled buttons.
A disabled component is automatically put in read-only state. No client
interaction with such a component is sent to the server and, as an
important security feature, the server-side components do not receive
state updates from the client in the read-only state. This feature exists
in all built-in components in Vaadin and is automatically handled for all
Field
components for the field property value. For
custom widgets, you need to make sure that the read-only state is checked
on the server-side for all safety-critical variables.
Disabled components have the v-disabled
CSS style
in addition to the component-specific style. To match a component with
both the styles, you have to join the style class names with a dot as
done in the example below.
.v-textfield.v-disabled { border: dotted; }
This would make the border of all disabled text fields dotted.
TextField disabled = new TextField("Disabled"); disabled.setValue("Read-only value"); disabled.setEnabled(false); layout.addComponent(disabled);
The result is illustrated in Figure 5.9, “Styling Disabled Components”.
An icon is an explanatory graphical label accompanying a user interface component, usually shown above, left of, or inside the component. Icon is closely related to caption (see Section 5.3.1, “Caption”) and is usually displayed horizontally before or after it, depending on the component and the containing layout.
The icon of a component can be set with the
setIcon()
method. The image is provided as a
resource, perhaps most typically a ThemeResource
.
// Component with an icon from a custom theme TextField name = new TextField("Name"); name.setIcon(new ThemeResource("icons/user.png")); layout.addComponent(name); // Component with an icon from another theme ('runo') Button ok = new Button("OK"); ok.setIcon(new ThemeResource("../runo/icons/16/ok.png")); layout.addComponent(ok);
The icon of a component is, by default, managed and displayed by the
layout component or component container in which the component is
placed. For example, the VerticalLayout
component
shows the icons left-aligned above the contained components, while the
FormLayout
component shows the icons on the left
side of the vertically laid components, with the icons and their
associated components left-aligned in their own columns. The
CustomComponent
does not manage the icon of its
composition root, so if the root component has an icon, it will not be
rendered.
Some components, such as Button
and
Panel
, manage the icon themselves and display it
inside the component.
The locale property defines the country and language used in a
component. You can use the locale information in conjunction with an
internationalization scheme to acquire localized resources. Some
components, such as DateField
, use the locale for
component localization.
You can set the locale of a component (or the application) with
setLocale()
.
// Component for which the locale is meaningful InlineDateField date = new InlineDateField("Datum"); // German language specified with ISO 639-1 language // code and ISO 3166-1 alpha-2 country code. date.setLocale(new Locale("de", "DE")); date.setResolution(DateField.RESOLUTION_DAY); layout.addComponent(date);
The resulting date field is shown in Figure 5.11, “Set Locale for InlineDateField
”.
You can get the locale of a component with
getLocale()
. If the locale is undefined for a
component, that is, not explicitly set, the locale of the parent component
is used. If none of the parent components have a locale set, the locale of
the application is used, and if that is not set, the default system locale
is set, as given by Locale.getDefault()
.
Because of the requirement that the component must be attached to the
application, it is awkward to use getLocale()
for
internationalization. You can not use it in the constructor, so you would
have to get the locale in attach()
as shown in
the following example:
Button cancel = new Button() { @Override public void attach() { ResourceBundle bundle = ResourceBundle.getBundle( MyAppCaptions.class.getName(), getLocale()); setCaption(bundle.getString("CancelKey")); } }; layout.addComponent(cancel);
It is normally a better practice to get the locale from an application-global parameter and use it to get the localized resource right when the component is created.
// Captions are stored in MyAppCaptions resource bundle // and the application object is known in this context. ResourceBundle bundle = ResourceBundle.getBundle(MyAppCaptions.class.getName(), getApplication().getLocale()); // Get a localized resource from the bundle Button cancel = new Button(bundle.getString("CancelKey")); layout.addComponent(cancel);
A common task in many applications is selecting a locale. This is done
in the following example with a Select
component.
// The locale in which we want to have the language // selection list Locale displayLocale = Locale.ENGLISH; // All known locales final Locale[] locales = Locale.getAvailableLocales(); // Allow selecting a language. We are in a constructor of a // CustomComponent, so preselecting the current // language of the application can not be done before // this (and the selection) component are attached to // the application. final Select select = new Select("Select a language") { @Override public void attach() { setValue(getLocale()); } }; for (int i=0; i<locales.length; i++) { select.addItem(locales[i]); select.setItemCaption(locales[i], locales[i].getDisplayName(displayLocale)); // Automatically select the current locale if (locales[i].equals(getLocale())) select.setValue(locales[i]); } layout.addComponent(select); // Locale code of the selected locale final Label localeCode = new Label(""); layout.addComponent(localeCode); // A date field which language the selection will change final InlineDateField date = new InlineDateField("Calendar in the selected language"); date.setResolution(DateField.RESOLUTION_DAY); layout.addComponent(date); // Handle language selection select.addListener(new Property.ValueChangeListener() { public void valueChange(ValueChangeEvent event) { Locale locale = (Locale) select.getValue(); date.setLocale(locale); localeCode.setValue("Locale code: " + locale.getLanguage() + "_" + locale.getCountry()); } }); select.setImmediate(true);
The user interface is shown in Figure 5.12, “Selecting a Locale”.
The property defines whether the value of a component can be changed. The
property is mainly applicable to Field
components,
as they have a value that can be edited by the user.
TextField readwrite = new TextField("Read-Write"); readwrite.setValue("You can change this"); readwrite.setReadOnly(false); // The default layout.addComponent(readwrite); TextField readonly = new TextField("Read-Only"); readonly.setValue("You can't touch this!"); readonly.setReadOnly(true); layout.addComponent(readonly);
The resulting read-only text field is shown in Figure 5.13, “A Read-Only Component.”.
Setting a layout or some other component container as read-only does not
usually make the contained components read-only recursively. This is
different from, for example, the disabled state, which is usually applied
recursively. The Form
component is an exception, as
it applies the read-only state to the form fields.
Notice that the value of a selection component is the selection, not its
items. A read-only selection component doesn't therefore allow its
selection to be changed, but other changes are possible. For example, if
you have a read-only Table
in editable mode, its
contained fields and the underlying data model can still be edited, and
the user could sort it or reorder the columns.
Client-side state modifications will not be communicated to the
server-side and, more importantly, server-side field components will not
accept changes to the value of a read-only Field
component. The latter is an important security feature, because a
malicious user can not fabricate state changes in a read-only field. This
is handled at the level of AbstractField
in
setValue()
, so you can not change the value
programmatically either. Calling setValue()
on a
read-only field results in
Property.ReadOnlyException
.
Also notice that while the read-only status applies automatically to the
property value of a field, it does not apply to other component
variables. A read-only component can accept some other variable changes
from the client-side and some of such changes could be acceptable, such as
change in the scroll bar position of a
Table
. Custom widgets should check the read-only
state for variables bound to business data.
Setting a normally editable component to read-only state can change
its appearance to disallow editing the value. In addition to CSS
styling, also the HTML structure can change. For example,
TextField
loses the edit box and appears much
like a Label
.
A read-only component will have the v-readonly
style. The following CSS rule would make the text in all read-only
TextField
components appear in italic.
.v-textfield.v-readonly { font-style: italic; }
The style name property defines one or more custom
CSS style class names for the component. The
getStyleName()
returns the current style names as
a space-separated list. The setStyleName()
replaces all the styles with the given style name or a space-separated
list of style names. You can also add and remove individual style names
with addStylename()
and
removeStyleName()
. A style name must be a valid
CSS style name.
Label label = new Label("This text has a lot of style"); label.addStyleName("mystyle"); layout.addComponent(label);
The style name will appear in the component's HTML element in two forms:
literally as given and prefixed with the component class specific style
name. For example, if you add a style name mystyle
to a
Button
, the component would get both
mystyle
and v-button-mystyle
styles. Neither form may conflict with built-in style names of Vaadin or
GWT. For example, focus
style would conflict with a
built-in style of the same name, and an option
style
for a Select
component would conflict with the
built-in v-select-option
style.
The following CSS rule would apply the style to any component that has the
mystyle
style.
.mystyle { font-family: fantasy; font-style: italic; font-size: 25px; font-weight: bolder; line-height: 30px; }
The resulting styled component is shown in Figure 5.14, “Component with a Custom Style”
Components can be hidden by setting the visible property to false. Also the caption, icon and any other component features are made hidden. Hidden components are not just invisible, but their content is not communicated to the browser at all. That is, they are not made invisible cosmetically with only CSS rules. This feature is important for security if you have components that contain security-critical information that must only be shown in specific application states.
TextField readonly = new TextField("Read-Only"); readonly.setValue("You can't see this!"); readonly.setVisible(false); layout.addComponent(readonly);
The resulting invisible component is shown in Figure 5.15, “An Invisible Component.”.
Beware that invisible beings can leave footprints. The containing layout cell that holds the invisible component will not go away, but will show in the layout as extra empty space. Also expand ratios work just like if the component was visible - it is the layout cell that expands, not the component.
If you need to make a component only cosmetically invisible, you should
use a custom theme to set it display: none
style. This
is mainly useful for certain special components such as
ProgressIndicator
, which have effects even when
made invisible in CSS. If the hidden component has undefined size and is
enclosed in a layout that also has undefined size, the containing layout
will collapse when the component disappears. If you want to have the
component keep its size, you have to make it invisible by setting all its
font and other attributes to be transparent. In such cases, the invisible
content of the component can be made visible easily in the browser.
A component made invisible with the visible property
has no particular CSS style class to indicate that it is hidden. The
element does exist though, but has display: none
style,
which overrides any CSS styling.
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.12.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.12.1, “Layout Size” for details.
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
suffix. For example, a
TextField
, which normally has the
v-textfield
style, would additionally have the
v-textfield-focus
style.
For example, the following would make a text field blue when it has focus.
.v-textfield-focus { background: lightblue; }