--- a/docs/events.rst	Sun Dec 16 21:04:03 2012 +0100
+++ b/docs/events.rst	Mon Dec 17 00:24:34 2012 +0100
@@ -1,16 +1,46 @@
 Event handling
 ==============
 
-Keyboard event propagation
---------------------------
+Draw event
+----------
+
+Draw event is generating for all widgets in top down order - top window is drawn first, then its children etc.
+See TopWindow.draw(), Container.draw(), Widget.draw() - these methods control the draw event propagation.
+Normal widgets should implement only on_draw() method, which is called from draw().
+
 
-top widget -> focuswidget -> focuswidget's parent -> focuswidget's parent's parent -> ...and so forth
+Keypress event, focus
+---------------------
+
+Keyboard events go in top down order, from top window to focused widget in each level. When implementing on_keypress method,
+add super().on_keypress(). Anything before that will be executed in top down walk, anything after in bottom up. Return True if you want to stop
+the walk.
+
+::
 
-1 top window
-4   window
-3     container
-2       edit box
+  before  after
+  1       7      top window
+  2       6        window
+  3       5          container
+  4       4            edit box
+
+Each container maintains its focus child and allows to cycle focus between children (See Container.focusnext). Focus cycling works throughout
+container levels - if focus was on last child and would go to the first, 'tab' key is not handled thus allowing parent level to cycle focus.
+
+When focus changes, two events are generated: focus on new widget, unfocus on previous one.
+Mousedown causes focus change when allowed (Widget.allow_focus).
+
+ * tab key - change focus to next widget
+ * shift-tab - previous widget (FIXME: not implemented)
+
+Hide on focused widget causes focus change like if tab key was pressed.
+
+See Container.trapfocus, Widget.canfocus(), Widget.hasfocus(), Widget.setfocus() for more information.
 
 
 Other event propagation
 -----------------------
+
+Normal events are propagated in top down order, to all children in each level, in order of child addition.
+Some events choose one or more of children for event propagation. In case of mouse events, child is chosen based on mouse cursor position.
+