====== Event types ======
[tbd]
====== Event propagation ======
===== Basic principles =====
[tbd]





===== Focus event =====
<code c++>
  enum FOCUS_EVENTS
  {
      FOCUS_LOST = 0,
      FOCUS_GOT = 1,
  };

  struct FOCUS_PARAMS
  {
      UINT      cmd;            // FOCUS_EVENTS
      HELEMENT  target;         // target element, for FOCUS_LOST it is a handle 
                                // of new focus element and for FOCUS_GOT it is 
                                // a handle of old focus element, can be NULL
      BOOL      by_mouse_click; // TRUE if focus is being set by mouse click
      BOOL      cancel;         // in FOCUS_LOST phase setting this field to TRUE
                                // will cancel transfer focus from old element 
                                // to the new one.
  };
</code>

Let's assume that some element A already has focus and another element B is getting focus.
While setting focus engine sends FOCUS_LOST and FOCUS_GOT events in the following sequence:

First:

  * Element that has focus before (A) will get ''FOCUS_LOST'' (and its parents will get ''FOCUS_LOST | SINKING'').
  * ''FOCUS_PARAMS.target'' in this event points to the new focus candidate element.
  * ''FOCUS_PARAMS.cancel'' at this point can be set to TRUE to canel focus assignment.
  * In this phase (FOCUS_LOST dispatching) ''HTMLayoutGetFocusElement(HWND hwnd, HELEMENT *phe)'' will return reference to old focus element (A).  

Second: 

  * System will set internal variable "current_focus" to the new focus.
  * After this point ''HTMLayoutGetFocusElement(HWND hwnd, HELEMENT *phe)'' will return new focus element (B).

Third:

  * Element that is getting focus gets ''FOCUS_GOT'' (and its parents will get ''FOCUS_GOT | SINKING'').
  * ''FOCUS_PARAMS.target'' in this event points to the old focus element (A).   
  * ''FOCUS_PARAMS.cancel'' has no effect in this case. 

Rationale:

While processing these events applications knows what element is loosing focus and what element is getting focus.