The event API debate

Having reflected on this somewhat, I think we should have one of those
healthy debates on the direction of the widget API.

Basically, there's two schools of thought on this:

(1) The widget API is an abstraction of the core API.  This means
    there are two APIs - one for the widgets and one for the core -
    and this is the approach of the Lithium-based widgets.

(2) The widget API should make use of the core API where possible.
    With the new two-way event model introduced for keyboard and
    mouse events in Nitrogen, it is possible to _control_ the core
    API meaning that the user need only be aware of 1 event API;
    the one listed in the reference.

On the face of things, one event API is preferable to two APIs.  But I'm
not sure it's that simple.

With the single API, whilst there is only 1 set of event triggers that
need be known, there is actually a subtle difference between how said
API behaves in certain circumstances.

For instance, a widget that traps KeyPressed will only receive the event
if said widget is focused.  But a box that traps KeyPressed will receive
it regardless - unless said KeyPressed event is trapped and blocked
elsewhere, which may well be caused by the widget focus model.  This is
a little confusing - one trigger, multiple behaviour possibilities.

Also, the fact that there would only be one API is a bit of a fallacy. 
Whilst this may apply to the event API - since people would be using
reference event functions - there would still need to be a separate
widget API to enable easy theming.  The classic example would be the
clickable/focusable model, where the visual state of a widget is
determined by a trigger of active/hover/normal and whether said widget
is in a focused or enabled state.

With the two APIs, there is a clear distinction between what to expect. 
Also, other than for basic layout, the core API just wouldn't be needed
by your average developer since they would just be using the widgets and
the widget API.  The widget API is much simpler - eg 'action' vs
'Press1/Release1/Click1' - and easier to understand.

I actually prefer it the way we were doing things before.  I do think
that the two-way event model will bring much simplification to the
widget library code.  I don't think it means we should do away with a
widget API which is meant to be simple and easy for a newcomer to pick
up.  For me, the core API is a little intimidating for somebody new to
XWT.

Here's my subject summary of the two methods:

(1) The widget API is an abstraction of the core API

    Pros:
    - Two simple distinct APIs for simple development needs;
      widget event API and the core layout API
    - API behaviour is always the same
    - No limitations on widget API expression
    - Very easy for the uninitiated

    Cons:
    - Two APIs which means two places to look
    - Doesn't make _full_ use of two-way event model

(2) The widget API should make use of the core API where possible

    Pros:
    - Single API for simple development needs
    - Makes full use of the two-way event model

    Cons:
    - Varied behaviour for some API elements
    - Still two APIs needed eg for non-represented visual triggers
    - Limited by the way the core API is expressed
    - Core API is limiting

Opinions _please_ since the path that we take will be virtually
irreversable and hence it needs to be the right one.

- Charlie

-- 
Charles Goodwin <[email protected]>
Member of the XWT Foundation

The future of the net - www.xwt.org