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
--------------

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

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

 * 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.

See Container.trap_focus, Widget.can_focus(), Widget.has_focus(), Widget.set_focus() 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.