Event handling
==============

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().


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.

::

  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.