Vaadin
|
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 can usually be given as the first parameter of a constructor
or later with the // 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 in which the component is
placed. For example, the
Some components, such as 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.
An alternative way to implement a caption is to use another component as
the caption, typically a
Setting the caption with
A caption will be rendered inside an HTML element that has the
<component>-caption CSS style class, where <component> is
the identifier of the component to which the caption is attached. For
example, the caption of a All components (that inherit You can set the description with 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. When a component error has been set with 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 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
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 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 component does not receive state updates from the client.
Disabled components have the .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
// 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
Some components, such as
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
You can set the locale of a component (or the application) with
// 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
You can get the locale of a component with
Because of the requirement that the component must be attached to the
application, it is awkward to use 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 // 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 user can change the value of a
component. As only 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.”. Even when a component is read-only, the user may be able to interact with some component features, such as scrolling.
Client-side state modifications will not be communicated to the
server-side and, more important, server-side field components will not
accept changes to the value of a read-only component. This is an important
security feature, because a malicious user can not fabricate state changes
in a read-only component. Notice that this occurs at the level of
The appearance of the component can change to indicate that the value
is not editable. A read-only component will have the
.v-textfield.v-readonly {
font-style: italic;
}
An icon will be rendered inside an HTML element that has the
The style name property defines one or more custom
CSS style class names for the component. The
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
The following CSS rule would apply the style to any component that has the
.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.”.
If you need to make a component only cosmetically invisible, you should
use a custom theme to set it
An invisible component has no particular CSS style class to indicate that
it is hidden. The element does exist though, but has 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 The size of a component can be set with 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 " 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 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 Table 5.1. Size Units
If a component inside 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 The focus order or tab index of a component is defined as a positive integer value, which you can set with 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 For example (if we have the .focusexample .v-textfield-focus {
background: lightblue;
} |
Table of Contents
|
