1 files changed, 74 insertions, 0 deletions
diff --git a/documentation/architecture/architecture-events.asciidoc b/documentation/architecture/architecture-events.asciidoc
new file mode 100644
index 0000000000..e832c581fe
--- /dev/null
+++ b/documentation/architecture/architecture-events.asciidoc
@@ -0,0 +1,74 @@
+---
+title: Events and Listeners
+order: 4
+layout: page
+---
+
+[[architecture.events]]
+= Events and Listeners
+
+Vaadin 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. 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, 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 [methodname]#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 [classname]#Button# has
+[classname]#Button.ClickEvent# events, which can be listened to through the
+[classname]#Button.ClickListener# interface.
+
+In the following, we handle button clicks with a listener implemented as an
+anonymous class:
+
+
+[source, java]
+----
+final Button button = new Button("Push it!");
+
+button.addClickListener(new Button.ClickListener() {
+    public void buttonClick(ClickEvent event) {
+        button.setCaption("You pushed it!");
+    }
+});
+----
+
+<<figure.eventlistenerdiagram>> illustrates the case where an
+application-specific class inherits the [classname]#Button.ClickListener#
+interface to be able to listen for button click events. The application must
+instantiate the listener class and register it with
+[methodname]#addClickListener()#. It can be an anonymous class, such as the one
+above. When an event occurs, an event object is instantiated, in this case a
+[classname]#Button.ClickEvent#. The event object knows the related UI component,
+in this case the [classname]#Button#.
+
+[[figure.eventlistenerdiagram]]
+.Class Diagram of a Button Click Listener
+image::img/events-classdiagram-hi.png[]
+
+In the ancient times of C programming, __callback functions__ filled largely the
+same need as listeners do now. In object-oriented languages, we usually only
+have classes and methods, not functions, so the application has to give a class
+interface instead of a callback function pointer to the framework.
+
+<<dummy/../../../framework/application/application-events#application.events,"Handling
+Events with Listeners">> goes into details of handling events in practice.
+
+
+