diff -r 54dd866b8951 -r c6e170452c7f docs/events.rst
--- a/docs/events.rst	Mon Dec 17 21:07:59 2012 +0100
+++ b/docs/events.rst	Mon Dec 17 23:19:58 2012 +0100
@@ -9,8 +9,8 @@
 Normal widgets should implement only on_draw() method, which is called from draw().
 
 
-Keypress event, focus
----------------------
+Keypress event
+--------------
 
 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
@@ -24,18 +24,26 @@
   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
+Focus
+-----
+
+Basics:
+ * Only one node in hierarchy can have focus.
+ * All parent containers have focus, so they can relay events to focused child.
+ * Top container has always focus.
+
+Each container maintains its focus child and allows to cycle focus between children (See Container.focus_next). 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)
+ * Use grab_focus() on widget to make it receive keyboard events. This will clean old focus and set focus to this child.
+ * Global shortcuts can be handled in keypress event from top widget. All keyboard events go through there.
+ * Tab key changes focus to next widget. Shift-tab changes back to previous widget (FIXME: not implemented).
+ * Hide on focused widget causes focus change like if tab key was pressed.
 
-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.
+See Container.trap_focus, Widget.can_focus(), Widget.has_focus(), Widget.set_focus() for more information.
 
 
 Other event propagation