All components have a built-in error indicator that can be set explicitly
with setComponentError()
or can be turned on
implicitly if validating the component fails. As with component caption,
the placement of the indicator is managed by the layout in which the
component is contained. Usually, the error indicator is placed right of
the caption text. Hovering the mouse pointer over the field displays the
error message.
The following example shows how you can set the component error explicitly. The example essentially validates field value without using an actual validator.
// Create a field. final TextField textfield = new TextField("Enter code"); main.addComponent(textfield); // Let the component error be initially clear. (It actually is by default.) textfield.setComponentError(null); // Have a button right of the field (and align it properly). final Button button = new Button("Ok!"); main.addComponent(button); ((VerticalLayout)main.getLayout()).setComponentAlignment(button, Alignment.BOTTOM_LEFT); // Handle button clicks button.addListener(new Button.ClickListener() { public void buttonClick(ClickEvent event) { // If the field value is bad, set its error. // (Here the content must be only alphanumeric characters.) if (! ((String) textfield.getValue()).matches("^\\w*$")) { // Put the component in error state and set the error message. textfield.setComponentError(new UserError("Must be letters and numbers")); } else { // Otherwise clear it. textfield.setComponentError(null); } } });
The Form
component handles and displays also the
errors of its contained fields so that it displays both the error
indicator and the message in a special error indicator area. See Section 4.15, “Form
” and Section 4.15.3, “Validating Form Input” for details on the
Form
component and validation of form input.
Notifications are error or information boxes that appear typically at the center of the screen. A notification box has a caption and optional description and icon. The box stays on the screen either for a defined time or until the user clicks it. The notification type defines the default appearance and behaviour of a notification.
Notifications are always associated with a window object, which can be a
child window (the positioning is always relative to the entire browser
view). The Window
class provides a
showNotification()
method for displaying
notifications. The method takes the caption and an optional description
and notification type as parameters. The method also accepts a
notification object of type Window.Notification
, as
described further below.
mainwindow.showNotification("This is the caption", "This is the description");
The caption and description are, by default, written on the same line. If
you want to have a line break between them, use the XHTML line break markup
"<br/>
". You can use any XHTML markup in the
caption and description of a notification.
main.showNotification("This is a warning", "<br/>This is the <i>last</i> warning", Window.Notification.TYPE_WARNING_MESSAGE);
The notification type defines the overall default style and behaviour of a
notification. If no notification type is given, the "humanized" type is
used as the default. The notification types, listed below, are defined in
the Window.Notification
class.
Table 3.1. Types of Notifications
![]() | TYPE_HUMANIZED_MESSAGE | A user-friendly message that does not annoy too much: it does not require confirmation by clicking and disappears very quickly. It is centered and has a neutral gray color. |
![]() | TYPE_WARNING_MESSAGE | Warnings are messages of medium importance. They are displayed with colors that are neither neutral nor too distractive. A warning is displayed for 1.5 seconds, but the user can click the message box to dismiss it. The user can continue to interact with the application while the warning is displayed. |
![]() | TYPE_ERROR_MESSAGE | Error messages are notifications that require the highest user attention, with alert colors and by requiring the user to click the message to dismiss it. The error message box does not itself include an instruction to click the message, although the close box in the upper right corner indicates it visually. Unlike with other notifications, the user can not interact with the application while the error message is displayed. |
![]() | TYPE_TRAY_NOTIFICATION | Tray notifications are displayed in the "system tray" area, that is, in the lower-right corner of the browser view. As they do not usually obsure any user interface, they are displayed longer than humanized or warning messages, 3 seconds by default. The user can continue to interact with the application normally while the tray notification is displayed. |
All of the features of specific notification types can be controlled with
the attributes of Window.Notification
. You can pass
an explicitly created notification object to the
showNotification()
method.
// Create a notification with the default settings for a warning. Window.Notification notif = new Window.Notification( "Be warned!", "This message lurks in the top-left corner!", Window.Notification.TYPE_WARNING_MESSAGE); // Set the position. notif.setPosition(Window.Notification.POSITION_TOP_LEFT); // Let it stay there until the user clicks it notif.setDelayMsec(-1); // Show it in the main window. main.showNotification(notif);
The setPosition()
method allows setting the
positioning of the notification. The method takes as its parameter any of
the constants:
Window.Notification.POSITION_CENTERED | |
Window.Notification.POSITION_CENTERED_TOP | |
Window.Notification.POSITION_CENTERED_BOTTOM | |
Window.Notification.POSITION_TOP_LEFT | |
Window.Notification.POSITION_TOP_RIGHT | |
Window.Notification.POSITION_BOTTOM_LEFT | |
Window.Notification.POSITION_BOTTOM_RIGHT |
The setDelayMSec()
allows you to set the time in
milliseconds for how long the notification is displayed. Parameter value
-1
means that the message is displayed until the user
clicks the message box. It also prevents interaction with other parts of
the application window, as is default behaviour for error messages. It
does not, however, add a close box that the error notification has.