# HG changeset patch
# User Radek Brich <radek.brich@devl.cz>
# Date 1355700274 -3600
# Node ID caf927c3f10b0ccc2989b143fbdb89b349fd28b3
# Parent  f62c8269ded6eae8a979ae7d245aa0e039312741
Update docs.

diff -r f62c8269ded6 -r caf927c3f10b docs/events.rst
--- 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.
+
diff -r f62c8269ded6 -r caf927c3f10b docs/focus.rst
--- a/docs/focus.rst	Sun Dec 16 21:04:03 2012 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-Focus
-=====
-
-Only one widget can have focus at the time.
-Top widget has link to currently focused widget in 'focuswidget'.
-
-Events emitted on change: focus, unfocus
-
-mousedown - focus widget under mouse
-
-tab - focus next child in container (depends on canfocus())
-shift-tab - previous child
-
-hide() -> unfocus
-
-tab/shift-tab into / out off containers?
-trapfocus # if True, tab cycles inside container
-
-widget.hasfocus()
diff -r f62c8269ded6 -r caf927c3f10b docs/index.rst
--- a/docs/index.rst	Sun Dec 16 21:04:03 2012 +0100
+++ b/docs/index.rst	Mon Dec 17 00:24:34 2012 +0100
@@ -14,7 +14,6 @@
    application
    emitter
    events
-   focus
    redraw
    colors
    tableview
diff -r f62c8269ded6 -r caf927c3f10b tuikit/application.py
--- a/tuikit/application.py	Sun Dec 16 21:04:03 2012 +0100
+++ b/tuikit/application.py	Mon Dec 17 00:24:34 2012 +0100
@@ -20,12 +20,15 @@
         self.timeout = []
         self.timelast = None
 
+    def draw(self, screen, x=0, y=0):
+        """Draw the top window and its children.
 
-    def draw(self, screen, x=0, y=0):
+        This is entry point for full screen redraw.
+
+        """
         screen.erase()
         super().draw(screen, x, y)
 
-
     def add_timeout(self, s, func):
         if not len(self.timeout):
             self.timelast = time.time()
diff -r f62c8269ded6 -r caf927c3f10b tuikit/container.py
--- a/tuikit/container.py	Sun Dec 16 21:04:03 2012 +0100
+++ b/tuikit/container.py	Mon Dec 17 00:24:34 2012 +0100
@@ -82,7 +82,6 @@
         if keyname == 'tab':
             return self.focusnext()
 
-
     def on_resize(self):
         super().on_resize()
         for child in self.children:
@@ -90,6 +89,12 @@
 
 
     def draw(self, driver, x, y):
+        """Draw the container and its children.
+
+        This method should not be overriden by subclasses,
+        use on_draw instead.
+
+        """
         if self.hidden:
             return True
 
diff -r f62c8269ded6 -r caf927c3f10b tuikit/widget.py
--- a/tuikit/widget.py	Sun Dec 16 21:04:03 2012 +0100
+++ b/tuikit/widget.py	Mon Dec 17 00:24:34 2012 +0100
@@ -116,6 +116,12 @@
             self.parent._redraw = True
 
     def draw(self, driver, x, y):
+        """Draw the widget.
+
+        This method should not be overriden by subclasses,
+        use on_draw instead.
+
+        """
         if self.hidden:
             return True
 
@@ -188,6 +194,8 @@
     def hide(self):
         '''Hide widget. Convenience method.'''
         self.hidden = True
+        if self.hasfocus():
+            self.parent.focusnext()
         self.redraw()