Package com.vaadin.ui

Class Notification

  • All Implemented Interfaces:
    MethodEventSource, ClientConnector, Extension, Connector, Serializable
    public class Notification
extends AbstractExtension
    A notification message, used to display temporary messages to the user - for example "Document saved", or "Save failed".

    The notification message can consist of several parts: caption, description and icon. It is usually used with only caption - one should be wary of filling the notification with too much information.

    The notification message tries to be as unobtrusive as possible, while still drawing needed attention. There are several basic types of messages that can be used in different situations:
    • TYPE_HUMANIZED_MESSAGE fades away quickly as soon as the user uses the mouse or types something. It can be used to show fairly unimportant messages, such as feedback that an operation succeeded ("Document Saved") - the kind of messages the user ignores once the application is familiar.
    • TYPE_WARNING_MESSAGE is shown for a short while after the user uses the mouse or types something. It's default style is also more noticeable than the humanized message. It can be used for messages that do not contain a lot of important information, but should be noticed by the user. Despite the name, it does not have to be a warning, but can be used instead of the humanized message whenever you want to make the message a little more noticeable.
    • TYPE_ERROR_MESSAGE requires to user to click it before disappearing, and can be used for critical messages.
    • TYPE_TRAY_NOTIFICATION is shown for a while in the lower right corner of the window, and can be used for "convenience notifications" that do not have to be noticed immediately, and should not interfere with the current task - for instance to show "You have a new message in your inbox" while the user is working in some other area of the application.

    In addition to the basic pre-configured types, a Notification can also be configured to show up in a custom position, for a specified time (or until clicked), and with a custom stylename. An icon can also be added.

    See Also:
    Serialized Form

    • Constructor Detail

      • Notification

        public Notification​(String caption)
        Creates a "humanized" notification message. The caption is rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message to show

      • Notification

        public Notification​(String caption,
                    Notification.Type type)
        Creates a notification message of the specified type. The caption is rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message to show
        type - The type of message

      • Notification

        public Notification​(String caption,
                    String description)
        Creates a "humanized" notification message with a bigger caption and smaller description. The caption and description are rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message caption
        description - The message description

      • Notification

        public Notification​(String caption,
                    String description,
                    Notification.Type type)
        Creates a notification message of the specified type, with a bigger caption and smaller description. The caption and description are rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message caption
        description - The message description
        type - The type of message

      • Notification

        public Notification​(String caption,
                    String description,
                    Notification.Type type,
                    boolean htmlContentAllowed)
        Creates a notification message of the specified type, with a bigger caption and smaller description. Care should be taken to to avoid XSS vulnerabilities if html is allowed.
        Parameters:
        caption - The message caption
        description - The message description
        type - The type of message
        htmlContentAllowed - Whether html in the caption and description should be displayed as html or as plain text

    • Method Detail

      • getCaption

        public String getCaption()
        Gets the caption part of the notification message.
        Returns:
        The message caption

      • setCaption

        public void setCaption​(String caption)
        Sets the caption part of the notification message.
        Parameters:
        caption - The message caption

      • getDescription

        public String getDescription()
        Gets the description part of the notification message.
        Returns:
        The message description

      • setDescription

        public void setDescription​(String description)
        Sets the description part of the notification message.
        Parameters:
        description - The message description

      • getPosition

        public Position getPosition()
        Gets the position of the notification message.
        Returns:
        The position

      • setPosition

        public void setPosition​(Position position)
        Sets the position of the notification message.
        Parameters:
        position - The desired notification position, not null

      • getIcon

        public Resource getIcon()
        Gets the icon part of the notification message.
        Returns:
        The message icon

      • setIcon

        public void setIcon​(Resource icon)
        Sets the icon part of the notification message.
        Parameters:
        icon - The desired message icon

      • getDelayMsec

        public int getDelayMsec()
        Gets the delay before the notification disappears.
        Returns:
        the delay in milliseconds, -1 indicates the message has to be clicked.

      • setDelayMsec

        public void setDelayMsec​(int delayMsec)
        Sets the delay before the notification disappears.
        Parameters:
        delayMsec - the desired delay in milliseconds, -1 to require the user to click the message

      • setStyleName

        public void setStyleName​(String styleName)
        Sets the style name for the notification message.
        Parameters:
        styleName - The desired style name

      • getStyleName

        public String getStyleName()
        Gets the style name for the notification message.
        Returns:
        The style name

      • setHtmlContentAllowed

        public void setHtmlContentAllowed​(boolean htmlContentAllowed)
        Sets whether html is allowed in the caption and description. If set to true, the texts are passed to the browser as html and the developer is responsible for ensuring no harmful html is used. If set to false, the texts are passed to the browser as plain text.
        Parameters:
        htmlContentAllowed - true if the texts are used as html, false if used as plain text

      • isHtmlContentAllowed

        public boolean isHtmlContentAllowed()
        Checks whether caption and description are interpreted as HTML or plain text.
        Returns:
        true if the texts are used as HTML, false if used as plain text
        See Also:
        setHtmlContentAllowed(boolean)

      • show

        public void show​(Page page)
        Shows this notification on a Page.
        Parameters:
        page - The page on which the notification should be shown

      • close

        public void close()
        Closes (hides) the notification.

        If the notification is not shown, does nothing.

        Since:
        8.4

      • close

        protected void close​(boolean userOriginated)
        Closes (hides) the notification.

        If the notification is not shown, does nothing.

        Parameters:
        userOriginated - true if the notification was closed because the user clicked on it, false if the notification was closed from the server
        Since:
        8.4

      • getState

        protected NotificationState getState()
        Description copied from class: AbstractClientConnector
        Returns the shared state for this connector. The shared state object is shared between the server connector and the client connector. Changes are only communicated from the server to the client and not in the other direction.

        As a side effect, marks the connector dirty so any changes done to the state will be sent to the client. Use getState(false) to avoid marking the connector as dirty.

        Overrides:
        getState in class AbstractClientConnector
        Returns:
        The shared state for this connector. Never null.

      • show

        public static Notification show​(String caption)
        Shows a notification message on the middle of the current page. The message automatically disappears ("humanized message"). The caption is rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message
        Returns:
        The Notification
        See Also:
        Notification(String), show(Page)

      • show

        public static Notification show​(String caption,
                                String description,
                                Notification.Type type)
        Shows a notification message the current page. The position and behavior of the message depends on the type, which is one of the basic types defined in Notification, for instance Notification.TYPE_WARNING_MESSAGE. The caption is rendered as plain text with HTML automatically escaped.
        Parameters:
        caption - The message
        description - The message description
        type - The message type
        Returns:
        The Notification
        See Also:
        Notification(String, String, Type), show(Page)

      • addCloseListener

        public Registration addCloseListener​(Notification.CloseListener listener)
        Adds a CloseListener to the Notification.
        Parameters:
        listener - the CloseListener to add, not null
        Since:
        8.2