General principles

Behaviors and event handlers are the way to make html page dynamic. Main purpose of the behavior is to handle various user interface events: mouse and keyboard, timer and drawing events, etc. Event is the representation of some asynchronous occurrence (e.g. mouse click or loss of focus) that gets associated with an html element (targeted at it.)

Physically behaviors are implemented by host application as a function:

BOOL ElementEventProc(LPVOID tag, HELEMENT he, UINT evtg, LPVOID prms);

ElementEventProc is a functional equivalent of WindowProc. SDK contains C++ class event_handler - OO wrapper splitting calls of various event groups (evtg) into separate virtual calls: on_mouse , on_key, on_focus, etc.

Behaviors can be attached by CSS and programmatically in runtime. Any element can have multiple behaviors/event_handlers.

Style definition (CSS) in HTMLayout may contain behavior attribute:

.myclass { behavior:my-button; }

When HTMLayout loads html document it resolves styles of all elements. If some element is getting behavior value then HTMLayout window sends notification HLN_ATTACH_BEHAVIOR to host application with the name of behavior ("my-button" in this case). And host application may provide its own implementation of the behavior.

SDK also contains implementation of the behavior:event_handler C++ class. behavior class has additionally name field and implements list of instances - list of behaviors. Therefore behavior is a named event_handler in HTMLayout.

Propagation of Events.

When an event occurs it is being dispatched. HTMLayout uses standard for HTML sinking/bubbling dispatch mechanism which is quite different from the one Windows uses.

Lets imagine that we have following document:

<p><input type="button"></p>

and user will press mouse button on the input element.

The dispatch is done in two phases: The first phase is called sinking ( or capture ). At this phase event is passed down from root element to the target element.

If user click on the input the event would be first processed by event handler of <html> element, then by <body>, and then by <p> element and <input>.

The second phase is called bubbling. At this phase the event is passed back up the tree to the root element. For the example above, elements would be processed in the following order: first <input> element, then <p>, then <body> and last <html> element.

If element has multiple event handlers assigned then their ElementEventProcs will be called in the order of handler assignment.

Sinking phase is marked by PHASE_MASK:SINKING bit of cmd field in event parameters structure. See file sdk/include/htmlayout_behaviors.h. Thus if you need to handle mouse down event in sinking phase (before it will be dispatched to children) you will use:

case MOUSE_DOWN | SINKING : ... break;

and if you want to handle MOUSE_DOWN if it was not processed by any child you will do following:

case MOUSE_DOWN : ... break;

Therefore event_handler associated with some element will receive:
  1. all events targeted at it or contained elements in sinking phase (with SINKING flag);
  2. all events targeted at this element and all non-consumed by its children events in the bubbling phase.
Event is considered as consumed if correspondent ElementEventProc in the chain will return TRUE while handling it. In this case HTMLayout stops dispatching it further. Thus if for example event_handler of the root element will always return TRUE for some event in sinking phase then no one descendant of the root will not even know about this event occurrence.

Builtin HTML Controls.

Built-in input controls in HTMLayout are plain DOM elements. Period.

Different input elements have different behaviors implemented guess by what? - by set of the behaviors of course. Take a look on master style sheet of HTMLayout. This CSS (Cascading Style Sheet) table is used by HTMLayout for assigning behaviors to particular DOM elements and for definition of their rendering styles.

Having behaviors declared and assigned by CSS practically means following:

  1. You can design your own behavior which will replace builtin behavior. It is enough to say e.g. :
    button { behavior:my-button; }
    and all <button>s will automagically get your own application specific behavior.
  2. You can assign standard behaviors to any DOM element of your choice. For example CSS declaration:
    td.button { behavior:button; }
    will assign button behavior for all cells <td class="button"> in some table.
  3. CSS and its cascading rules allows now to define not only rendering style of the element but also "behavioral style" of element.

Standard Behaviors.

List of currently supported behaviors is locatted at http://www.terrainformatica.com/wiki/h-smile/built-in-behaviors/start .




HTMLayout distribution is not available. Use Sciter Engine instead.