Multitouch review 1: event capture

[Matthias Clasen <matthias clasen gmail com>]

API:
  GtkWidget::captured-event signal
  GTK_CAPTURED_EVENT_{HANDLED,STORE}
  gtk_widget_release_captured_events

General idea: The ::captured-event signal is emitted top-down,
starting at the toplevel (somewhat different in the presence of grabs)
all the way down to the widget that received the event. If the
propagation is not interrupted (see below), the next phase is to emit
the traditional ::event signal, starting from the innermost widget,
and then upwards. The per-event signals (like ::button-press-event)
and the ::event-after signal are also delivered as they always have.

toplevel -> ::captured-event
  container1 -> ::captured-event
    container2 -> ::captured-event
       button -> ::captured-event
       button -> ::event
    container2 -> ::event
  ...

Each intermediate ::captured-event handler can declare the event
handled by returning GTK_CAPTURED_EVENT_HANDLED. This stops the
further propagation of the event. Optionally, the handler can request
that the event be store for later replay, with
GTK_CAPTURED_EVENT_STORE. gtk_widget_release_captured_events() can
later be called to release or drop the stored the events. The use case
for store/release is that e.g. GtkScrolledWindow can capture events
that might lead to scrolling, and when it turns out that it was just a
press/release without motion, it
can pass the stored events on to the child widget.

This API looks reasonably straightforward to me, and matches well with
the web model[1]. Questions, comments:

 - When captured events are released, they are not further propagated
via ::captured-event, but directly to the target widget via ::event.
Is that good enough ? It does not allow events to be captured multiple
times, but maybe that is an unlikely enough scenario that it does not
matter...

 - The docs warn about the fact that storing events takes no
precaution about pairedness of enter/leave, etc. There is certainly
some danger that careless picking of events could seriously confuse
the widget 'downstream'. Is there a use case for storing individual
events while letting other pass through ? If not, we could consider an
alternative where you can turn storage of events on/off, but not for
individual events. Would that be better ? Maybe not...

 - The 'release' in gtk_widget_release_captured_events clashes a bit
with the 'release' we have in a bunch of event names:
button-release-event, key-release-event... Probably not a big deal.
And 'replay' does not have quite the right meaning.

- The docs for ::captured-event should explain the interaction with
grabs - in the presence of a grab, the ::captured-event signal is
emitted starting at the grab widget, not the toplevel.


[1] http://www.w3.org/TR/DOM-Level-2-Events/events.html#Events-flow-basic