1 files changed, 58 insertions, 0 deletions
diff --git a/server/src/com/vaadin/event/package.html b/server/src/com/vaadin/event/package.html
new file mode 100644
index 0000000000..2e7e17b892
--- /dev/null
+++ b/server/src/com/vaadin/event/package.html
@@ -0,0 +1,58 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+</head>
+
+<body bgcolor="white">
+
+<!-- Package summary here -->
+
+<p>Provides classes and interfaces for the inheritable event
+model. The model supports inheritable events and a flexible way of
+registering and unregistering event listeners. It's a fundamental building
+block of Vaadin, and as it is included in
+{@link com.vaadin.ui.AbstractComponent}, all UI components
+automatically support it.</p>
+
+<h2>Package Specification</h2>
+
+<p>The core of the event model is the inheritable event class
+hierarchy, and the {@link com.vaadin.event.EventRouter EventRouter}
+which provide a simple, ubiquitous mechanism to transport events to all
+interested parties.</p>
+
+<p>The power of the event inheritance arises from the possibility of
+receiving not only the events of the registered type, <i>but also the
+ones which are inherited from it</i>. For example, let's assume that there
+are the events <code>GeneralEvent</code> and <code>SpecializedEvent</code>
+so that the latter inherits the former. Furthermore we have an object
+<code>A</code> which registers to receive <code>GeneralEvent</code> type
+events from the object <code>B</code>. <code>A</code> would of course
+receive all <code>GeneralEvent</code>s generated by <code>B</code>, but in
+addition to this, <code>A</code> would also receive all 
+<code>SpecializedEvent</code>s generated by <code>B</code>. However, if
+<code>B</code> generates some other events that do not have 
+<code>GeneralEvent</code> as an ancestor, <code>A</code> would not receive
+them unless it registers to listen for them, too.</p>
+
+<p>The interface to attaching and detaching listeners to and from an object
+works with methods. One specifies the event that should trigger the listener,
+the trigger method that should be called when a suitable event occurs and the
+object owning the method. From these a new listener is constructed and added
+to the event router of the specified component.</p>
+
+<p>The interface is defined in
+{@link com.vaadin.event.MethodEventSource MethodEventSource}, and a
+straightforward implementation of it is defined in
+{@link com.vaadin.event.EventRouter EventRouter} which also includes
+a method to actually fire the events.</p>
+
+<p>All fired events are passed to all registered listeners, which are of
+type {@link com.vaadin.event.ListenerMethod ListenerMethod}. The
+listener then checks if the event type matches with the specified event
+type and calls the specified trigger method if it does.</p>
+
+<!-- Put @see and @since tags down here. -->
+
+</body>
+</html>