Documentation versions (currently viewingVaadin 8)

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Events and Listeners

Vaadin Framework offers an event-driven programming model for handling user interaction. When a user does something in the user interface, such as clicks a button or selects an item, the application needs to know about it. Many Java-based user interface frameworks follow the Event-Listener pattern (also known as the Observer design pattern) to communicate user input to the application logic. So does Vaadin Framework. The design pattern involves two kinds of elements: an object that generates ("fires" or "emits") events and a number of listeners that listen for the events. When such an event occurs, the object sends a notification about it to all the listeners. In a typical case, there is only one listener.

Events can serve many kinds of purposes. In Vaadin Framework, the usual purpose of events is handling user interaction in a user interface. Session management can require special events, such as time-out, in which case the event would actually be the lack of user interaction. Time-out is a special case of timed or scheduled events, where an event occurs at a specific date and time or when a set time has passed.

To receive events of a particular type, an application must register a listener object with the event source. The listeners are registered in the components with an add*Listener() method (with a method name specific to the listener).

Most components that have related events define their own event class and the corresponding listener class. For example, the Button has Button.ClickEvent events, which can be listened to through the Button.ClickListener functional interface.

In the following, we assign a button click listener using a lambda expression.

final Button button = new Button("Push it!");

button.addClickListener(event ->
  button.setCaption("You pushed it!"));

Class Diagram of a Button Click Listener illustrates the case where an application-specific class inherits the Button.ClickListener interface to be able to listen for button click events. The application must instantiate the listener class and register it with addClickListener(). When an event occurs, an event object is instantiated, in this case a Button.ClickEvent. The event object knows the related UI component, in this case the Button.

events classdiagram
Class Diagram of a Button Click Listener

"Handling Events with Listeners" goes into details of handling events in practice.